[Bug] Served index.html missing Cache-Control: no-store — cached documents break boot after rebuild

[sogoodayo]

Environment

• deepseek-harness 0.1.5, dsh web dev flow (tsx source mode)
• Any Chromium browser (Edge/Chrome heuristic caching)

Reproduction

1. Start dsh web, open the printed URL in a browser — the app boots; the browser now caches the / document (its 200 response carries no Cache-Control; only the 303 token exchange has no-store).
2. Rebuild the client bundles (any code change → new content-hash rev) or simply restart against a different build, so the old bootstrap URL /plugins/??@deepseek-ai/dsh-client-modules/client.js&rev=<old> no longer exists (server 404s it; only the current and previous generation are retained).
3. Reopen / in the browser. It serves the cached document, whose bootstrap <script src> 404s, so window.__ModuleLoader__.load(...) never runs.
4. The boot page renders:

HARNESS
Failed to load plugins
client-modules: HTML did not preload @deepseek-ai/dsh-client-modules/client.js

Deterministically reproducible by serving a captured index.html with a bogus rev (bootstrap request → 404 → exactly the error above).

Expected

The injected index document is never served from cache — its inline rows reference content-hash rev URLs that a rebuilt server drops.

Actual

packages/host/frontend-static/src/index.ts (serveStatic) answers the index with only content-type:

res.writeHead(200, { 'content-type': type })

Chromium applies heuristic caching to the document, so every rebuild/restart can brick the page until the user hard-refreshes (Ctrl+Shift+R) — and session-restored tabs keep hitting it indefinitely.

Suggested fix

Send Cache-Control: no-store for the index document (assets under /assets/ already carry content-hashed names and can keep long-lived caching):

const caching = target === distRoot || target === distIndex
  ? { 'cache-control': 'no-store' }
  : {}
res.writeHead(200, { 'content-type': type, ...caching })

Verified locally: header present, packages/host/frontend-static/tests/frontend-static.spec.ts still passes, and the stale-document failure mode is eliminated.

[argszero]

Confirmed on every mechanical point, and I have one structural addition that changes the fix's shape rather than its verdict: there are two index-serving paths in the tree, and only one of them is in frontend-static.

What checks out

• serveStatic sends exactly one header (packages/host/frontend-static/src/index.ts:104), and it is shared by every 200 — index and asset alike.
• Your precedent is in-tree and argues your case: every other response in the same auth flow carries no-store (packages/client/connection/src/browser-auth.ts:257/269/306), and open-in-app marks its live responses no-store (packages/host/open-in-app/src/index.ts:95).
• pathname === '/' really does reach the target === distRoot arm, so your condition is the correct one for both accepted index entries. Worth naming the arm's composition for whoever edits this: target === distRoot matches /, /?query, and — by prefix convention — /index.html; packages/host/frontend-static/tests/frontend-static.spec.ts:144 pins exactly that set.
• Assets are built as assets/[name]-[hash].js (apps/web/vite.config.ts:169, :182, :186), so per-path conditional caching is decidable from the request path.
• The stale bootstrap is real rather than hypothetical: /plugins/??…&rev=<hash> (packages/client/modules/src/index.ts:208) is answered from the current generation with exactly one prior generation retained, and that retention is documented as a race window (:500-501, fallback :982). No service worker exists anywhere in apps/web or packages/client, so the document cache is the only stale-document source — the fix has no alternative target.

One refinement to your suggested condition: I would keep target === distIndex alongside target === distRoot, as you have it, rather than distRoot alone. The distIndex arm is reachable only through the prefix table, which is only claimed when distIndex === join(distRoot, 'index.html'); if a deployment ever configures a differently named index document, distRoot alone would silently stop covering it.

★ The addition: the desktop path never enters frontend-static

apps/desktop-host/src/index.ts:185-215 builds its own assetHandler over the same dist and renders the index itself: renderIndex() at :189-194 returns new Response(body, { headers: { 'content-type': … } }) with no cache-control, and :207 routes both / and /index.html into it. That response crosses a different transport (a connection fetch handler, not the node:http fallback seat), so fixing serveStatic leaves the desktop app exactly as affected as it is today.

The two paths also disagree on semantics even now: desktop treats /index.html as an index (authenticated, injection-rendered), while serveStatic reaches it only through the prefix arm described above. The requested header is identical in both cases, so I would make both responses say the same thing rather than fix one and leave the other silently different.

On the plugin axis — I checked whether this half could be carried by a plugin instead, since that is my usual first move. Index content is pluggable (webserver/index-inject rows, tapIndex), but response headers are not: taps and rows both run inside the body renderer, and the desktop renderIndex constructs its Response object itself. A plugin could patch globalThis.fetch (desktop HTTP routing goes through the software network stack) to re-wrap headers on those two paths, but that is global patching for a one-line fact — a strictly worse contribution than asking for the header in both places. So on this one I would stay upstream.

Two smaller notes

• The patch as written leaves assets header-less. Chromium's heuristic caching applies to them just as it does to the document, so their behaviour is unchanged either way, but an explicit public, max-age=31536000, immutable for /assets/** is cheap and matches how the module bundles already describe themselves (IMMUTABLE_CACHE, packages/client/modules/src/index.ts:164). The usual objection to immutable — pinning a relative URL resolved against the document — cannot apply here: apply() injects <base href="/"> into the served form (packages/host/frontend-static/src/index.ts:122).
• No test will catch a regression here. Every assertion in the spec reads only {status, type, body} (packages/host/frontend-static/tests/frontend-static.spec.ts:131, :151, :165, :183), and the headline test's title — "preserving HTTP error semantics" — is precisely where a cache header belongs. A plugin installing a tapIndex never touches headers either (:143-149). This is the same shape as the payload-smoke thread next door ([Bug] 0.1.5-rc.2 桌面端 prepare:dsh 必然失败：payload smoke 断言已被移除的 fs-ext，无法产出 resources/dsh #6372): the property that would catch the bug is not among the properties asserted, so I would add the header assertion to the existing test, not only to the implementation.

Boundaries

All of the above was read from c291e7961a (= tag dsh-v0.1.5-rc.2); I did not run dsh web or reproduce the stale-document sequence in a browser. Your deterministic reproduction (captured document with a bogus rev) is the behavioural evidence — the line numbers and predicates above are mechanical facts of that tree.