refactor(extension-core): stop exporting background helpers nothing imports

[chrischall]

Addresses the first nit from the #226 auto-review follow-ups (#227).

Nit 1 — seven symbols exported but referenced only within their own module — FIXED

drop export on hello.ts:sameDomainSet, DEFAULT_CAPABILITIES, effectiveCapabilities, DeclaredScope, declaredScope, badge.ts:syncBadge, pending-records.ts:PendingRecordBase

Verified real before changing anything. A whole-tree git grep over origin/main (tracked files only, so node_modules/dist are out of scope, docs are in) shows every one of the seven referenced only inside its own defining module. The apparent cross-file hits are false positives: declaredScope/DeclaredScope in tests/background.test.ts and server-hello.ts are local const declaredScope / const declaredScopeForHash identifiers, not imports. Both barrels (src/background.ts, src/index.ts) were read directly — they re-export handleServerHello / HandleHelloDeps / HandleHelloResult, applyNeedsPairRecord / AnyPendingRecord and the session-scope symbols, and none of the seven.

The sibling exports deliberately stay: badge.ts's four transitions (setConnectionStatus, flashActivity, setPairPendingBadge, clearPairPendingBadge) are imported by socket.ts / server-hello.ts / approval.ts / boot.ts, and PendingPairRecord / PendingScopeUpdateRecord are imported by server-hello.ts. Only the over-exported symbols were narrowed.

No TS4020. PendingRecordBase does not need export to remain reachable as the extends base of two exported interfaces. Confirmed from the emitted declaration rather than assumed:

$ grep -n "interface\|export" packages/extension-core/dist/background/pending-records.d.ts
16:interface PendingRecordBase {
37:export interface PendingPairRecord extends PendingRecordBase {
93:export interface PendingScopeUpdateRecord extends PendingRecordBase {
128:export type AnyPendingRecord = PendingPairRecord | PendingScopeUpdateRecord;
144:export {};

$ grep -c "DeclaredScope" packages/extension-core/dist/background/hello.d.ts
0

Docblock correction. pending-records.ts asserted that PendingRecordBase was "exported here because background.ts still constructs both record kinds." Two things wrong with that: the constructor is server-hello.ts (lines 139 and 214), not background.ts, and the export was not needed for it either way. Rewritten to say what is actually true.

Regression guard

New tests/background-module-surface.test.ts pins all three surfaces. It guards both halves:

• Value exports via the ES module namespace (Object.keys(module)).
• Type-only exports via the module source text. Interfaces and type aliases are erased at runtime so they never appear in the namespace, and this package's tsconfig.json sets include: ["src/**/*"] — tsc -b never reads tests/, so a stray export interface cannot be caught by a type error either. Without the source-text half, DeclaredScope and PendingRecordBase would have had no automated guard at all.

TDD — the guard was written first and run against the unfixed tree (git stash of the three src/ files, restored after):

$ npx vitest run packages/extension-core/tests/background-module-surface.test.ts   # src at db30f4d
 FAIL  ... > hello.ts exports only the decision function its callers import
+   "DEFAULT_CAPABILITIES", +   "declaredScope", +   "effectiveCapabilities", +   "sameDomainSet"
 FAIL  ... > hello.ts exports only the two types its callers name
+   "DeclaredScope"
 FAIL  ... > badge.ts exports only the four badge transitions its callers import
+   "syncBadge"
 FAIL  ... > pending-records.ts keeps PendingRecordBase file-local
+   "PendingRecordBase"

 Test Files  1 failed (1)
      Tests  4 failed | 1 passed (5)

All four fail without the fix; all five pass with it.

Nit 2 — session-scope-teardown.test.ts ALL_SCOPE_MAPS — DEFERRED

derive the list from the module's exports to make the "must fail here" comment true

Not touched by this PR. Its checkbox stays unchecked on #227, which therefore stays open — no Closes.

Verification

Run in CI's order (build-command: npm run build, then test-command: npm test), all after the final edit:

$ npm run build
npm run build exit=0

$ npm test
 Test Files  92 passed (92)
      Tests  1240 passed (1240)          # 1235 on main + 5 new

$ (cd packages/extension-core && npx tsc -b --force)
tsc -b --force exit=0

$ (cd packages/extension-chrome && npx tsx build.ts)
extension-chrome built → packages/extension-chrome/dist
build.ts exit=0

Refs #227

[claude]

Claude finished @chrischall's task in 1m 35s —— View job

---

Review complete

• Read CLAUDE.md for conventions
• Read PR diff (git diff origin/main...HEAD)
• Review each changed file
• Verify claims made in PR description
• Post findings and verdict

Summary

This PR drops export from seven symbols in hello.ts, badge.ts, and pending-records.ts that are only referenced within their own defining module, and adds a regression test (background-module-surface.test.ts) that pins each module's exported surface (both value exports via the namespace object and type-only exports via source-text matching, since tsc -b doesn't type-check tests/ per this package's tsconfig.json).

I independently re-verified the PR's central claims rather than taking them at face value:

• No cross-file references exist for any of the seven narrowed symbols. Ran git grep -n -w <symbol> across the full tracked tree for sameDomainSet, DEFAULT_CAPABILITIES, effectiveCapabilities, DeclaredScope, declaredScope, syncBadge, and PendingRecordBase. Every hit is inside the symbol's own defining file, its own doc comment, or (for declaredScope) a false-positive local const declaredScope in tests/background.test.ts:890 and a prose mention in docs/superpowers/specs/2026-06-03-capture-headers-host-path-design.md:75 — exactly as the PR description claims.
• Neither barrel re-exports any of the seven. packages/extension-core/src/background.ts re-exports handleServerHello/HandleHelloDeps/HandleHelloResult, ChromeCookie, applyNeedsPairRecord/AnyPendingRecord, and several handler-level symbols — none of the seven. src/index.ts only re-exports handleServerHello and its types from background.js.
• The rewritten docblock in pending-records.ts is accurate. It now attributes construction of both pending-record kinds to server-hello.ts; confirmed PendingScopeUpdateRecord is constructed at server-hello.ts:139 and PendingPairRecord at server-hello.ts:214.
• The new test's expected export lists match the post-diff source for all four describe blocks (hello.ts value/type exports, badge.ts, pending-records.ts).

No correctness, convention, or test-coverage issues found. This is a mechanical, low-risk visibility narrowing with a well-targeted regression test that guards against re-widening (including the type-only exports that tsc -b alone wouldn't catch, per this package's include: ["src/**/*"]).

Note: I was unable to execute npm run build / npm test / npx tsc -b in this sandbox (commands required approval that wasn't available), so I could not independently reproduce the PR description's reported 92 passed / 1240 passed and tsc -b --force exit=0 results. All findings above are grounded in direct source inspection and git grep, not test execution — flagging this as an open question rather than a blocking concern, since the PR description already includes the CI-order verification output.

Verdict: pass

[github-actions]

✅ Auto-review verdict: pass — Mechanical, low-risk export-narrowing PR; all claims (no cross-file references, no barrel re-exports, accurate docblock, matching regression test) were independently verified via git grep and diff inspection. No correctness or convention issues found.