V48 Gate 3 (specification-only): correct the "installation removed" 40x hint — it's a stale installation id from a different Bitcode GitHub App (V48-Gate3-F35)

geraldarthurdavis · claude · geraldarthurdavis · commit 80efc995fd17 · 2026-07-08T12:32:26.000-07:00
The F34 diagnostic did its job: retesting surfaced "Failed to generate
installation token: 404 Not Found." But the org's Installed GitHub Apps
page shows BOTH Bitcode GitHub Apps still installed (production and
Stag-Test) — disproving F34's own hint that a 40x means the installation
was removed.

Per the documented Environments section, these are genuinely two separate
GitHub App registrations, and the 2026-07-05 "production == staging"
decision pushed the Stag-Test app's credentials to all three Vercel
targets. A connection whose installation id was minted under the OTHER
app (production) is invisible to a JWT signed for Stag-Test — GitHub
returns 404, indistinguishable from a real removal even though an app is
very much still installed.

Corrected the copy: it no longer claims reinstalling on GitHub is the fix.
It now points at Disconnect + reconnect (in Bitcode), which re-runs the
install/authorize flow against whichever app this deployment is actually
configured with and writes a fresh installation id — no GitHub-side action
needed.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/BITCODE_V48_QA.md b/BITCODE_V48_QA.md
@@ -537,9 +537,16 @@ Track 3-4 scripts (BTD ledger, settlement, pack journaling) get added when those
 
 - Severity: high (live-confirmed, 2026-07-08: clicked Refresh after the F33 deploy went live — same "Invalid" badge in Auxillaries, same reconnect-required banner on `/deposits`. Confirmed deploy timing: commit `dbef719e` (F33) pushed 11:24:50, its Preview build was `Ready` by ~11:27, the retest screenshot is 11:46 — the fix WAS live when retested, so F33's fix, while a real and necessary bug, was not the reason THIS specific connection stayed Invalid).
 - Investigation: with F33 confirmed deployed and env vars confirmed present (F33), the only two remaining explanations are (a) the GitHub App installation was genuinely revoked/uninstalled on GitHub's side (only a real reinstall fixes that), or (b) a different bug in the regeneration call chain. Neither was distinguishable from the UI or from `vercel logs` (historical logs aren't retrievable after the fact for this project's plan/log-drain setup — confirmed by trying).
-- Repair (turns the black box into a source-safe diagnostic instead of resolving blind): `VCSConnections` now persists a `last_regeneration_error` (and `last_regeneration_at`) onto the connection row every time installation-token regeneration is attempted — the actual reason on failure (GitHub's own API error text, e.g. a 404 meaning the installation was removed; or `github_app_credentials_not_configured` if the env gate itself was skipped), or cleared to `null` on success. This flows through the existing `sanitizeConnectionMetadata` pass-through into `connectionStatus.metadata` with no other route changes needed (the new keys aren't in the token/secret blocklist). `VCSConnectionCard.tsx` now renders this reason under the badge when `!valid`, with a plain-language hint that a 401/403/404 means reinstalling the GitHub App is the only fix Refresh can't provide. This makes the NEXT occurrence of "Refresh doesn't fix Invalid" immediately diagnosable from the card itself — for this user or anyone — without needing server log access. Verified: `tsc --noEmit` 0 (both packages); new `uapi/tests/vcsConnectionCard.test.tsx` (4/4: no extra UI when valid, reason + reinstall hint on a 404, missing-credentials reason mapped to plain language with no reinstall hint, no extra UI when invalid but no diagnostic recorded yet); full uapi jest suite 643/644 green (1 pre-existing skip); `packages/vcs` suite 7/7 green.
+- Repair (turns the black box into a source-safe diagnostic instead of resolving blind): `VCSConnections` now persists a `last_regeneration_error` (and `last_regeneration_at`) onto the connection row every time installation-token regeneration is attempted — the actual reason on failure (GitHub's own API error text; or `github_app_credentials_not_configured` if the env gate itself was skipped), or cleared to `null` on success. This flows through the existing `sanitizeConnectionMetadata` pass-through into `connectionStatus.metadata` with no other route changes needed (the new keys aren't in the token/secret blocklist). `VCSConnectionCard.tsx` now renders this reason under the badge when `!valid`. This makes the NEXT occurrence of "Refresh doesn't fix Invalid" immediately diagnosable from the card itself — for this user or anyone — without needing server log access. Verified: `tsc --noEmit` 0 (both packages); new `uapi/tests/vcsConnectionCard.test.tsx` (4/4); full uapi jest suite 643/644 green (1 pre-existing skip); `packages/vcs` suite 7/7 green. See F35 immediately below: the initial "a 404 means the installation was removed" copy this repair shipped with turned out to be WRONG for the actual case it then revealed.
 - Noted but out of scope here: `uapi/components/base/bitcode/vcs/__tests__/VCSConnectionCard.test.tsx` is a pre-existing test file for an entirely superseded implementation of this component (mocks `@supabase/auth-helpers-nextjs` directly, expects copy/icons that no longer exist) — it isn't in `jest.config.cjs`'s `testMatch` allowlist, so it silently never runs and was not caught by this drift. Left as-is; a follow-up should either delete it or rewrite it against the current component.
 
+### V48-Gate3-F35 — The 404 is a stale installation id from a DIFFERENT Bitcode GitHub App, not a removed installation — GitHub still shows the app installed (FIXED copy; DIAGNOSIS refined)
+
+- Severity: high (live-confirmed, 2026-07-08: the F34 diagnostic surfaced `Failed to generate installation token: 404 {"message":"Not Found",...}`; the org's **Installed GitHub Apps** page shows BOTH `Bitcode GitHub Auxillary` (production) AND `Bitcode GitHub Auxillary (Stag-Test)` still installed on `advancedengineeredsoftware` — disproving F34's own "the installation was removed" hint for this case).
+- Refined cause: per the Environments section above (`## Environments`, corrected 2026-07-06), there are genuinely TWO separate Bitcode GitHub App registrations — `bitcode-github-auxillary` (production-mainnet) and `bitcode-github-auxillary-stag-test` (`GITHUB_APP_ID=4224019`) — and, per the 2026-07-05 "production == staging" decision, the stag-test app's credentials were pushed to ALL THREE Vercel targets (`staginglocal-testnet`, `production`, `preview`). A connection whose stored installation id was minted under `bitcode-github-auxillary` (e.g. from before that unification, or from a flow that used the production app's install link) is invisible to a JWT signed for `bitcode-github-auxillary-stag-test` — GitHub returns 404 for "this app doesn't own that installation id," which reads identically to "the installation was removed" even though the app is very much still installed (just the OTHER one). Confirmed can't rule this out by comparing `GITHUB_APP_ID` values directly: `vercel env pull` returns encrypted vars as empty strings under this session's CLI permissions (confirmed non-sensitive vars pull fine, so this is a permission gate, not empty config).
+- Repair: corrected `VCSConnectionCard.tsx`'s 40x hint — it no longer claims "the installation was removed, reinstalling will fix it" (unverifiable and, in this case, wrong). It now says a 40x means this connection's stored installation isn't one the CURRENT deployment's app can use, even if GitHub still shows an app installed, and suggests Disconnect (in Bitcode) + reconnect — which re-runs the install/authorize flow against whichever app this deployment is actually configured with (already shown as installed in GitHub's list) and writes a fresh installation id, with no GitHub-side action needed. Updated `uapi/tests/vcsConnectionCard.test.tsx` to match. Verified: `tsc --noEmit` 0; `vcsConnectionCard.test.tsx` 4/4 green.
+- Not yet done: confirming from the Supabase side which specific `connectionId`/app the existing stuck row actually points to (would need direct DB access, out of reach here) — Disconnect + reconnect is the actionable next step for the live account; if it does NOT resolve to Valid, the next lead is confirming this Preview deployment's actual `GITHUB_APP_ID`/`SUPABASE_URL` pairing against the documented map above.
+
 ## Track 1 — Identity / Authentication / Auxillaries — COMPLETE 2026-06-12 (email deferred by decision; F2/F9 and legacy eradication queued for gates)
 
 - [x] Sign up / sign in via Connect Wallet (nav CTA → SignUpWindow → wallet signature on testnet4 → `custom:bitcode-bitcoin` session → `/tps/supabase/callback`) — verified 2026-06-12 after F5 fix; lands on `/packs`. Re-verified from fully nuked state (purged user + cleared site data): created 19:29:21 → session 19:29:25 → binding auto-written 19:29:29 by the bridge on `/packs` mount with no Auxillaries visit; UI consistent across nav, Wallet, and Profile panes.
diff --git a/uapi/components/base/bitcode/vcs/VCSConnectionCard.tsx b/uapi/components/base/bitcode/vcs/VCSConnectionCard.tsx
@@ -228,12 +228,20 @@ export function VCSConnectionCard({
               )}
             </div>
 
-            {/* V48-Gate3-F34: Refresh already retries installation-token
+            {/* V48-Gate3-F34/F35: Refresh already retries installation-token
                 regeneration silently — if it still fails, surface WHY
                 (source-safe: GitHub's own API error text, no tokens) instead
-                of leaving "Invalid" with no explanation. A 404/"Not Found"
-                here means the GitHub App installation itself was removed,
-                which Refresh can never fix — only reinstalling the app can. */}
+                of leaving "Invalid" with no explanation. A 404 here does NOT
+                reliably mean the installation was removed from GitHub — it
+                also happens when this connection's stored installation
+                belongs to a DIFFERENT Bitcode GitHub App than the one this
+                deployment is configured with (there can be more than one:
+                production vs. a staging/test app registration). GitHub still
+                showing the app installed does not rule this out. Disconnect
+                + reconnect is the cheap thing to try first — it re-runs the
+                install/authorize flow against THIS deployment's app and
+                writes a fresh installation id, no GitHub-side changes
+                needed. */}
             {!status.valid && status.metadata?.last_regeneration_error && (
               <div className="rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-xs text-destructive">
                 <p className="font-medium">Last reconnect attempt failed:</p>
@@ -244,8 +252,11 @@ export function VCSConnectionCard({
                 </p>
                 {/\b40[134]\b/.test(String(status.metadata.last_regeneration_error)) && (
                   <p className="mt-1 text-destructive/80">
-                    This usually means the GitHub App installation was removed —
-                    Refresh can&apos;t fix that; reinstalling the app will.
+                    A 40x here usually means this connection&apos;s stored GitHub
+                    App installation isn&apos;t one this deployment can use —
+                    even if GitHub still shows an app installed. Try
+                    Disconnect below, then reconnect (no need to touch
+                    anything on GitHub first).
                   </p>
                 )}
               </div>
diff --git a/uapi/tests/vcsConnectionCard.test.tsx b/uapi/tests/vcsConnectionCard.test.tsx
@@ -55,7 +55,7 @@ describe("VCSConnectionCard — regeneration-failure diagnostic (V48-Gate3-F34)"
       screen.getByText(/Failed to generate installation token: 404 Not Found/i),
     ).toBeInTheDocument();
     expect(
-      screen.getByText(/GitHub App installation was removed/i),
+      screen.getByText(/Try Disconnect below, then reconnect/i),
     ).toBeInTheDocument();
   });
 
@@ -76,7 +76,7 @@ describe("VCSConnectionCard — regeneration-failure diagnostic (V48-Gate3-F34)"
       screen.getByText(/GitHub App credentials are not configured/i),
     ).toBeInTheDocument();
     expect(
-      screen.queryByText(/GitHub App installation was removed/i),
+      screen.queryByText(/Try Disconnect below, then reconnect/i),
     ).not.toBeInTheDocument();
   });
 
