feat(github): a multi-org GitHub App, and git that reaches every org (v0.435.0)

[vikasprogrammer]

Phases 1–3 of docs/github-multi-org-plan.md (#800).

The defect

GithubIdentity.ensureBotToken persisted a single github_installation_id and, when it was unset, resolved it as installations[0] — whichever install GET /app/installations happened to return first — then cached one token under one vault key.

With the App installed on two orgs the bot acted on one of them and 404'd every repo in the other. Nothing failed at launch: the token is valid, it just doesn't cover that repo, so it reads to a human as "the agent can't see our repo". The stale-id retry re-picked [0] too, so a reinstall could flip which org worked with nobody touching a setting.

Phase 1 + 2 — the registry and a token per installation

• github_installations records the whole set; github_installation_id keeps its exact meaning as the primary. Both are plain settings rows — no migration, and a one-org tenant behaves bit-for-bit as before. GithubIdentity gains installations / installationFor (case-insensitive) / primaryInstallation / orgs / refreshInstallations.
• Each installation caches under github_bot_token:<id>; loadBotToken(org?) and ensureBotToken(nowMs?, by?, org?) resolve per org. A token in the legacy bare slot migrates onto the primary's key on first read.
• An org the App isn't installed on yields undefined and mints nothing — never another org's credential. refreshInstallations leaves a live primary alone and replaces only a vanished one, so reinstall churn can't quietly move which org the fleet pushes to.
• Launch exports AOS_GH_ORG + AOS_GH_ORGS; GET /api/state exposes installations + primaryInstallationId. Clearing the private key now drops every installation's token and the registry.

Phase 3 — git reaches every org

configureGitCredentials turns on credential.useHttpPath for a multi-org bot run, so git hands the helper path=<org>/<repo> on every request. The helper reads the org off that and — only when it isn't the org $GH_TOKEN already covers — fetches that installation's token from POST /api/agent/github/credential, the same session-secret loopback channel the gate hook uses.

• A primary-org repo costs no round trip.
• Any failure falls back to $GH_TOKEN: unreachable route, uninstalled org, restarted server. The worst case is exactly the old behaviour, never broken git.
• The member guard, both sides. The helper isn't installed for a run carrying a linked member's token, and the route refuses one (member_identity). A per-repo bot token would otherwise silently re-author that human's commits as the App bot the moment they touched a second org.
• Mints are audited (github.bot_token.minted, via: credential-helper); lookups aren't — git calls its helper on every fetch/push and the token is cached for the hour.

gh is still primary-only — it reads GH_TOKEN and ignores git credential helpers. The agent's prompt now says exactly that rather than implying every non-primary org is unreachable. github_token({ org }) is phase 4.

Verification

• npm run typecheck, cd web && npm run build, and the full npm run test:governance gate all clean.
• scripts/github-multi-org-test.cjs — 50 checks, added to test:governance. The phase-3 half drives real git credential fill against the real route, covering the primary/second-org/uninstalled/unreachable/member-identity paths plus the route's 404/403/no_org edges.
• scripts/github-per-member-test.cjs still 86/86 — the single-org path is unchanged.

Two things the real-git runs caught that review would not have: an inlined -d "{\"session\"...}" in the helper silently truncates the curl argument (the body is built with printf now), and a test harness using execFileSync deadlocks against an in-process server, so the helper always appeared to fall back.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UfJRSqtHhuk7x51Cqy4NB5