V48 Gate 3 (specification-implementation): surface why GitHub token regeneration failed instead of a bare Invalid badge (V48-Gate3-F34)

Retested after the F33 fix (deployed and confirmed live by timestamp):
Refresh still shows "Invalid." With env vars confirmed present and no way
to pull historical Vercel logs for this project, the remaining causes
(installation actually revoked on GitHub's side vs. some other bug in the
regeneration chain) were indistinguishable from the UI alone.

Rather than keep guessing blind, make the failure diagnosable: persist a
source-safe last_regeneration_error (GitHub's own API error text, or a
plain reason like missing app credentials) on the connection row every
time installation-token regeneration is attempted, cleared on success.
It flows through the existing metadata sanitizer with no other route
changes needed. VCSConnectionCard now shows this reason under the Invalid
badge, with a plain-language note that a 401/403/404 means the GitHub App
installation was removed — which only a reinstall (not Refresh) can fix.

This turns the next occurrence of "Refresh doesn't fix Invalid" into
something checkable at a glance instead of another investigation.

Also noted (not fixed here): components/base/bitcode/vcs/__tests__/
VCSConnectionCard.test.tsx tests a superseded version of this component
and isn't in jest.config.cjs's testMatch, so it silently never runs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: geraldarthurdavis

BITCODE_V48_QA.md

@@ -533,6 +533,13 @@ Track 3-4 scripts (BTD ledger, settlement, pack journaling) get added when those
 - Cause (a real bug, found by inspection): the expiry check that decides whether to regenerate reads `connectionData.installation_token_expires_at` (line ~193) — the field `_callback-handler.ts` writes at initial install. But the regeneration's own persistence call, `this.updateTokens(...)`, only ever wrote `token_expires_at` — a DIFFERENT field, never read by that check. So every regeneration attempt "succeeded" (fresh token minted, `validateToken` passes for that one request) yet the field the NEXT check reads never moved off its original, already-past value — forcing a full re-regeneration on every single subsequent call (every Refresh click, every repo/branch/commit fetch that reaches this path) forever. Separately, `GET /api/vcs/[provider]/connection` built the returned status from the `connection` row fetched BEFORE `validateStoredConnection` ran, so even a successful in-request regeneration wouldn't show its fresh `expiresAt`/metadata until a subsequent call.
 - Repair: `VCSConnections.updateTokens` now writes `installation_token_expires_at` alongside `token_expires_at` (its only caller is this one GitHub-App regeneration path, so this is safe with no other call sites to consider). `GET /api/vcs/[provider]/connection` now re-fetches the connection after a successful `validateStoredConnection` before building the response, so a same-request regeneration is reflected immediately instead of one Refresh click behind. Note: if the GitHub App installation itself was actually revoked/uninstalled on GitHub's side (not just an expired token), regeneration will keep failing and Disconnect+reinstall genuinely is required then — check https://github.com/settings/installations (or the org's) to tell the two apart. Verified: `tsc --noEmit` 0 (both packages); new `packages/vcs/src/__tests__/connections.test.ts` (2/2, pins both fields moving together and that a fresh token skips re-regeneration); full uapi jest suite 639/640 green (1 pre-existing skip).
 
+### V48-Gate3-F34 — Refreshing GitHub still showed bare "Invalid" after the F33 fix, no way to tell why (FIXED)
+
+- 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.
+- 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.
+
 ## 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.

packages/vcs/src/connections.ts

@@ -35,6 +35,9 @@ interface PersistedConnectionData {
   installation_token_expires_at?: unknown;
   oauth_token?: unknown;
   instance_url?: unknown;
+  /** V48-Gate3-F34: source-safe reason the last regeneration attempt failed, or null on success. */
+  last_regeneration_error?: unknown;
+  last_regeneration_at?: unknown;
   [key: string]: unknown;
 }
 
@@ -206,40 +209,60 @@ export class VCSConnections {
             const { GitHubAppAuth } = await import('@bitcode/github');
             const appId = process.env.GITHUB_APP_ID;
             const privateKey = process.env.GITHUB_PRIVATE_KEY;
-            
+
             if (appId && privateKey) {
               const githubApp = new GitHubAppAuth({
                 appId,
                 privateKey,
                 clientId: process.env.GITHUB_APP_CLIENT_ID,
                 clientSecret: process.env.GITHUB_APP_CLIENT_SECRET
               });
-              
+
               // Don't request specific permissions - use whatever the installation has granted
               // This avoids 422 errors when requesting permissions not available to the installation
               const tokenData = await githubApp.generateInstallationToken(
                 Number(installationConnectionId)
                 // Omitting permissions parameter to use installation's granted permissions
               );
-              
+
               accessToken = tokenData.token;
-              
+
               // Update the connection with new token
               await this.updateTokens(connection.id, {
                 accessToken: tokenData.token,
                 expiresAt: tokenData.expiresAt
               });
-              
+              // Clear any prior failure diagnostic now that regeneration succeeded.
+              await this.recordRegenerationDiagnostic(connection.id, null);
+
               log('GitHub installation token regenerated successfully', 'info', {
                 connectionId,
                 expiresAt: tokenData.expiresAt
               });
+            } else {
+              // V48-Gate3-F34: env misconfiguration (missing GITHUB_APP_ID/
+              // GITHUB_PRIVATE_KEY on this deployment target) silently no-op'd
+              // here before — the stale token then failed live validation with
+              // no trace of WHY, indistinguishable from a genuinely revoked
+              // installation. Persist a source-safe reason so Invalid is
+              // diagnosable without server log access.
+              await this.recordRegenerationDiagnostic(
+                connection.id,
+                'github_app_credentials_not_configured',
+              );
             }
           } catch (error) {
+            const reason = error instanceof Error ? error.message : 'unknown_regeneration_error';
             log('Failed to regenerate GitHub installation token', 'error', {
               connectionId,
               error
             });
+            // V48-Gate3-F34: persist WHY regeneration failed (source-safe —
+            // GitHub's own API error text, e.g. installation suspended/
+            // uninstalled — no tokens/secrets) so a stuck-Invalid connection
+            // is diagnosable from the connection status alone, without
+            // needing server logs.
+            await this.recordRegenerationDiagnostic(connection.id, reason);
             // Fall back to OAuth token if available
             accessToken = readString(connectionData.oauth_token);
           }
@@ -344,7 +367,36 @@ export class VCSConnections {
       );
     }
   }
-  
+
+  /**
+   * V48-Gate3-F34: persist the outcome of the last GitHub App installation
+   * token regeneration attempt (source-safe reason text only — never a
+   * token/secret) so a connection stuck on "Invalid" is diagnosable from the
+   * stored connection alone. Best-effort: a failure here must never mask the
+   * original regeneration error, so it's swallowed.
+   */
+  private async recordRegenerationDiagnostic(
+    connectionId: string,
+    reason: string | null
+  ): Promise<void> {
+    try {
+      const connection = await this.connections.getById(connectionId);
+      if (!connection) return;
+      const connectionData = asConnectionData(connection.connection_data);
+      const nextConnectionData = {
+        ...connectionData,
+        last_regeneration_error: reason,
+        last_regeneration_at: new Date().toISOString()
+      } as Database['public']['Tables']['user_connections']['Update']['connection_data'];
+
+      await this.connections.update(connectionId, {
+        connection_data: nextConnectionData
+      });
+    } catch (error) {
+      log('Failed to record regeneration diagnostic', 'warn', { error, connectionId });
+    }
+  }
+
   /**
    * Delete a connection
    */

uapi/components/base/bitcode/vcs/VCSConnectionCard.tsx

@@ -227,7 +227,30 @@ export function VCSConnectionCard({
                 </div>
               )}
             </div>
-            
+
+            {/* V48-Gate3-F34: 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. */}
+            {!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>
+                <p className="mt-1 break-words">
+                  {status.metadata.last_regeneration_error === 'github_app_credentials_not_configured'
+                    ? 'The Bitcode GitHub App credentials are not configured on this deployment.'
+                    : String(status.metadata.last_regeneration_error)}
+                </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.
+                  </p>
+                )}
+              </div>
+            )}
+
             <div className="flex gap-2">
               <Button
                 variant="outline"

uapi/jest.config.cjs

@@ -153,6 +153,7 @@ module.exports = {
     '<rootDir>/tests/productAnalytics.test.ts',
     '<rootDir>/tests/searchableSelect.test.tsx',
     '<rootDir>/tests/vcsFileTreePicker.test.tsx',
+    '<rootDir>/tests/vcsConnectionCard.test.tsx',
     '<rootDir>/tests/bitcodeInlineExplainerAriaLabel.test.tsx',
     '<rootDir>/tests/readRouteModel.test.ts',
     '<rootDir>/tests/readPageClient.test.tsx',

uapi/tests/vcsConnectionCard.test.tsx

@@ -0,0 +1,96 @@
+import "@testing-library/jest-dom";
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+
+import { VCSConnectionCard } from "@/components/base/bitcode/vcs/VCSConnectionCard";
+
+// V48-Gate3-F34: when a stored GitHub connection is Invalid, Refresh already
+// silently retries installation-token regeneration (V48-Gate3-F33) — but if
+// regeneration itself keeps failing, the card used to show only "Invalid"
+// with no way to tell why, indistinguishable from a genuinely revoked
+// installation. This suite pins the new diagnostic surfacing.
+
+function mockConnectionFetch(payload: Record<string, unknown>) {
+  global.fetch = jest.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    headers: { get: () => "application/json" },
+    json: async () => payload,
+  }) as unknown as typeof fetch;
+}
+
+describe("VCSConnectionCard — regeneration-failure diagnostic (V48-Gate3-F34)", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("shows nothing extra when the connection is valid", async () => {
+    mockConnectionFetch({
+      connected: true,
+      valid: true,
+      username: "bitcode",
+      metadata: {},
+    });
+
+    render(<VCSConnectionCard provider="github" />);
+
+    await screen.findByText("bitcode");
+    expect(screen.queryByText(/Last reconnect attempt failed/i)).not.toBeInTheDocument();
+  });
+
+  it("surfaces the source-safe regeneration failure reason when invalid", async () => {
+    mockConnectionFetch({
+      connected: true,
+      valid: false,
+      username: "advancedengineeredsoftware",
+      metadata: {
+        last_regeneration_error: "Failed to generate installation token: 404 Not Found",
+      },
+    });
+
+    render(<VCSConnectionCard provider="github" />);
+
+    await screen.findByText(/Last reconnect attempt failed/i);
+    expect(
+      screen.getByText(/Failed to generate installation token: 404 Not Found/i),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByText(/GitHub App installation was removed/i),
+    ).toBeInTheDocument();
+  });
+
+  it("maps the missing-credentials reason to a clear message without the reinstall hint", async () => {
+    mockConnectionFetch({
+      connected: true,
+      valid: false,
+      username: "advancedengineeredsoftware",
+      metadata: {
+        last_regeneration_error: "github_app_credentials_not_configured",
+      },
+    });
+
+    render(<VCSConnectionCard provider="github" />);
+
+    await screen.findByText(/Last reconnect attempt failed/i);
+    expect(
+      screen.getByText(/GitHub App credentials are not configured/i),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(/GitHub App installation was removed/i),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows nothing extra when invalid but no diagnostic has been recorded yet", async () => {
+    mockConnectionFetch({
+      connected: true,
+      valid: false,
+      username: "advancedengineeredsoftware",
+      metadata: {},
+    });
+
+    render(<VCSConnectionCard provider="github" />);
+
+    await waitFor(() => expect(screen.getByText("Invalid")).toBeInTheDocument());
+    expect(screen.queryByText(/Last reconnect attempt failed/i)).not.toBeInTheDocument();
+  });
+});