@@ -267,9 +267,12 @@ export function openBrowser(
  * authorize URL, and wait for the redirect back to `http://localhost:PORT/callback`.
  *
  * The server validates the `state` it appended to the callback URL against the
- * incoming request, renders a success/error HTML page, and resolves with the
- * callback request's search params (the caller reads `code` / `link_code` etc.).
- * The server is always closed before settling.
+ * incoming request, then runs the caller's `finalize` hook INSIDE the request
+ * handler (so the browser only ever sees the success page after the underlying
+ * exchange/link actually succeeded). On finalize success it renders the success
+ * HTML and resolves with finalize's return value; on finalize failure it
+ * renders the same "could not complete" failure page the login flow uses and
+ * rejects with the thrown error. The server is always closed before settling.
  *
  * `onUrl` is invoked with the authorize URL once the local server is listening,
  * so callers can show the URL to the user as a manual fallback when the browser
@@ -278,11 +281,18 @@ export function openBrowser(
  *
  * `execFile` is injectable so tests can avoid launching a real browser.
  */
-export async function awaitBrowserCallback(options: {
+export async function awaitBrowserCallback<T>(options: {
   /** Caller-generated; appended to the callback URL and validated on the incoming request. */
   state: string;
   /** Given `http://localhost:PORT/callback?state=…`, return the URL to open. */
   buildAuthUrl: (callback: URL) => Promise<string> | string;
+  /**
+   * Runs INSIDE the request handler, after state/error/validate checks pass and
+   * BEFORE the success page is rendered. Resolve to settle the outer promise
+   * with this value (success page shown); throw to render the failure page and
+   * reject the outer promise with the thrown error.
+   */
+  finalize: (params: URLSearchParams) => Promise<T>;
   /** Map an `?error=…` query to a user message (return null to ignore). */
   describeError?: (params: URLSearchParams) => string | null;
   /**
@@ -298,13 +308,13 @@ export async function awaitBrowserCallback(options: {
   timeoutMs?: number;
   /** Injectable for tests; defaults to the real `node:child_process` `execFile`. */
   execFile?: typeof import('node:child_process').execFile;
-}): Promise<URLSearchParams> {
+}): Promise<T> {
   const http = await import('node:http');
-  const { state, buildAuthUrl, describeError, validate, onUrl } = options;
+  const { state, buildAuthUrl, finalize, describeError, validate, onUrl } = options;
   const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
   const execFile = options.execFile ?? (await import('node:child_process')).execFile;
 
-  return new Promise<URLSearchParams>((resolve, reject) => {
+  return new Promise<T>((resolve, reject) => {
     let settled = false;
 
     const fail = (error: Error): void => {
@@ -316,16 +326,16 @@ export async function awaitBrowserCallback(options: {
       reject(error);
     };
 
-    const succeed = (params: URLSearchParams): void => {
+    const succeed = (result: T): void => {
       if (settled) {
         return;
       }
       settled = true;
       server.close();
-      resolve(params);
+      resolve(result);
     };
 
-    const server = http.createServer((req, res) => {
+    const server = http.createServer(async (req, res) => {
       const url = new URL(req.url!, `http://localhost`);
       if (url.pathname !== '/callback') {
         res.writeHead(404);
@@ -357,9 +367,30 @@ export async function awaitBrowserCallback(options: {
         return;
       }
 
+      // Finalize INSIDE the request path so the browser only sees the success
+      // page once the underlying exchange/link succeeds. A finalize failure
+      // (expired code, API error, 409 conflict, etc.) renders the failure page
+      // and rejects — matching the base login flow's exchange-in-request-path
+      // behavior. Guard against the timeout racing the in-flight finalize.
+      let result: T;
+      try {
+        result = await finalize(url.searchParams);
+      } catch (err) {
+        if (settled) {
+          return;
+        }
+        res.writeHead(400, { 'Content-Type': 'text/html' });
+        res.end(page('Login failed', 'Could not complete login. Please try again.'));
+        fail(err instanceof Error ? err : new Error('auth: Failed to complete login.'));
+        return;
+      }
+
+      if (settled) {
+        return;
+      }
       res.writeHead(200, { 'Content-Type': 'text/html' });
       res.end(page('Login successful!', 'You can close this tab and return to the terminal.'));
-      succeed(url.searchParams);
+      succeed(result);
     });
 
     // Close immediately after callback — don't wait for keep-alive timeout
@@ -416,7 +447,9 @@ export async function runLogin(
   const codeVerifier = createCodeVerifier();
   const codeChallenge = createCodeChallenge(codeVerifier);
 
-  const params = await awaitBrowserCallback({
+  // The exchange runs INSIDE the request handler (via finalize), so an exchange
+  // failure renders the failure page — exactly as the base login flow did.
+  return awaitBrowserCallback<string>({
     state,
     execFile,
     onUrl,
@@ -444,8 +477,6 @@ export async function runLogin(
       }
       return null;
     },
+    finalize: (params) => exchangeLoginCode(apiUrl, params.get('code')!, state, codeVerifier),
   });
-
-  const code = params.get('code')!;
-  return exchangeLoginCode(apiUrl, code, state, codeVerifier);
 }
@@ -152,11 +152,21 @@ export async function runInstall(
       await linkIdentity(root, client);
       try {
         ({ url } = await client.getGithubInstallUrl());
-      } catch {
-        log.error(
-          'Could not start the GitHub App install after linking. Try `void github link`, then `void github install` again.',
-        );
-        process.exit(1);
+      } catch (retryErr) {
+        // Only the SAME identity-required 403 means linking didn't take — show
+        // the actionable link/install guidance. Any other failure (401, 426,
+        // 500, a different 403) is the real error and must surface normally.
+        if (
+          retryErr instanceof PlatformApiError &&
+          retryErr.status === 403 &&
+          retryErr.code === 'github_identity_required'
+        ) {
+          log.error(
+            'Could not start the GitHub App install after linking. Try `void github link`, then `void github install` again.',
+          );
+          process.exit(1);
+        }
+        throw retryErr;
       }
     } else {
       throw err;
@@ -189,25 +199,28 @@ export async function runGithubLink(root: string, client: PlatformClient): Promi
   const challenge = createCodeChallenge(verifier);
   const state = randomBytes(32).toString('hex');
 
-  const params = await awaitBrowserCallback({
-    state,
-    buildAuthUrl: async (callback) => {
-      callback.searchParams.set('state', state);
-      const { url } = await client.getGithubLinkUrl(callback.href, challenge);
-      return url;
-    },
-    describeError: (p) => (p.get('error') ? 'GitHub authorization failed.' : null),
-    onUrl: (url) => log.message(`Open this URL to link your GitHub account:\n${pc.cyan(url)}`),
-  });
-
-  const linkCode = params.get('link_code');
-  if (!linkCode) {
-    throw new Error('github: link callback did not return a link code.');
-  }
-
+  // completeGithubLink runs INSIDE the request handler (via finalize), so the
+  // browser only shows the success page after the link actually succeeds; a 409
+  // conflict rejects out of awaitBrowserCallback and is mapped below.
   let status: 'linked' | 'already_linked';
   try {
-    ({ status } = await client.completeGithubLink(linkCode, verifier));
+    ({ status } = await awaitBrowserCallback<{ status: 'linked' | 'already_linked' }>({
+      state,
+      buildAuthUrl: async (callback) => {
+        callback.searchParams.set('state', state);
+        const { url } = await client.getGithubLinkUrl(callback.href, challenge);
+        return url;
+      },
+      describeError: (p) => (p.get('error') ? 'GitHub authorization failed.' : null),
+      onUrl: (url) => log.message(`Open this URL to link your GitHub account:\n${pc.cyan(url)}`),
+      finalize: async (params) => {
+        const linkCode = params.get('link_code');
+        if (!linkCode) {
+          throw new Error('github: link callback did not return a link code.');
+        }
+        return client.completeGithubLink(linkCode, verifier);
+      },
+    }));
   } catch (err) {
     if (err instanceof PlatformApiError && err.code === 'github_already_linked') {
       log.error('Your Void account is already linked to a different GitHub account.');
 
@@ -10,11 +10,12 @@ const noopExecFile = vi.fn() as unknown as typeof import('node:child_process').e
  * (built from the localhost callback). Returns the callback URL so the test can
  * drive the localhost server directly.
  */
-function startCallback(options?: {
+function startCallback<T = URLSearchParams>(options?: {
   describeError?: (params: URLSearchParams) => string | null;
+  finalize?: (params: URLSearchParams) => Promise<T>;
   state?: string;
 }): {
-  resultPromise: Promise<URLSearchParams>;
+  resultPromise: Promise<T>;
   callbackPromise: Promise<URL>;
   state: string;
 } {
@@ -24,10 +25,14 @@ function startCallback(options?: {
     resolveCallback = resolve;
   });
 
-  const resultPromise = awaitBrowserCallback({
+  const finalize =
+    options?.finalize ?? ((params: URLSearchParams) => Promise.resolve(params as unknown as T));
+
+  const resultPromise = awaitBrowserCallback<T>({
     state,
     execFile: noopExecFile,
     describeError: options?.describeError,
+    finalize,
     buildAuthUrl: (callback) => {
       resolveCallback(callback);
       return 'https://example.test/authorize';
@@ -38,8 +43,11 @@ function startCallback(options?: {
 }
 
 describe('awaitBrowserCallback', () => {
-  it('resolves with the callback params on a valid /callback request', async () => {
-    const { resultPromise, callbackPromise, state } = startCallback();
+  it('runs finalize in the request path and resolves with its return value', async () => {
+    const finalize = vi.fn(async (params: URLSearchParams) => ({
+      linked: params.get('link_code'),
+    }));
+    const { resultPromise, callbackPromise, state } = startCallback({ finalize });
     const callback = await callbackPromise;
 
     // The helper appends the caller-supplied state to the callback URL.
@@ -54,13 +62,45 @@ describe('awaitBrowserCallback', () => {
     const res = await fetch(hit);
     expect(res.status).toBe(200);
 
-    const params = await resultPromise;
-    expect(params.get('link_code')).toBe('abc');
-    expect(params.get('state')).toBe(state);
+    // finalize ran inside the request handler with the callback params, and the
+    // outer promise resolves with finalize's return value.
+    expect(finalize).toHaveBeenCalledTimes(1);
+    expect(finalize.mock.calls[0]![0].get('link_code')).toBe('abc');
+    expect(finalize.mock.calls[0]![0].get('state')).toBe(state);
+
+    await expect(resultPromise).resolves.toEqual({ linked: 'abc' });
   });
 
-  it('returns 400 and keeps listening on a state mismatch (does not resolve)', async () => {
-    const { resultPromise, callbackPromise, state } = startCallback();
+  it('renders the failure page and rejects when finalize throws (F3 regression pin)', async () => {
+    const finalizeError = new Error('exchange blew up');
+    const finalize = vi.fn(async () => {
+      throw finalizeError;
+    });
+    const { resultPromise, callbackPromise, state } = startCallback({ finalize });
+    const callback = await callbackPromise;
+
+    // Attach the rejection assertion before triggering the request so the
+    // handler is in place when the promise settles (no unhandled rejection).
+    const rejection = expect(resultPromise).rejects.toBe(finalizeError);
+
+    const hit = new URL(callback);
+    hit.searchParams.set('state', state);
+    hit.searchParams.set('link_code', 'abc');
+
+    const res = await fetch(hit);
+    // The browser must NOT see the success page when finalize fails.
+    expect(res.status).toBe(400);
+    const body = await res.text();
+    expect(body).not.toContain('successful');
+    expect(body).toContain('Could not complete');
+
+    expect(finalize).toHaveBeenCalledTimes(1);
+    await rejection;
+  });
+
+  it('returns 400 and keeps listening on a state mismatch (does not call finalize)', async () => {
+    const finalize = vi.fn(async (params: URLSearchParams) => params);
+    const { resultPromise, callbackPromise, state } = startCallback({ finalize });
     const callback = await callbackPromise;
 
     const bad = new URL(callback);
@@ -70,6 +110,9 @@ describe('awaitBrowserCallback', () => {
     const badRes = await fetch(bad);
     expect(badRes.status).toBe(400);
 
+    // A state mismatch is rejected before finalize runs.
+    expect(finalize).not.toHaveBeenCalled();
+
     // The genuine callback still completes — the server stayed open.
     const good = new URL(callback);
     good.searchParams.set('state', state);
@@ -79,6 +122,7 @@ describe('awaitBrowserCallback', () => {
     expect(goodRes.status).toBe(200);
 
     const params = await resultPromise;
+    expect(finalize).toHaveBeenCalledTimes(1);
     expect(params.get('link_code')).toBe('real');
   });
 
@@ -107,6 +151,7 @@ describe('awaitBrowserCallback', () => {
       state: 'timeout-state',
       execFile: noopExecFile,
       timeoutMs: 10,
+      finalize: async (params) => params,
       buildAuthUrl: (callback) =>
         `https://example.test/authorize?cb=${encodeURIComponent(callback.href)}`,
     });
@@ -124,6 +169,7 @@ describe('awaitBrowserCallback', () => {
     const resultPromise = awaitBrowserCallback({
       state: 's',
       execFile,
+      finalize: async (params) => params,
       buildAuthUrl: (callback) => {
         resolveCallback(callback);
         return 'https://example.test/authorize';
 
@@ -138,6 +138,46 @@ describe('runLogin', () => {
     await expect(loginPromise).resolves.toBe('real-token');
   });
 
+  it('shows the failure page and throws when the code exchange fails (F3 regression)', async () => {
+    // Override fetch so the localhost callback still hits the real server, but
+    // the API token exchange returns a non-ok response (expired code, etc.).
+    vi.stubGlobal('fetch', async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url =
+        input instanceof Request ? input.url : input instanceof URL ? input.href : input.toString();
+      if (url.startsWith('http://localhost:')) {
+        return originalFetch(input, init);
+      }
+      return new Response('expired', { status: 400 });
+    });
+
+    let resolveLoginUrl!: (url: string) => void;
+    const loginUrlPromise = new Promise<string>((resolve) => {
+      resolveLoginUrl = resolve;
+    });
+
+    const loginPromise = runLogin('/project', 'github', resolveLoginUrl);
+    // Attach the rejection assertion up front so the exchange failure doesn't
+    // surface as an unhandled rejection.
+    const rejection = expect(loginPromise).rejects.toThrow(/Failed to exchange login code/);
+
+    const loginUrl = new URL(await loginUrlPromise);
+    const redirect = loginUrl.searchParams.get('redirect');
+    expect(redirect).toBeTruthy();
+
+    const validUrl = new URL(redirect!);
+    validUrl.searchParams.set('code', 'real-code');
+
+    const validResponse = await fetch(validUrl);
+    // The exchange ran INSIDE the request handler and failed → failure page,
+    // never the success page.
+    expect(validResponse.status).toBe(400);
+    const body = await validResponse.text();
+    expect(body).not.toContain('successful');
+    expect(body).toContain('Could not complete');
+
+    await rejection;
+  });
+
   it('sends Cloudflare Access headers when exchanging the login code', async () => {
     process.env.CF_ACCESS_TOKEN = 'cf-access-token';