The live-test reload lane: a shipped build must be one 'Reload Window' away — and the panel should prompt when one is live

[aarontrowbridge]

The rule of thumb (the product requirement, from the fleet's daily use)

The fleet topology is the only proper test rig for Amicode: changes get put through their paces on the real hub (tunnel, frontdoor, shelf, panel) before they merge. Which means the last mile of every agent deploy is the same ceremony: the agent ships the dist, the developer reloads the window they're developing in, the new feature is there. That ceremony must be:

1. Reliable — reload-the-window picks up the freshly shipped build, no cache surgery, no stale ghosts.
2. Prompting — the panel tells the developer a new build is live and offers the reload. The agent shouldn't have to nag; the system should know.

Today it is neither — verified live twice this week.

The evidence

• The 2026-09-24 harness-switcher deploy (feat(app): the harness switcher in the chat box — composer control riding the solver-mode trio, entitlement-gated, harness-aware degradation #1549/feat(app): the harness switcher in the chat box (#1549) #1550) did everything right at the ops layer — built, staged, swapped, bounced, verified — and then the developer's reload served the OLD app anyway: VS Code's webview service worker caches the panel iframe's navigation, so the freshly shipped index never reaches the frame until the outer webview's cache is cleared by hand (the cache-surgery class). This is fix(extension): cache-bust the panel iframe src per app-dist build — the outer webview SW serves a stale index across ships (every ship needs a reload-window + cache clear to land) #1459's diagnosis, and it makes "reload to test" false precisely when it matters most — right after a deploy.
• No prompt exists anywhere. The agent's last message has to tell the developer to reload (the deploying campaign's actual last words on 9-24 were "reload your window, open the panel…" — the agent doing the UI's job). Nothing watches the served dist version, so a ship lands silently and the developer discovers it whenever.

Why this is tractable today, with zero hub-side changes

Two facts make the whole lane land in the extension alone:

• The extension host's fetches bypass the webview service worker. The SW sits in the webview layer; the host process fetching the panel origin's / gets the true current index.html every time. So the host can reliably detect the served dist's version (its index-<hash>.js asset reference) even while the framed app is stuck on the old one.
• The version is already mechanically present: index.html references index-<buildhash>.js. Same derivation the shelf would expose; no service route needed for v1 (a clean GET /amicode/app-version route can be the follow-up nicety).

The design (subsumes #1459's stamping requirement)

packages/extension/src only — a new small module + chat_panel.ts:

1. Derive (pure): distBuildIdFromIndexHtml(html) → the index-<hash>.js build id, or undefined on no-match (graceful: an unparseable origin doc never breaks anything).
2. Stamp (the fix(extension): cache-bust the panel iframe src per app-dist build — the outer webview SW serves a stale index across ships (every ship needs a reload-window + cache clear to land) #1459 fix, in renderHtml + the transition-HTML path): at panel construction, the host fetches the origin doc, derives the build id, and sets amicode_build=<id> on the iframe src alongside the existing param convention (colorScheme, auth_token, amicode_hide_project, …). A new dist = a new URL = the SW's navigation cache can never serve the old app across ships. The param must not disturb the credential carriage (auth_token) or any existing param. Failure to fetch/parse = no stamp = exactly today's behavior (honest degradation).
3. Prompt (the new ceremony): the host polls the same derivation on a slow interval (e.g. every 3 minutes; cheap — one small GET, and pause when the VS Code window is unfocused is a nice-to-have, not required). When the served build id ≠ the id the loaded panel was stamped with, show the information message: "Amicode: a new app build is live (<id>). Reload Window to pick it up." with a Reload Window button → workbench.action.reloadWindow. One prompt per version change (re-prompt only when another new build lands), never a nag loop on the same version.
4. The re-frame path (origin switches) re-derives and re-stamps so fleet switches get the same guarantee.

Acceptance shape

• A freshly shipped dist + Reload Window → the panel runs the new build, no cache surgery — the amicode_build param changed and the frame fetched fresh.
• While the panel is open and a new dist ships, the developer receives exactly one prompt with the new build id; clicking reloads the window; declining means no more prompts for that version.
• The credential (auth_token) and every existing param survive the stamping.
• Unparseable origin docs / fetch failures: no stamp, no prompt, no error surfaced (today's behavior, honestly degraded).
• Unit tests on: the derivation (real index.html shapes, the no-match leg), the stamp (param addition, preservation of existing params, both HTML paths), and the change-detection logic (prompt-once-per-version semantics).

Relationship to #1459

#1459 is the stamping half (the cache-bust) — this issue keeps its diagnosis and lands it as part of the full lane, adding the detection + prompt that make it a ceremony rather than a mechanism. Closing this closes #1459's requirement.

Relationship to #1552/#1553

The interrupted-session re-dispatch makes the campaign side of deploys survivable; this makes the developer side of deploys effortless. Together they turn the sanctioned bounce + ship into a complete, safe live-test loop: ship → prompt → reload → test.