pwa(sw): a second tab loading during another tab's first-ever install can still see one unwanted reload

[qnbs]

Context

Found during PR #613's review (fixing #585 — the SW controllerchange handler no longer reloads on an ordinary first-ever install). A narrower, compound-timing residual remains that even a fully-corrected live Service Worker API check cannot close.

The scenario

register-sw.ts's registerServiceWorker() runs via window.addEventListener('load', registerServiceWorker) — i.e. at the load event, not at navigation time. Its hadControllerAtLoad snapshot (!!navigator.serviceWorker.controller) is read at that point.

If Tab A is the first tab to ever visit an origin and its install→activate→clients.claim() sequence completes while Tab B (also loading for the very first time) is still parsing/loading its own page, clients.claim() sets Tab B's .controller property immediately — before Tab B's own load event fires, and therefore before Tab B's own registerServiceWorker() (and its controllerchange listener) ever runs.

Two independent consequences:

1. Tab B's controllerchange event (from Tab A's claim) has no listener yet when it's dispatched — it is not replayed, so it's silently missed (same class as the listener-ordering gap PR fix(pwa): skip the controllerchange reload on a first-ever install (#585) #613 already closed elsewhere, but this instance happens before registerServiceWorker() even starts).
2. When Tab B's load handler eventually runs, hadControllerAtLoad reads true — because .controller was already set by Tab A's claim — even though this is still, in reality, the very first activation this origin has ever had. Tab B's classification logic (correctly, given only this signal) concludes "this is a genuine update," so if Tab B's page code ever reacts to that state, it treats what was actually the shared first-ever install as if it were a returning-visitor update.

Why not fixed in #613

Closing this fully requires a signal that doesn't depend on live, per-tab Service Worker API timing at all — e.g. a persistent flag (localStorage, written the moment any tab first observes a genuine claim) checked synchronously before any Service Worker API call. That is a materially different design from the live-registration-state approach #613 already converged on through several rounds of narrower fixes, and disproportionate to add speculatively without a concrete reproduction proving it matters in practice.

Impact

Extremely narrow: requires two tabs open on the very first-ever visit to the origin, with one tab's own page-load time exceeding the other tab's complete install+activate+claim pipeline (a real network round-trip for precaching). Worst case is a single unwanted reload for the second tab on that one shared first visit — not a recurring or update-blocking defect, unlike the original #585 bug this PR fixes.

Suggested direction (not designed here)

A persistent, storage-backed "this origin has activated a service worker before" flag, written by the first tab to observe any real controllerchange, checked synchronously (no Service Worker API await) before falling back to the current live-state heuristic. Needs its own design pass, not a rushed addition to #613.

[qnbs]

Update from PR #613's later commits: a persistent, storage-backed flag (`worldscript-sw-installed:`) was added to close several related live-API classification races found in further review — including this issue's own scenario in all but its very first occurrence.

The flag is written the moment any tab observes a genuine controllerchange for this app's own scoped worker, and checked synchronously before any Service Worker API call. Once written, all subsequent loads for that browser+scope classify instantly and correctly, bypassing the live-heuristic (and this issue's timing dependency) entirely.

What remains open here: the flag doesn't exist yet on a browser's absolute first-ever encounter with this app (or its first encounter after this exact code ships to an existing install base). This issue's exact race is still possible in that one narrow, self-healing window — it cannot recur for that browser+scope once the flag is written, whether via this exact race's outcome or any other genuine claim. Keeping this open to track that narrower residual; no code change needed here beyond what already landed.

[qnbs]

Further finding from PR #613's continued review (chatgpt-codex-connector), confirming this issue's persistent-flag caveat above with a second, distinct manifestation of the same root cause — and confirming the persistent flag does not close this class of race, not even partially, for a truly first-ever concurrent wave.

New variant — via getRegistration()'s live registration snapshot, not via an early controller claim.

When two fresh tabs register together for the very first time this origin has ever had a service worker, Tab A's install→activate can complete while Tab B is still awaiting its own getRegistration(basePath) call. ServiceWorkerRegistration is a single object shared by scope across all tabs, and its .active state transitions live — so Tab B's snapshot can read active.state === 'activated' (Tab A's now-fully-activated worker) even though clients.claim() has not yet claimed Tab B itself. refineFirstInstallClassification then classifies Tab B as a returning visitor with a genuine update pending, and Tab B's own first-ever claim gets replayed as an update — reload, not the first-install exemption.

Why the persistent flag doesn't help here (or in this issue's original scenario): the flag only has evidentiary value once some tab has already written it via a real, completed prior claim. In a genuinely first-ever wave, by construction nothing has written it yet — every racing tab is asking "has this ever happened before?" at the same moment the answer is first becoming "yes." No snapshot, live or persisted, resolves that instant correctly for every racing tab.

What would actually close this class: real cross-tab coordination during the race itself — e.g. a BroadcastChannel-based "install wave" announcement so a tab can learn "another tab already claimed this exact wave" before finalizing its own classification. That is new architectural surface, not a targeted bugfix, so it belongs in its own PR under this issue rather than folded into #613's already-large convergence.

Disposition: both variants remain correctly scoped to this issue, not #613. #613 closes #585 for the ordinary (non-concurrent-wave) cases, which is the overwhelming majority of real-world first installs — a single-tab first visit, or a returning visitor's update, with or without a force-refresh. This issue's residual is the multi-tab-same-instant edge case only.

[qnbs]

Queue / execution status — 2026-09-05

Priority: P0 in P0-C is an execution-order decision, not severity inflation. Preserve the issue's current impact truth: this is an extremely narrow simultaneous-first-visit timing class whose worst case is one unwanted reload in the second tab.

When P0-C reaches this issue, prefer reuse of the shared #480/#485 multi-context/install-update coordination and a durable/shared first-activation-history contract. Do not restart the #613 pattern of adding progressively narrower local register-sw.ts heuristics on every review finding.

Required distinction remains:

• origin has never completed WorldScript SW activation;
• this tab already has a controller only because another concurrent first-visit tab just completed the shared first activation;
• genuine returning-user update.

Close only with deterministic two-tab first-install timing evidence plus normal returning-update regression coverage.

[qnbs]

Live triage 2026-09-06: keep P0. register-sw.ts awaits flushLatestStateThenReload() before a visible-tab reload, and the focused tests prove the ordering. However, flushLatestStateThenReload() catches a rejected or 8-second timed-out flush and still calls window.location.reload(); the hidden-tab visibilitychange path also reloads without awaiting or repeating a flush. The current evidence therefore does not prove no acknowledged-data-loss path. #614 remains coupled to the #480/#485/#518 lifecycle/data-integrity work until a concrete two-tab first-install proof closes this residual safely.