fix(github): /status reports credential liveness, not just presence

[lilyshen0722]

Stacked on #808 — merge that first. This touches routes/github.ts, which #808 rewrites; branching off main would have conflicted, so the base here is #808's head 68b51262. The diff will shrink to just this change once #808 lands.

The defect

GET /api/github/status exists to answer one question — is the GitHub credential OK? It answered off GitHubAppService.isPatConfigured(), which is !!process.env.GITHUB_PAT: presence, not liveness.

Through the 2026-08-04 outage it therefore reported configured: true while every proxied call returned 401 Bad credentials. Measured from inside three running pods (backend, clawdbot-gateway, cloud-codex-cody) — all 401, PAT present and well-formed in each.

It fails in the direction that ends the search. configured: true reads as the config is fine, so it's you. Three seats were blocked that morning and one concluded the fault was its own seat before the real cause was found — that seat has confirmed the belief it formed (msg 52256), and this endpoint would have confirmed it too.

A second predicate, not a corrected one

Credit: @ux-lead, msg 52286, who caught that the obvious fix is wrong.

isPatConfigured has six call sites asking two different questions:

sites	question	right test
the four proxying gates	"should I even attempt this?"	presence — and with #808 landed the attempt now fails legibly, which is the correct division of labour
/status	"is it working?"	liveness — only GitHub can answer
getPatToken handout	hands the token out	presence

Putting a network call inside isPatConfigured would fix /status and put a round-trip on four hot request paths. Same "one constant, two jobs" shape as VALID_POD_TYPES on #807.

So: isPatConfigured is unchanged (with a docstring saying to keep it free of I/O), and checkPatLiveness is new.

Three answers, not two

{ live: boolean | null, status: 'absent'|'accepted'|'rejected'|'unreachable', upstreamStatus?, detail? }

live: null for unreachable is load-bearing. If GitHub can't be reached we don't know, and reporting false would send an operator to rotate a credential that may be perfectly good. A diagnostic that guesses in the confident direction is the defect this removes, not a smaller copy of it.

The probe is GET /rate_limit because GitHub documents it as not counting against the rate limit, so the diagnostic can be called freely. A 401 there is exactly the wanted signal: present, well-formed, refused.

/status must not adopt #808's mapper — and that is now pinned

This is the one route where staying unmapped is a hard rule rather than an observation. If the diagnostic returned 502 on a rejected credential, a caller could not distinguish "the credential is dead" from "the diagnostic is broken" — the exact collapse #808 spent a PR removing from the seven proxying routes, reintroduced at the single endpoint that exists to prevent it.

A dead credential is a successful diagnosis. It answers 200 { mode: 'pat', configured: true, credentialLive: false, credentialStatus: 'rejected', upstreamStatus: 401 }.

Both the rule and the reason are in the source comment, because the route already carries a comment explaining why it keeps its 500 and the next reader will reasonably try to unify them.

Verification

node@22 v22.23.1. 22/22 across all three github route suites (6 new). tsc:check clean.

Mutations, each blob-hashed before and after so an unapplied edit can't fake a green:

mutation	result
revert /status to presence-only (the original bug)	5 red
report unreachable as dead (live: false)	1 red — exactly the false-negative test
/status adopts the mapper's 502 on a dead credential	2 red

Lint: the .ts parsing errors from npx eslint are pre-existing — the legacy resolver doesn't parse TypeScript at all; origin/main's untouched githubAppService.ts fails on line 1's import. The three real findings on the new test file are fixed.

Not verified

I could not exercise this against the live GitHub API with a working credential — the shared PAT is currently dead, which is the whole subject. The accepted path is covered by a mocked 200 only. /rate_limit's quota exemption is from GitHub's documentation, not measured here. And this does not fix the outage: the PAT still needs rotating. It only makes the next one diagnosable in one call instead of three pods.

🤖 Generated with Claude Code

[lilyshen0722]

Now DIRTY against main — #808 merged and the two branches rewrite the same error-mapping code. 10 conflicts across 3 files, and they are composable rather than competing: each side changed a different property of the same branches.

I stopped short of resolving them because the two conflicts I read need opposite resolutions, so a uniform "take ours/theirs" would ship a regression either way. Recording the analysis so it is not re-derived:

Conflict 1 (github.ts:77, the 404 branch) — take main's. #808 added detail to every branch including this one; without it the caller's log line reads github_not_found undefined on the commonest failure there is. This branch's copy predates that and would silently revert it.

Conflict 2 (github.ts:97, rate-limit detection) — take this branch's. Extracting isRateLimitError(upstreamStatus, headers) so the liveness probe shares the exact predicate is what #809 is for; main's inline 429 || (403 && remaining === '0') is the duplicate that made the probe call every throttled PAT dead. Keep the extraction and make sure the 403-with-zero-remaining case survives into it.

The shape generalizes to the remaining 8: #808 owns the response body, #809 owns the predicate. Where the conflict is about what is reported, main wins; where it is about how the condition is detected, this branch wins. Resolve per-hunk on that rule rather than per-file.

Verify after resolving with the github route suites, and specifically check that a 403 carrying x-ratelimit-remaining: 0 still classifies as rate-limited and still carries detail — that is the one case both PRs touch at once.

Context for whoever picks this up: I hit the same class of trap on #818 today. Its extraction was byte-stale against a clause #804 had added, and every test stayed green because the suite pinned the extracted module, which was self-consistently wrong. A refactor's tests cannot catch a stale copy — only a diff against the live text can.