[PWA] Hoist the generated worker's importScripts above the AMD factory and pin the forced activate sweep at browser level (the #2475 'window open' red was a test observation race)

[Chris0Jeky]

What

The forced static-cache re-sweep that PR #2416 (closes #2411) placed inside event.waitUntil on activate in frontend/taskdeck-web/public/api-cache-cleanup.js never executes in the generated worker. The activate listener is attached from inside vite-plugin-pwa's asynchronous AMD factory (the file is pulled in by importScripts inside the factory's promise continuation), so the lifecycle event has already been dispatched by the time the listener exists. The install listener attached the same way does receive its event; the activate one does not, on every run.

Consequence on current main: the install-to-activation re-poisoning window that #2411's review identified as HIGH is still open. A static-cache entry that the old (#2350-era) worker admits into taskdeck-static-assets after the evaluation-time sweep and before the replacement activates survives the migration. The evaluation-time sweep with its one-time marker is the only sweep that runs.

Evidence (2026-09-05, bounded attempt under #2475, branch issue-2475/pwa-activation-race)

• Deterministic browser case tests/e2e/pwa-proof-strict.spec.ts (gated by TASKDECK_E2E_PWA_PREVIEW=1, playwright.pwa-proof.config.ts, self-started backend on 5031 and vite preview on 4193) holds the window open instead of racing into it: registerType: 'prompt' parks the installed replacement in waiting until the page sends taskdeck:skip-waiting, so the seed is written by the OLD worker's own CacheFirst handler from a real 200 response, strictly after the marker cache exists and while registration.waiting is non-null and the policy handshake still answers legacy-api-cache-retired.
• Against unmodified main: 3 of 3 runs red at the final assertion, PROOF raceEntriesAfter = ["http://localhost:4193/icons/icon-192x192.png?td-race-seed=1"].
• With a candidate hook appended to the cleanup script (self.serviceWorker statechange to activating/activated calling retireCaches({ force: true })), rebuilt: 2 of 2 runs green, raceEntriesAfter = []. The hook was reverted; the branch touches no production file.
• Instrumented build (reverted): caches.keys() after a completed migration contained td-diag-evaluated, td-diag-state-installing, td-diag-install-entered, td-diag-state-installed, td-diag-state-activating and never td-diag-activate-entered or td-diag-activate-swept.
• This reproduces the __proofActivateFired:false measurement recorded on PR Keep configured API paths out of PWA runtime caches #2416 on 2026-09-04; the consequence was not drawn then, and the repair for the window was placed inside the same inert listener. The generated-worker unit tests dispatch activate themselves against a fake CacheStorage, which is why they pass.
• The case is committed with test.fail() on that branch (b51002b) so the gated lane stays green until the production repair lands; it flips the lane red the moment the case starts passing, which is the removal signal.

Ask

1. Bind the forced re-sweep to something that actually fires in the generated worker, and prove it in a real Chromium, not with a dispatched fake event. Candidates, in order of preference: emit the cleanup script's lifecycle listeners at top level of the generated worker (workbox importScripts placed before the AMD define, or the injectManifest strategy with a hand-written worker source) so activate is attached synchronously and event.waitUntil semantics are real; otherwise the statechange hook, accepting and documenting that it cannot extend activation.
2. Keep waitUntil semantics if at all possible: a sweep that runs after clients.claim() leaves a window where the new worker already controls the page.
3. Adopt the branch's deterministic case as the regression (remove test.fail() once green), make the generated-worker unit tests stop dispatching activate by hand or make them run the emitted worker in a way that exercises the real attachment order, and correct docs/platform/PWA_OFFLINE_BEHAVIOR.md, the PWA row of autodoc/AGENT_INDEX.md and the comment block in public/api-cache-cleanup.js (lines 104-115 already record the inertness; the file's own doc still claims activation fails on error).
4. Record the finding on [Security][PWA] Static-asset runtime cache admits API responses when VITE_API_BASE_URL is nested under /assets/ or /icons/ #2411 and [Security][PWA] Remove authenticated API responses from the service-worker cache #2350; the readiness view's PWA isolation claim depends on it.

Refs #2475, #2411, #2416, #2350. Priority I: this is the v0.3 PWA isolation blocker reopened.

[Chris0Jeky]

[Claude lane claim v2]
lane: beta-platform-integrity (session taskdeck-beta-a5)
issue: #2639
base: origin/main 9cf28bb
residual acceptance: all four asks are open. Slice: bind the forced static-cache re-sweep to a lifecycle hook that actually fires in the generated worker, preferring a shape that keeps event.waitUntil semantics (listeners attached at top level of the emitted worker); adopt the deterministic browser case from branch issue-2475/pwa-activation-race (b51002b) as the regression with test.fail() removed once green (3 consecutive local passes, red again with the repair reverted); make the generated-worker unit tests exercise the real attachment order or stop dispatching activate by hand; correct docs/platform/PWA_OFFLINE_BEHAVIOR.md, the PWA row of autodoc/AGENT_INDEX.md and the cleanup script's own comments; record the finding on #2411 and #2350.
owned paths/modules: frontend/taskdeck-web/public/api-cache-cleanup.js; frontend/taskdeck-web/vite.config.ts (workbox importScripts placement only, if that is the fix); frontend/taskdeck-web/tests/pwa-generated-worker.spec.ts; frontend/taskdeck-web/src/tests/pwa/**; frontend/taskdeck-web/tests/e2e/pwa-proof-strict.spec.ts; docs/platform/PWA_OFFLINE_BEHAVIOR.md; autodoc/AGENT_INDEX.md (PWA row)
shared-path leases: service-worker/PWA policy and frontend/taskdeck-web/vite.config.ts (lane-owned hot path; no other open PR touches them; the runtime cache predicates in src/pwa/runtimeCachePolicy.ts, the router and the session store are not touched)
parallel-safe work: PR #2619 awaiting CI
open PRs/branches/review threads checked: no open PR touches the PWA worker; branch issue-2475/pwa-activation-race carries the test only; PR #2416 (merged) is the record this corrects
human or decision gates: none for the repair; the readiness view's PWA isolation claim is the coordinator's to re-state
status: active

[Chris0Jeky]

[Claude lane correction] beta-platform-integrity, issue #2639.

The premise of this issue did not reproduce. The fix worker re-measured before changing anything, with breadcrumb caches written at script evaluation and as the first statement of the activate handler in public/api-cache-cleanup.js, rebuilt without any repair, Chromium 151.0.7922.34 via Playwright 1.62.1:

• first install on a fresh origin: activateEntered = true, 3 of 3 runs;
• the waiting-then-skip-waiting migration path (the E2E case's own flow): activateEntered = true;
• the worker killed while waiting (CDP ServiceWorker.stopAllWorkers) and restarted straight into activation: activateEntered = true, 3 of 3 runs.

So the forced retireCaches({ force: true }) inside event.waitUntil on activate has been running since PR #2416 merged. The install-to-activation re-poisoning window is closed on main, as #2416 recorded.

Why the #2475 case was red on main. It was an observation race in the test, not in the worker: the case asserted the static cache as soon as the policy handshake answered taskdeck-api-cache-policy-v2, and the browser swaps the active worker (so the new worker's message listener answers) before the activate event's waitUntil sweep has finished. Measured four ways with the case alone: pre-hoist plus a wait for registration.active.state === 'activated' passes; pre-hoist without the wait fails 2 of 2; hoisted with the wait passes 3 of 3; hoisted without the wait fails 3 of 3. With the wait, the case is red 2 of 2 only when the forced sweep itself is reverted to the one-time evaluation sweep, which is exactly the regression #2475 asked for. The original __proofActivateFired: false measurement on PR #2416 is not explained by this work; it is recorded as a disagreement, not reproduced.

What PR #2660 ships instead. Hardening, not a repair: a fail-closed post-build rewrite (src/pwa/hoistWorkerImportScripts.ts, applied from vite.config.ts) moves the emitted importScripts("api-cache-cleanup.js","share-target-handler.js") call to offset 0 of dist/sw.js, ahead of vite-plugin-pwa's AMD factory, so the cleanup script's lifecycle listeners are attached synchronously and no longer depend on the factory's microtask ordering (which no specification promises); a structural generated-worker test pins that placement (red on the pre-hoist build); the E2E case lands without test.fail() and with the correct wait; the generated-worker unit tests no longer claim a dispatched fake activate proves attachment; the cleanup script's comments, docs/platform/PWA_OFFLINE_BEHAVIOR.md and the AGENT_INDEX PWA row state the measured behaviour, including that a rejected activate waitUntil does not abort activation.

Retitling this issue to match; Priority I was an over-statement on my part and it is Priority II hardening. It closes when #2660 merges. The readiness view and STATUS caveats I asked for have been withdrawn with the coordinators.