refactor(bg): tab-registry + challenge-flag redesign (closes Q-016)

[DustinVK]

What & why

Refactors per-tab run state — which was scattered as raw expurge_tab_* / expurge_challenge_*
session-storage literals and ad-hoc scans across background/index.ts — into one owned tab
registry, and makes the content script the authoritative owner of the challenge signal. No
happy-path behavior change; a class of challenge-flag lifecycle bugs (orphan keys, in-place
reappearance, "who clears the flag") disappears. Closes Q-016.

The three parts (one commit each)

• A — refactor(bg): own per-tab state in a tab-registry. New pure tab-registry-resolve.ts
  (tabForItem, brokerTabInWindow, key helpers) + I/O wrapper tab-registry.ts. Split into two
  files (not the spec's one) because webextension-polyfill throws at import in node tests, so the
  pure resolvers must stay polyfill-free to be unit-tested — mirrors the coordinator.ts ↔
  index.ts pattern. removeTab now drops both keys and removeAllTabs sweeps both families
  on Stop → the orphan-challenge-key bug is gone.
• B — feat(content): always-armed challenge observer. A persistent, never-disconnecting
  MutationObserver reports challenge transitions in both directions (appear → DETECTED, clear →
  RESOLVED), closing the in-place-reappearance gap.
• C — fix(bg): drop redundant onUpdated push. The content report is the authoritative
  post-load push; onUpdated's push raced it and flashed the verdict view over a challenge page.
  Own revertable commit; SPA caveat documented.

Self-review follow-ups (also in this branch)

An extra-high-effort review of the branch surfaced 15 findings; the correctness/robustness ones are
fixed here:

• Challenge appearance is now reported on the leading edge (never starved by a churny page's
  debounce reset); clearing keeps the 250 ms settle but the timer isn't reset.
• putTab scrubs any stale challenge key on tab (re)open — a recycled id can't inherit challenge=true.
• captureListingUrl requires isOnHost — an off-host tab can't record a wrong listing into a draft.
• onRemoved clears a tracked tab's keys eagerly (can't be skipped by handleSkip's !run return)
  and skips storage writes for untracked tabs.
• findBrokerTab resolves tracked tabs in parallel; isPerTabKey predicate extracted + tested;
  cross-window resolver test added.

Consciously left (rationale in commits): lastReported-before-send (MV3 wakes the event page),
late-injected-widget false DETECTED (challenge-specific selectors), numeric-vs-insertion key order
(monotonic ids), observer-never-disconnects (by design), redundant resolver param (cosmetic).

Testing

npm run typecheck && npm test && npm run build green; 187 unit tests, 100% coverage on the
pure modules, web-ext lint 0 errors (13 pre-existing manifest _notes warnings, unrelated).

Still owed (not blocking merge)

• Manual QA in Firefox 140+: normal challenge→solve flow unchanged; no expurge_challenge_*
  after Stop; no verdict flash on a challenge load; a DOM-injected challenge flips to the challenge
  view. Plus the PR chore(sidebar): review cleanup — wordmark, isMissingSkip, progress source, checklist race, external-mutation pushes #5 re-verdict checks in temp/next-steps.md §2.
• After merge: resolve Q-016 in the wherefore log; update plan/expurge-progress.md.

🤖 Generated with Claude Code

---

Manual QA — Firefox 140+, 2026-07-03

Test	Result
1 — no orphan expurge_challenge_* keys remain after Stop	✅ pass
2 — in-place challenge appear → clear flips the sidebar view (incl. the churn variant that would starve a trailing debounce)	✅ pass
3 — closing a broker tab clears both its keys and skips the item (tab_closed)	✅ pass
5 — off-host listingUrl guard	✅ pass — on-host details URL captured; an off-host (google.com) verdict recorded no listingUrl
6 — re-verdict trio (post-run summary refresh / mid-run sticky view / stopped counts)	✅ pass
4 — real Cloudflare challenge	⚠️ pre-existing detection gap — not a regression from this PR

Test 4 — pre-existing challenge-detection gap (does not block this PR)

On TruePeopleSearch's real gate (/InternalCaptcha, a "Verify you are human" widget) the sidebar shows
verdict buttons over the live challenge. Root cause is in detectChallenge() (src/content/classify.ts),
which this PR does not touch — so it predates this refactor and isn't caused by it. This PR reworks
challenge state management (all tests green); it doesn't change what counts as a challenge.

Diagnosed via live DOM probe: TPS renders Cloudflare Turnstile explicitly (widget iframes are
about:blank, no .cf-turnstile container), so every current selector misses it. The reliable signal is
the Turnstile API script challenges.cloudflare.com/turnstile/v0/api.js. Fix is a one-selector add to
detectChallenge(), safe because the interstitial navigates away on solve (fresh load → CHALLENGE_RESOLVED).

Tracked as a follow-up (fix/challenge-detection-managed, natural pairing with the M9 broker expansion);
full write-up in temp/challenge-detection-fix.md (local handoff doc).