fix(debug): A33.1 SAVE-ack race — gate on race-free fresh-archive signal

Root cause: driveA33's A33.1 hard-gated on the chrome.runtime.sendMessage
SAVE_ARCHIVE callback ack. After the Puppeteer CDP worker.close() SW kill,
the SAVE_ARCHIVE message wakes a fresh SW instance; that instance runs the
multi-step saveArchive() pipeline (offscreen video-keepalive port
re-establishment + REQUEST_BUFFER round-trip + rrweb collection + zip
build). The harness's original sendMessage response port has its own MV3
lifetime — on a 5-min-aged SW the pipeline INTERMITTENTLY outruns it,
surfacing chrome.runtime.lastError "message port closed before a response
was received". The archive is still written correctly every time, which is
why A33.2/A33.3 always passed (Plan 04-05 full-mode UAT: A33.1 FAIL while
A33.2/A33.3 PASS at 1.56 MB). A33.1 was gating a CI assertion on a
best-effort transport ack with inherent MV3 non-determinism.

Fix (harness-side only, Option A — race-free reframe): A33.1 now gates on
the durable race-free signal — a fresh archive on disk — via the canonical
snapshotExistingZips + pollForNewOrUpdatedZip helpers (also used by
driveA12/A13/A27). The sendMessage ack is demoted to a soft non-gating
diagnostic. This is exactly the signal the proven-reliable spike already
uses. A33.2/A33.3 substantive checks are intact and now read the verified
fresh zip. No new symbol; FORBIDDEN_HOOK_STRINGS unchanged at 12. The SW
SAVE_ARCHIVE handler is a correct MV3 async pattern — no production change.

Verified: full-mode A33 (genuine 5-min idle) 3/3 GREEN; skip-mode UAT
35/35 GREEN; tsc + build:test exit 0; vitest 184/184.

Debug session: .planning/debug/a33-save-ack-race.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.planning/debug/a33-save-ack-race.md

@@ -0,0 +1,199 @@
+---
+status: resolved
+trigger: "A33.1 SAVE_ARCHIVE-ack flake — Plan 04-05 full-mode UAT showed 33/35, bailed at A33.1 (saveResult.success===false) while A33.2/A33.3 PASSED (1.56 MB video survived worker.close() SW kill)"
+created: 2026-05-22T11:10:39Z
+updated: 2026-05-22T13:35:00Z
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - reflects NOW -->
+
+RESOLVED. Root cause: driveA33's A33.1 hard-gated on the chrome.runtime.sendMessage
+SAVE_ARCHIVE callback ack — a best-effort MV3 transport signal that intermittently
+surfaces chrome.runtime.lastError ("message port closed before a response was
+received") at the worker.close() -> SW-respawn boundary, even though saveArchive()
+completes and the archive is written every time. Fix (harness-side only, Option A):
+A33.1 reframed to gate on the durable race-free signal — a fresh archive on disk via
+the canonical snapshotExistingZips + pollForNewOrUpdatedZip helpers; the sendMessage
+ack demoted to a soft non-gating diagnostic. A33.2/A33.3 substantive checks intact.
+Verified: full-mode A33 3/3 GREEN (genuine 5-min idle); skip-mode UAT 35/35 GREEN;
+tsc + build:test exit 0; vitest 184/184; Tier-1 FORBIDDEN_HOOK_STRINGS 12.
+NOT a production bug — SW SAVE_ARCHIVE handler is correct; no src/ change.
+
+next_action: none — resolved, committed.
+
+reasoning_checkpoint:
+  hypothesis: "driveA33 line 2661 makes A33-overall-pass require saveResult.success===true. After worker.close(), the SAVE_ARCHIVE callback channel (port bound to the SW alive at send time) closes before the freshly-woken SW instance resolves sendResponse — surfacing chrome.runtime.lastError 'message port closed before a response was received' — even though saveArchive() runs to completion and chrome.downloads writes the archive."
+  confirming_evidence:
+    - "Plan 04-05 full-mode UAT 33/35: A33.1 FAIL (success=false) while A33.2/A33.3 PASS (actual 1565516 bytes) — observed directly in 04-05-SUMMARY lines 311-321."
+    - "src/background/index.ts:1040-1044 SAVE_ARCHIVE handler is correct: returns true synchronously + always calls sendResponse(result). No production bug — eliminates Phase-2 candidate (b)."
+    - "saveArchive() (src/background/index.ts:906+) is slow: tabs.query + captureScreenshot + getVideoBufferFromOffscreen + GET_RRWEB_EVENTS round-trip + createArchive — ample window for the original port to tear down before sendResponse."
+    - "The spike (tests/uat/spike-a33-sw-persistence.ts:263-332) uses the IDENTICAL dispatch but does NOT gate on saveResult.success — pass/fail is purely videoSize>floor. Spike is the proven-reliable methodology; driveA33 diverged."
+    - "A33 is the ONLY SAVE-ack check dispatched immediately after worker.close(). A24.1/A25.1/A27.1/A29.1/A30.1/A31.1/A34.1 all gate on the ack reliably because the SW is alive+stable when they dispatch — confirms the race is specific to the post-kill respawn boundary."
+  falsification_test: "Run the fast-repro 3-5x. If A33.1's success is ALWAYS true (never flakes) AND videoSize is always large, the hypothesis is wrong (the ack is reliable). If A33.1 flakes while videoSize stays large, hypothesis confirmed."
+  fix_rationale: "Option A — reframe A33.1 to a race-free signal (poll downloadsDir for a fresh archive within timeout T, the same race-free signal A33.2/A33.3 consume). The sendMessage ack becomes a soft diagnostic logged but not gated. This addresses the root cause: A33.1 was measuring a best-effort transport ack instead of the durable proof (archive written). A33.2/A33.3 substantive checks stay intact."
+  blind_spots: "Whether the flake is 100% reproducible or intermittent — fast-repro will quantify. Whether the fast 20s idle changes SW lifecycle vs the real 5-min (SW idle eviction does NOT fire under Puppeteer CDP attach per Chrome devrel, so worker.close() is the only eviction either way — the race boundary is identical). Will confirm with genuine 5-min runs."
+
+## Symptoms
+<!-- Written during gathering, then IMMUTABLE -->
+
+expected: A33 full-mode (SKIP_LONG_UAT unset) — all three sub-checks GREEN. A33.1: saveResult.success===true. A33.2: video/last_30sec.webm size > 0. A33.3: video size > 100 KB.
+actual: Plan 04-05 full-mode run showed 33/35 — bailed at A33.1 (saveResult.success===false) while A33.2 and A33.3 PASSED. The 1.56 MB video buffer survived the worker.close() SW kill; archive written correctly.
+errors: saveResult.success === false at A33.1. Suspected chrome.runtime.lastError: "message port closed before a response was received" (TBD verbatim).
+reproduction: Run full-mode UAT (SKIP_LONG_UAT unset) — A33 runs the real 5-min idle + SW kill via Puppeteer worker.close(), then dispatches SAVE_ARCHIVE via chrome.runtime.sendMessage with a callback.
+started: First observed Plan 04-05 full-mode UAT run. A33 harness assertion shipped in Plan 04-08. Plan 04-08 verified A33 only in skip-mode (GREEN placeholder) — the full-mode 5-min path of the A33 ASSERTION was never run to completion (only the standalone spike exercised it).
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating -->
+
+## Evidence
+<!-- APPEND only - facts discovered -->
+
+- timestamp: 2026-05-22T11:10:39Z
+  checked: tests/uat/spike-a33-sw-persistence.ts — how the standalone spike dispatches SAVE_ARCHIVE
+  found: Spike uses chrome.runtime.sendMessage with a 15s timeout + chrome.runtime.lastError check (lines 263-281). The spike captures saveResult into a variable, logs it (`SPIKE Step 5 result: SAVE_ARCHIVE ack -> ...`), then proceeds UNCONDITIONALLY to Step 6/7 (download settle + zip inspection). Pass/fail is purely `videoSize > SPIKE_VIDEO_SIZE_FLOOR_BYTES` (lines 321-332). The spike does NOT gate on saveResult.success.
+  implication: The spike's design already treats the ack as a soft diagnostic, not a gate. If driveA33's A33.1 hard-checks saveResult.success, it diverges from the proven-reliable spike methodology. Strong support for the hypothesis.
+
+- timestamp: 2026-05-22T11:11:00Z
+  checked: src/background/index.ts SAVE_ARCHIVE handler (lines 1040-1044) + saveArchive() body (906+)
+  found: Handler is correct MV3 async pattern — `case 'SAVE_ARCHIVE': saveArchive().then(result => sendResponse(result)); return true;`. Returns true synchronously to keep the channel open; the .then ALWAYS calls sendResponse. saveArchive() is slow (tabs.query + captureScreenshot + getVideoBufferFromOffscreen via long-lived port + GET_RRWEB_EVENTS tab round-trip + createArchive zip build).
+  implication: No production bug. Phase-2 candidate (b) "handler doesn't return true / doesn't sendResponse" ELIMINATED. Fix is harness-side per scope.
+
+- timestamp: 2026-05-22T11:11:30Z
+  checked: tests/uat/extension-page-harness.ts — other A*.1 SAVE_ARCHIVE-ack checks
+  found: A24.1/A25.1/A27.1/A29.1/A30.1/A31.1/A34.1 all gate on "SAVE_ARCHIVE ack received with success=true" and are reliably GREEN. NONE of them dispatch SAVE_ARCHIVE after a worker.close() SW kill — the SW is alive+stable when they send. A33.1 is the ONLY ack check at the post-kill respawn boundary.
+  implication: The race is specific to the worker.close() -> immediate-sendMessage boundary, not a general ack unreliability. Narrows the mechanism.
+
+- timestamp: 2026-05-22T11:27:00Z
+  checked: Fast-repro _tmp-a33-fast-repro.ts — 5 iterations, 20s idle each, verbatim driveA33 dispatch
+  found: ack.success=true on ALL 5 runs (sizes 1.17/1.80/1.79/1.85/1.72 MB; all archives fresh). The race did NOT reproduce with a 20s idle. SW logs show offscreen "port disconnected — reconnecting" right before each save, then the Blob URL mints and saveArchive completes — ack returns true cleanly.
+  implication: Hypothesis REFINED — the flake is NOT simply "worker.close() then sendMessage". A blind-spot from the reasoning checkpoint is now contradicted. Need to test the genuine 5-min path.
+
+- timestamp: 2026-05-22T11:52:30Z
+  checked: Standalone spike (tests/uat/spike-a33-sw-persistence.ts) — GENUINE 5-min idle + worker.close() + SAVE_ARCHIVE, ack logged not gated. elapsed=309.2s.
+  found: `SPIKE Step 5 result: SAVE_ARCHIVE ack -> {"success":true}`. videoSize=1,803,695 bytes. PRE-KILL/POST-KILL segment probes both =3. The ack did NOT flake on this genuine 5-min run.
+  implication: DECISIVE — the flake is INTERMITTENT, not deterministic, even on the real 5-min path. Plan 04-05 observed success=false ONCE; this spike run + the Plan 04-08 spike re-run both got success=true on the same 5-min path. This is a genuine non-deterministic MV3 timing race at the worker.close() -> SAVE_ARCHIVE boundary: SOMETIMES the original sendMessage port closes before the freshly-woken SW resolves sendResponse, SOMETIMES it does not. The archive ALWAYS lands (videoSize large every observed run) because saveArchive() completes + chrome.downloads writes regardless. This is exactly the textbook MV3 "message port closed before a response was received" flake. Original hypothesis CONFIRMED in substance (A33.1 gates a best-effort ack); the only correction is that it is intermittent rather than deterministic — which makes the case for the fix STRONGER (a hard-gate on a non-deterministic ack is a flaky test by definition).
+
+- timestamp: 2026-05-22T12:05:23Z
+  checked: Fast-repro 10 more iterations at 20s idle (15 total with the earlier 5)
+  found: ack.success=true 15/15. The 20s-idle path NEVER hits the race.
+  implication: Confirms the 5-min-aged SW state is necessary. Mechanism: the offscreen<->SW `video-keepalive` port (src/background/index.ts:415-421) is a PING/PONG keepalive that resets the SW idle timer. After worker.close() on a 5-min-aged SW, the freshly-woken SW's saveArchive() -> getVideoBufferFromOffscreen() must wait for the offscreen to re-establish its port (offscreen reconnects only on disconnect detection — logs show "port disconnected — reconnecting"). After 5 min there are ~30 segment rotations + a longer-lived port-reconnect state machine; SOMETIMES that re-establishment + REQUEST_BUFFER round-trip + zip build outruns the original sendMessage response-port lifetime, SOMETIMES it does not. The archive ALWAYS lands because saveArchive() completes + chrome.downloads writes regardless of the ack.
+
+- timestamp: 2026-05-22T12:30:00Z
+  checked: Mechanism cross-check — src/background/index.ts SAVE_ARCHIVE handler + onConnect port host + saveArchive() chain
+  found: SW SAVE_ARCHIVE handler (1040-1044) is a textbook-correct MV3 async pattern (return true + always sendResponse). The slowness is structural: saveArchive() = tabs.query + captureScreenshot + getVideoBufferFromOffscreen (offscreen port REQUEST_BUFFER round-trip, with port-reconnect retries) + GET_RRWEB_EVENTS tab message + createArchive zip build. None of this is a bug — it is the legitimate save pipeline.
+  implication: Phase-2 candidate verdict — mechanism is (a): the sendMessage callback channel/port closes before the freshly-woken SW resolves sendResponse(). (b) ELIMINATED (handler correct). (c) partially relevant — worker.close() teardown timing IS the trigger, but it is not a harness mis-sequencing bug; the 500ms settle is fine, the race is inherent to MV3 post-respawn ack delivery. (d) ELIMINATED. NOT a production bug — STOP/escalate path NOT triggered. Fix is harness-side: A33.1 must stop hard-gating a non-deterministic best-effort ack.
+
+- timestamp: 2026-05-22T12:27:54Z
+  checked: Fast-repro at GENUINE 5-min idle, 2 iterations (A33_REPRO_IDLE_MS=300000)
+  found: ack.success=true 2/2 (videoSize 1.85/1.76 MB, both archives fresh).
+  implication: Could NOT reproduce the success=false side this session. Tally of the SAVE_ARCHIVE-ack across ALL observed dispatches: success=true 18x (15x fast 20s-idle + 2x fast 5-min-idle + 1x spike 5-min-idle), success=false 1x (Plan 04-05 full-mode UAT, documented verbatim in 04-05-SUMMARY lines 317-318). The flake is RARE (low single-digit % under these headless conditions), not common — explains why it escaped Plan 04-08 (which never ran the full-mode A33 assertion) and why the Plan 04-08 spike re-run happened to pass.
+
+- timestamp: 2026-05-22T12:35:00Z
+  checked: Whether "cannot reproduce the failure side" weakens the fix justification
+  found: It does NOT. The fix's correctness is independent of failure-side reproducibility. (1) The failure was observed directly + documented verbatim by Plan 04-05 — primary evidence, not hearsay. (2) The mechanism is confirmed by code reading: MV3 sendMessage response port has a finite lifetime; saveArchive() on a freshly-respawned post-worker.close() SW is a genuinely slow multi-step pipeline; the response port CAN close before sendResponse fires. (3) A CI assertion that hard-gates on a signal which is documented-non-deterministic AND was observed false-while-the-verified-thing-succeeded is a flaky test BY DEFINITION — regardless of the flake frequency. The race-free fresh-zip signal is the correct gate and is exactly what the proven-reliable spike uses. Verdict: fix is justified by primary observed evidence + confirmed mechanism; the 18/18 session success rate quantifies the flake as rare but does not refute it.
+
+- timestamp: 2026-05-22T12:57:45Z
+  checked: Skip-mode UAT regression check — fix-applied run bailed at A30 (A30.2-A30.6 all FAIL, zero events captured). Stashed the fix, re-ran clean baseline.
+  found: Clean baseline (fix stashed) = 35/35 GREEN — A30 PASS, A33 PASS, A34 PASS. The fix-applied run's A30 failure was a transient environmental flake: A30 does chrome.tabs.create of a real https://example.com probe tab + chrome.scripting.executeScript injection; all-event-types-missing is the signature of the probe tab failing to load (network-dependent). A30 runs BEFORE A33 in the drivers array; my fix touches only driveA33 — structurally cannot affect A30.
+  implication: A30 flake is unrelated to the fix (confirmed by stash/baseline isolation). Re-run skip-mode with the fix applied to get a clean 35/35.
+
+- timestamp: 2026-05-22T13:01:55Z
+  checked: Skip-mode UAT (fix applied) re-run — bailed at A31 (A31.4 CONTROL sentinel missing); A30 PASSED this run.
+  found: A different cs-injection-world assertion (A31, not A30) tripped this time. NOTE: this skip-mode run was launched IN PARALLEL with the 3-run full-mode A33 verification (3 concurrent headless Chrome instances contending for CPU/network).
+  implication: A30/A31 are a known-flaky environment-dependent UAT family, orthogonal to the A33 fix.
+
+- timestamp: 2026-05-22T13:14:30Z
+  checked: FULL-MODE A33 verification — 3 consecutive genuine 5-min runs of the REAL fixed driveA33 export (tests/uat/_tmp-a33-fix-verify.ts)
+  found: 3/3 GREEN. Every run: A33.1 PASS (fresh archive written, race-free), A33.2 PASS (video>0), A33.3 PASS (video>100KB). videoSize 1.76/1.81/1.83 MB. sendMessage ack soft-diagnostic = success=true on all 3.
+  implication: The fixed driveA33 is reliably GREEN across consecutive full-mode runs. Primary success criterion met.
+
+- timestamp: 2026-05-22T13:27:21Z
+  checked: Skip-mode UAT (fix applied) SOLO re-run — bailed at A29 (A29.2 a29-mutation-sentinel missing); A30/A31 not reached.
+  found: A THIRD distinct cs-injection-world assertion tripped (A29 this run; A30 in the first fix-run; A31 in the second). The A29.2 failure message itself reads "closes iana.org-leftover-flake from Plan 03-02/03-03". tests/uat/extension-page-harness.ts:3345 explicitly documents this assertion family as "a pre-existing flake in Plan 03-02 + 03-03".
+  implication: DEFINITIVE — A29/A30/A31 are a HARNESS-AUTHOR-DOCUMENTED known-flaky cs-injection-world family (chrome.tabs.create of real external iana.org/example.com tabs + executeScript; network/timing sensitive). Each run a different one trips. This is a PRE-EXISTING flake, fully orthogonal to the A33 fix: (1) the harness authors documented it before this debug session; (2) driveA29/A30/A31 run BEFORE driveA33 and my fix touches only driveA33; (3) the clean baseline (fix stashed) reached 35/35 only because that run's A29/A30/A31 all happened to pass. The A33 fix neither causes nor worsens the A29/A30/A31 flake. To get a clean skip-mode 35/35 with the fix applied, re-running until the flaky family aligns is the only path (the flake is environmental, not fixable here and out of scope).
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: |
+  driveA33 (tests/uat/lib/harness-page-driver.ts:2657-2662) makes A33.1 a HARD-GATING
+  check on `saveResult.success === true`, where saveResult is the chrome.runtime.sendMessage
+  callback result for {type:'SAVE_ARCHIVE'} dispatched immediately after a Puppeteer CDP
+  worker.close() SW kill. A33-overall-pass = checks.every(c => c.passed), so a flaked A33.1
+  fails the whole assertion.
+
+  The MV3 mechanism: worker.close() force-terminates the SW; the SAVE_ARCHIVE sendMessage
+  wakes a FRESH SW instance event-driven. The fresh SW runs saveArchive() — a multi-step
+  pipeline that must re-establish the offscreen `video-keepalive` port (the offscreen
+  reconnects only on disconnect detection), round-trip REQUEST_BUFFER, collect rrweb
+  events, and build the zip. The harness's original sendMessage response port has its own
+  MV3 lifetime. On a 5-min-aged SW, that pipeline INTERMITTENTLY outruns the response-port
+  lifetime -> the callback fires with chrome.runtime.lastError ("message port closed
+  before a response was received") -> saveResult.success === false.
+
+  This is NON-DETERMINISTIC: observed success=false 1x (Plan 04-05 full-mode UAT),
+  success=true 2x (Plan 04-08 spike re-run + this session's spike run) on the identical
+  genuine 5-min path; success=true 15/15 on a 20s-idle fast variant. The archive ALWAYS
+  lands correctly (videoSize 1.2-1.8 MB every observed run) because saveArchive() completes
+  and chrome.downloads writes the zip regardless of whether the ack reaches the harness.
+
+  A33.1 therefore gates a CI assertion on a best-effort transport ack with inherent MV3
+  non-determinism at the worker.close() -> respawn boundary. The durable proof of ROADMAP
+  SC #1 is A33.2/A33.3 (the archive contains a non-empty video buffer that survived the
+  SW kill) — which is exactly the race-free signal the proven-reliable spike script uses
+  (the spike logs the ack but does NOT gate on it). NOT a production bug: the SW
+  SAVE_ARCHIVE handler is a textbook-correct MV3 async pattern.
+
+fix: |
+  Option A (race-free A33.1 reframe) applied to driveA33 in
+  tests/uat/lib/harness-page-driver.ts — harness-side only, no src/ change.
+
+  Step 5: before dispatching SAVE_ARCHIVE, snapshot the pre-SAVE zip state
+  via the canonical snapshotExistingZips(downloadsDir). The
+  chrome.runtime.sendMessage callback `saveResult` is STILL captured but is
+  now a SOFT DIAGNOSTIC (diagnostics.push with success + error verbatim) —
+  no longer a check.
+
+  Step 7: replace findLatestZip(downloadsDir) with the canonical race-free
+  pollForNewOrUpdatedZip(downloadsDir, preSnapshot) — the same mtime-diff +
+  stable-size poll used by driveA12/A13/A27. A33.1 becomes "a fresh archive
+  appeared in downloadsDir within the poll timeout after SAVE_ARCHIVE
+  dispatch", passed = (zipPath !== null). This is the durable race-free
+  signal the spike already relies on. The old A33.0 null-zip fallback is
+  folded into the A33.1 check itself.
+
+  A33.2/A33.3 substantive checks are UNCHANGED in logic and now read the
+  fresh zipPath from the race-free poll (semantically stronger than the
+  prior findLatestZip mtime-sort; functionally identical in A33's
+  single-run context). 3 gating sub-checks preserved (A33.1 fresh-archive,
+  A33.2 video>0, A33.3 video>100KB). SKIP_LONG_UAT env-gate untouched.
+  No new symbol introduced (snapshotExistingZips/pollForNewOrUpdatedZip are
+  pre-existing module-internal helpers); FORBIDDEN_HOOK_STRINGS unaffected.
+
+verification: |
+  - Full-mode A33 (genuine 5-min idle), 3 consecutive runs via the REAL
+    fixed driveA33 export: 3/3 GREEN. Every run passed A33.1 (fresh archive
+    written, race-free), A33.2 (video>0), A33.3 (video>100KB). videoSize
+    1.76/1.81/1.83 MB. sendMessage ack soft-diagnostic = success=true on
+    all 3 (the flake is rare — the point is A33 no longer GATES on it).
+  - Skip-mode UAT (SKIP_LONG_UAT=1, fix applied, solo run): 35/35 GREEN —
+    A33 placeholder PASS, A34 real PASS. (Two earlier skip-mode runs bailed
+    at A30 then A31, and a third at A29 — the harness-author-documented
+    cs-injection-world flake family per extension-page-harness.ts:3345
+    "pre-existing flake in Plan 03-02 + 03-03"; orthogonal to this fix,
+    confirmed by a clean-baseline stash run also hitting 35/35. The flaky
+    family aligned on the clean 35/35 fix-applied run.)
+  - npx tsc --noEmit: exit 0 (with + after throwaway-script cleanup).
+  - npm run build:test: exit 0.
+  - vitest: 184/184 GREEN (36 files) — unchanged baseline; no unit-test
+    change. no-test-hooks-in-prod-bundle.test.ts among them.
+  - Tier-1 FORBIDDEN_HOOK_STRINGS: 12 entries — unchanged (fix introduces
+    no new symbol; reuses pre-existing snapshotExistingZips +
+    pollForNewOrUpdatedZip module-internal helpers).
+  - SKIP_LONG_UAT env-gate at harness.test.ts: untouched.
+  - A33_IDLE_WAIT_MS confirmed at the real 5*60*1000; no temporary
+    idle-shortening landed (env-driven throwaway repro scripts used
+    instead, both deleted).
+files_changed:
+  - tests/uat/lib/harness-page-driver.ts