fix(gastown): distinguish null causes in PR status polling (#3149)

[jrf0110]

Summary

Replace PRStatusResult | null return type with discriminated PRStatusOutcome union in checkPRStatus. Each null cause (no token, HTTP error, invalid response, unrecognized URL, host mismatch) now surfaces a structured PRStatusError with actionable failure messages.

Key changes:

• resolveGitHubToken returns GitHubTokenResolution with resolution chain tracking which sources were tried
• no_token and non-transient HTTP errors (401/403/404) fail the bead immediately (1 strike)
• invalid_response/unrecognized_url/host_mismatch fail after 3 strikes
• Transient HTTP errors (5xx/429) keep existing 10-strike behavior
• poll_null_count resets to 0 on successful poll at both call sites
• failureKind persisted to bead metadata for analytics
• AE event pr.poll_failed emitted on terminal failure

Also includes an unrelated fix for boot hydration contention on /agents/start (commit 2ffcef28f).

Fixes #3149.

Verification

• pnpm --filter cloudflare-gastown typecheck passes
• Unit tests pass: test/unit/pr-poll-errors.test.ts (checkPRStatus, resolveGitHubToken), test/unit/pr-poll-thresholds.test.ts (failureMessageFor, shouldFailImmediately, shouldCountAsTransient)
• Integration test for no_token immediate-fail path: test/integration/pr-poll-errors.test.ts
• HTTP error scenarios covered by unit tests (mocking fetch is not practical in Cloudflare Workers integration test runtime)

Visual Changes

N/A

Reviewer Notes

• The refresh-git-token.handler.ts change is a caller update for the new GitHubTokenResolution return type (was string | null)
• The unrelated boot hydration commit (2ffcef28f) is included on this branch from a prior bead attempt — it fixes a separate timeout regression
• The wrangler.jsonc max_instances change (800→500) is from the same unrelated commit

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Previously Flagged Issues — All Resolved ✓

File	Issue	Status
services/gastown/src/dos/town/town-scm.ts	Missing tried entry when integrationId set but GIT_TOKEN_SERVICE absent	✅ Fixed
services/gastown/src/dos/town/actions.ts	Shared poll_null_count counter causing cross-contamination between thresholds	✅ Fixed — split into poll_transient_count / poll_non_transient_count
services/gastown/src/dos/town/actions.ts	unrecognized_url / host_mismatch routed through 3-strike retry rather than immediate fail	✅ Fixed

Latest Commit — No New Issues

The new commit adds:

• Token priority reorder in resolveGitHubToken: github_cli_pat → platform integration (fresh) → stored github_token. Correct fix for the stale installation-token bug; well-documented and covered by new tests in test/unit/town-scm.test.ts.
• resolveGitHubTokenString helper — thin wrapper, correctly typed string | null.
• buildContainerConfig now requires townId — prevents stale-token foot-gun at all call sites; all 4 callers updated.
• startAgentInContainer / startMergeInContainer — both resolve fresh tokens via resolveGitHubTokenString before container dispatch.
• gastown.worker.ts logger tagging — regex-based middleware replaced with route-pattern app.use() handlers. No logic change, cleaner param extraction.
• Three new debug endpoints (/debug/towns/:townId/rigs, /sling-convoy, /convoys) — all correctly guarded by ENVIRONMENT !== 'development'.
• E2E testing doc — new Test C section covering review-then-land convoy mode.

Files Reviewed

• services/gastown/src/dos/town/town-scm.ts — no issues
• services/gastown/src/dos/town/actions.ts — no issues
• services/gastown/src/dos/town/config.ts — no issues
• services/gastown/src/dos/town/container-dispatch.ts — no issues
• services/gastown/src/dos/Town.do.ts — no issues
• services/gastown/src/gastown.worker.ts — no issues
• services/gastown/src/handlers/refresh-git-token.handler.ts — no issues
• services/gastown/test/unit/town-scm.test.ts — no issues
• services/gastown/test/unit/pr-poll-errors.test.ts — no issues
• services/gastown/test/unit/pr-poll-thresholds.test.ts — no issues
• services/gastown/test/integration/pr-poll-errors.test.ts — no issues
• services/gastown/docs/e2e-pr-feedback-testing.md — no issues

---

_{Reviewed by claude-4.6-sonnet-20260217 · 1,297,610 tokens}