v1.39.0.0 feat: buildFetchHandler factory unblocks gbrowser submodule consumption

[garrytan]

Summary

buildFetchHandler ships — gbrowser v0.6.0.0 (phoenix overlay) can now consume gstack as a submodule and compose overlay routes on top of the browse server's dispatch.

• Exports buildFetchHandler(cfg: ServerConfig): ServerHandle from browse/src/server.ts. CLI delegates to the same factory.
• Auth is now cfg-driven end-to-end. Module-level AUTH_TOKEN const + boot initRegistry call, validateAuth, and shutdown are deleted; factory closure owns them so embedders' browsers actually get closed on shutdown.
• beforeRoute hook wired: runs after the tunnel surface filter, before per-route dispatch. Returns Response → short-circuit; returns null → fall through to gstack. JSDoc now includes a security warning about not returning privileged data from the hook without re-checking auth (the hook fires for missing AND invalid bearer).
• initRegistry gains idempotency: same token = no-op, different token = throws clearly. New __resetRegistry() test helper mirrors __resetConnectRateLimit.
• 14 new factory contract tests in browse/test/server-factory.test.ts cover the ServerHandle shape, auth wiring, validation throws, hook semantics across both surfaces, and registry idempotency.

Test Coverage

CODE PATHS                                                       USER FLOWS / EMBEDDER FLOWS
[+] browse/src/server.ts                                          [+] CLI start path
  ├── buildFetchHandler(cfg)                                        ├── [★★★ TESTED] start() smoke + bun test full
  │   ├── cfg.authToken short                  [★★★ TESTED]         └── [★★★ TESTED] /command POST flow
  │   ├── cfg.browserManager missing           [★★★ TESTED]
  │   ├── initRegistry init                    [★★★ TESTED]       [+] Embedder boot path
  │   ├── factory validateAuth                 [★★★ TESTED]         ├── [★★★ TESTED] cfg.authToken throws on short
  │   ├── factory shutdown                     [★  TESTED]           ├── [★★★ TESTED] missing browserManager throws
  │   └── beforeRoute hook                     [★★★ TESTED]         └── [★★★ TESTED] same-token idempotent
[+] browse/src/token-registry.ts                                  [+] beforeRoute hook contract
  ├── initRegistry idempotent                  [★★★ TESTED]         ├── [★★★ TESTED] Response short-circuits
  ├── initRegistry mismatch throws             [★★★ TESTED]         ├── [★★★ TESTED] null falls through
  └── __resetRegistry()                        [★★★ TESTED]         └── [★★★ TESTED] valid TokenInfo + null

COVERAGE: 14/14 new paths tested (100%) | 28 server-factory tests pass | 154 tests across 6 directly-affected files pass

Pre-Landing Review

Pre-landing review ran during /plan-eng-review (clean) and Codex outside-voice in plan mode. All findings incorporated into the plan and the implementation. Key Codex findings addressed:

• refactor: reorganize codebase into modular structure #2 ESM-hoisting in test bootstrap — superseded by D12 (no preload needed once AUTH_TOKEN const is deleted)
• browse skill: default to sonnet to save tokens #8 start() must capture Bun.serve() return — captured
• New /bugfix skill #9 beforeRoute threat model — security warning added to JSDoc
• Default browse skill to Sonnet to save tokens #11 'tabs' command flakiness — test split into /health positive + /command 401 negative
• Feedback #12 verbatim-copy semantic drift risk — mitigated by single-source dispatcher (no duplication)
• Security: Path traversal in screenshot/pdf/eval commands allows arbitrary file read/write #13 "pure factory" wording — softened to "exposed as a factory" (this entry follows)

Eval Results

No prompt-related files changed — evals skipped.

Plan Completion

All plan decisions (D1 through D14) accepted by the user and implemented. The CEO scope-expansion decision (D12) pulled the "real factory" refactor into this PR rather than deferring — module-level AUTH_TOKEN/validateAuth/shutdown all deleted in favor of factory-scoped equivalents.

Pre-existing test failures (not caused by this PR)

browse/test/server-auth.test.ts has 4 pre-existing failures verified against origin/main (via git stash) before this branch's work began:

• /activity/history requires authentication (marker mismatch: Sidebar endpoints → Sidebar chat endpoints ripped)
• /activity/history has no wildcard CORS header (same root cause)
• connect command status fetch body has no undefined variable references (CLI_SRC marker mismatch)
• pair-agent disables parent PID monitoring via BROWSE_PARENT_PID=0 (CLI_SRC marker mismatch)

These are source-pattern test drift unrelated to the factory work. Captured for a future cleanup PR.

Test plan

• bun test browse/test/server-factory.test.ts — 28/28 pass
• bun test browse/test/token-registry.test.ts — 49/49 pass
• bun test browse/test/skill-token.test.ts — 15/15 pass
• bun test browse/test/browser-skills-e2e.test.ts — 8/8 pass
• bun test browse/test/browser-skill-commands.test.ts — 29/29 pass
• bun test browse/test/dual-listener.test.ts — 25/25 pass (was 25/25 on main, no regression)
• Confirmed zero new regressions vs origin/main across the broader suite

🤖 Generated with Claude Code

[github-actions]

E2E Evals: ✅ PASS

8/8 tests passed | $1.40 total cost | 12 parallel runners

Suite	Result	Status	Cost
e2e-browse	2/2	✅	$0.13
e2e-deploy	2/2	✅	$0.32
e2e-qa-workflow	1/1	✅	$0.61
llm-judge	1/1	✅	$0.02
e2e-deploy	2/2	✅	$0.32

---

12x ubicloud-standard-8 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite