fix(server): report a pending SSH key approval instead of a generic fetch timeout

apps/server/src/vcs/GitVcsDriverCore.test.ts

@@ -6566,6 +6566,226 @@ it.layer(layerTest)("GitVcsDriver core integration", (it) => {
   });
 
   describe("remote operations", () => {
+    describe("SSH key approval", () => {
+      // OpenSSH DEBUG3 output while the agent is waiting for approval to sign.
+      const signing =
+        "debug1: Server accepts key: test-key ED25519 SHA256:test\n" +
+        "debug3: sign_and_send_pubkey: using publickey with ED25519 SHA256:test\n" +
+        "debug3: sign_and_send_pubkey: signing using ssh-ed25519 SHA256:test\n";
+      const startFetch = Effect.fnUntraced(function* (
+        stderr: Stream.Stream<string>,
+        options: {
+          sshCommand?: string;
+          envCommand?: string;
+          platform?: NodeJS.Platform;
+          hiddenConfig?: boolean;
+          submodules?: boolean;
+          fetchErrors?: readonly string[];
+        } = {},
+      ) {
+        const cwd = yield* makeTmpDir();
+        yield* git(cwd, ["init"]);
+        if (options.sshCommand !== undefined) {
+          yield* git(cwd, ["config", "core.sshCommand", options.sshCommand]);
+        }
+        const {
+          GIT_SSH_COMMAND: _command,
+          GIT_SSH: _ssh,
+          GIT_SSH_VARIANT: _variant,
+          GIT_CONFIG: _config,
+          ...hostEnvironment
+        } = yield* HostProcess.Environment;
+        const environment: NodeJS.ProcessEnv = {
+          ...hostEnvironment,
+          ...(options.envCommand !== undefined && { GIT_SSH_COMMAND: options.envCommand }),
+        };
+        if (options.hiddenConfig) {
+          yield* writeTextFile(cwd, "empty-config", "");
+          environment.GIT_CONFIG = (yield* Path.Path).join(cwd, "empty-config");
+        }
+        let fetchCwd = cwd;
+        if (options.submodules) {
+          yield* git(cwd, ["config", "fetch.recurseSubmodules", "true"]);
+          yield* writeTextFile(
+            cwd,
+            ".gitmodules",
+            '[submodule "child"]\n\tpath = child\n\turl = git@example.com:child.git\n',
+          );
+          fetchCwd = (yield* Path.Path).join(cwd, "nested");
+          yield* (yield* FileSystem.FileSystem).makeDirectory(fetchCwd);
+        }
+        const delegate = yield* ChildProcessSpawner.ChildProcessSpawner;
+        const started = yield* Deferred.make<void>();
+        const stderrRead = yield* Deferred.make<void>();
+        const exit = yield* Deferred.make<void>();
+        const released = yield* Deferred.make<void>();
+        const fetches: Array<CommandLine.Word | undefined> = [];
+        const attempts: Array<readonly CommandLine.Word[]> = [];
+        const spawner = ChildProcessSpawner.make((command) =>
+          Effect.gen(function* () {
+            if (!ChildProcess.isStandardCommand(command))
+              return yield* Effect.die("unexpected command");
+            if (command.args[0] !== "fetch") return yield* delegate.spawn(command);
+            const fetchError = options.fetchErrors?.[fetches.length];
+            fetches.push(command.options.env?.GIT_SSH_COMMAND);
+            attempts.push(command.args);
+            yield* Effect.addFinalizer(() => Deferred.succeed(released, undefined));
+            yield* Deferred.succeed(started, undefined);
+            return ChildProcessSpawner.makeHandle({
+              ...makeSuccessfulHandle(""),
+              exitCode: Deferred.await(exit).pipe(
+                Effect.as(ChildProcessSpawner.ExitCode(fetchError === undefined ? 0 : 128)),
+              ),
+              stderr: Stream.encodeText(
+                fetchError === undefined ? stderr : Stream.concat(stderr, Stream.make(fetchError)),
+              ).pipe(Stream.ensuring(Deferred.succeed(stderrRead, undefined))),
+            });
+          }),
+        );
+        const driver = yield* makeGitVcsDriverCore().pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(HostProcess.Platform, options.platform ?? "linux"),
+          Effect.provide(layerServerConfig),
+        );
+        const fetching = yield* driver
+          .fetchRemote({ cwd: fetchCwd, remoteName: "origin", refName: "main" })
+          .pipe(
+            Effect.provideService(HostProcess.Environment, environment),
+            Effect.result,
+            Effect.forkChild({ startImmediately: true }),
+          );
+        yield* Deferred.await(started);
+        return { fetching, stderrRead, exit, released, fetches, attempts };
+      });
+
+      it.effect("reports pending approval at the command timeout and releases the fetch", () =>
+        Effect.gen(function* () {
+          const fetch = yield* startFetch(Stream.make(signing));
+          yield* Deferred.await(fetch.stderrRead);
+          yield* TestClock.adjust("31 seconds");
+          assert.isTrue(yield* Deferred.isDone(fetch.released));
+          const result = yield* Fiber.join(fetch.fetching);
+          assert.isTrue(Result.isFailure(result));
+          if (Result.isFailure(result)) {
+            assert.equal(
+              result.failure.detail,
+              "SSH key authorization timed out. Approve or unlock the SSH key on the computer running T3 Code, then retry, or use an HTTPS remote.",
+            );
+          }
+          assert.lengthOf(fetch.fetches, 1);
+          assert.isFalse(yield* Deferred.isDone(fetch.exit));
+        }),
+      );
+
+      it.effect("lets an approval that arrives before the command timeout finish", () =>
+        Effect.gen(function* () {
+          const approved = yield* Deferred.make<void>();
+          const fetch = yield* startFetch(
+            Stream.concat(
+              Stream.make(signing),
+              Stream.fromEffect(
+                Deferred.await(approved).pipe(Effect.as("debug3: send packet: type 50\n")),
+              ),
+            ),
+          );
+          yield* TestClock.adjust("15 seconds");
+          yield* Deferred.succeed(approved, undefined);
+          yield* Deferred.await(fetch.stderrRead);
+          yield* Deferred.succeed(fetch.exit, undefined);
+          assert.deepEqual(yield* Fiber.join(fetch.fetching), Result.succeed(undefined));
+        }),
+      );
+
+      it.effect("allows a slow server and signing past the output cap to finish", () =>
+        Effect.gen(function* () {
+          const connected = yield* Deferred.make<void>();
+          // Arm just before the cap; the signed packet must still clear the watch after it.
+          const output = signing.padStart(1_000_000, "\n");
+          const fetch = yield* startFetch(
+            Stream.concat(
+              Stream.fromEffect(Deferred.await(connected).pipe(Effect.as(output))),
+              Stream.make("debug3: send packet: type 50\n"),
+            ),
+          );
+          yield* TestClock.adjust("12 seconds");
+          yield* Deferred.succeed(connected, undefined);
+          yield* Deferred.await(fetch.stderrRead);
+          yield* TestClock.adjust("15 seconds");
+          yield* Deferred.succeed(fetch.exit, undefined);
+          assert.deepEqual(yield* Fiber.join(fetch.fetching), Result.succeed(undefined));
+          assert.isTrue(yield* Deferred.isDone(fetch.released));
+        }),
+      );
+
+      it.effect("releases a pending fetch when its caller cancels", () =>
+        Effect.gen(function* () {
+          const fetch = yield* startFetch(Stream.make(signing));
+          yield* Deferred.await(fetch.stderrRead);
+          yield* Fiber.interrupt(fetch.fetching);
+          assert.isTrue(yield* Deferred.isDone(fetch.released));
+          assert.isFalse(yield* Deferred.isDone(fetch.exit));
+        }),
+      );
+
+      it.effect("keeps retry and error diagnostics after verbose SSH output", () =>
+        Effect.gen(function* () {
+          const fetch = yield* startFetch(
+            Stream.make("debug3: channel 0: rcvd adjust 2097152\n".repeat(30_000)),
+            {
+              fetchErrors: [
+                "error: cannot lock ref 'refs/remotes/origin/main': is at abc but expected def\n",
+                "fatal: Authentication failed\n",
+              ],
+            },
+          );
+          yield* Deferred.await(fetch.stderrRead);
+          yield* Deferred.succeed(fetch.exit, undefined);
+          const result = yield* Fiber.join(fetch.fetching);
+          assert.isTrue(Result.isFailure(result));
+          if (Result.isFailure(result)) {
+            assert.equal(
+              result.failure.detail,
+              "Git could not authenticate with the remote. Check Git credentials or SSH access on the server, then retry.",
+            );
+          }
+          const scoped = [
+            "fetch",
+            "--quiet",
+            "--no-tags",
+            "--",
+            "origin",
+            "+refs/heads/main:refs/remotes/origin/main",
+          ];
+          assert.deepEqual(fetch.attempts, [scoped, scoped]);
+          assert.isTrue(yield* Deferred.isDone(fetch.released));
+        }),
+      );
+
+      it.effect.each([
+        { name: "configured SSH", sshCommand: "ssh -v" },
+        { name: "an environment SSH override", envCommand: "ssh -v" },
+        { name: "Windows", platform: "win32" },
+        {
+          name: "SSH configuration hidden by GIT_CONFIG",
+          sshCommand: "ssh -v",
+          hiddenConfig: true,
+        },
+        { name: "submodule SSH configuration from a nested directory", submodules: true },
+      ] as const)("preserves $name without treating its output as pending approval", (options) =>
+        Effect.gen(function* () {
+          const fetch = yield* startFetch(Stream.make(signing), options);
+          yield* Deferred.await(fetch.stderrRead);
+          yield* TestClock.adjust("15 seconds");
+          yield* Deferred.succeed(fetch.exit, undefined);
+          assert.deepEqual(yield* Fiber.join(fetch.fetching), Result.succeed(undefined));
+          assert.deepEqual(fetch.fetches, [
+            "envCommand" in options ? options.envCommand : undefined,
+          ]);
+          assert.isTrue(yield* Deferred.isDone(fetch.released));
+        }),
+      );
+    });
+
     it.effect("creates a worktree from the latest fetched remote commit", () =>
       Effect.gen(function* () {
         const cwd = yield* makeTmpDir();

apps/server/src/vcs/GitVcsDriverCore.ts

@@ -125,6 +125,14 @@ const STATUS_UPSTREAM_REFRESH_ENV = Object.freeze({
   SSH_ASKPASS: "",
   SSH_ASKPASS_REQUIRE: "never",
 } satisfies NodeJS.ProcessEnv);
+// At LogLevel=DEBUG3, ssh logs "Server accepts key", then only signing-code lines while a
+// GUI agent holds the signature for the user's approval, then "send packet: type 50" for
+// the signed request. Unlike `-v`, LogLevel lets a ControlPersist master close stderr.
+const SSH_SIGN_REQUEST_LINE_PREFIX = "debug1: Server accepts key:";
+const SSH_SIGNING_LINE = /^debug\d: (?:input_userauth_pk_ok|sign_and_send_pubkey): /;
+const GIT_COMMAND_TIMEOUT_DETAIL = "Git command timed out.";
+const SSH_KEY_APPROVAL_TIMEOUT_DETAIL =
+  "SSH key authorization timed out. Approve or unlock the SSH key on the computer running T3 Code, then retry, or use an HTTPS remote.";
 const DEFAULT_BASE_BRANCH_CANDIDATES = ["main", "master"] as const;
 const GIT_LIST_BRANCHES_DEFAULT_LIMIT = 100;
 const NON_REPOSITORY_STATUS_DETAILS = Object.freeze<GitVcsDriver.GitStatusDetails>({
@@ -1107,7 +1115,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
             () =>
               new GitCommandError({
                 ...gitCommandContext(commandInput),
-                detail: "Git command timed out.",
+                detail: GIT_COMMAND_TIMEOUT_DETAIL,
               }),
           ),
         ),
@@ -4782,24 +4790,95 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     });
 
   const fetchRemote = Effect.fn("fetchRemote")(function* (input: GitVcsDriver.GitFetchRemoteInput) {
+    // Only Git's default OpenSSH is watched: GIT_SSH_COMMAND would replace a
+    // configured command, and Git for Windows may run another ssh.
+    const hostEnvironment = yield* HostProcess.Environment;
+    const watchSshApproval =
+      hostPlatform !== "win32" &&
+      ["GIT_SSH_COMMAND", "GIT_SSH", "GIT_SSH_VARIANT"].every(
+        (key) => hostEnvironment[key] === undefined,
+      ) &&
+      // GIT_CONFIG redirects `git config`, but fetch still reads repository config.
+      hostEnvironment.GIT_CONFIG === undefined &&
+      (yield* Effect.gen(function* () {
+        const config = yield* executeGit(
+          "GitVcsDriver.fetchRemote.sshConfig",
+          input.cwd,
+          ["config", "--get-regexp", "^(core\\.sshcommand|ssh\\.variant|submodule\\..*\\.url)$"],
+          { allowNonZeroExit: true },
+        );
+        if (config.exitCode !== 1) return false;
+        // Recursive fetch inherits GIT_SSH_COMMAND over submodules' own SSH commands.
+        const root = yield* runGitStdout("GitVcsDriver.fetchRemote.repositoryRoot", input.cwd, [
+          "rev-parse",
+          "--show-toplevel",
+        ]);
+        return (
+          root.trim().length > 0 &&
+          !(yield* fileSystem.exists(path.join(root.trim(), ".gitmodules")))
+        );
+      }).pipe(Effect.orElseSucceed(() => false)));
     const args = ["fetch", "--quiet", "--", input.remoteName];
     const options = {
       env: STATUS_UPSTREAM_REFRESH_ENV,
       fallbackErrorDetail: `git fetch ${input.remoteName} failed`,
+      ...(watchSshApproval && {
+        env: { ...STATUS_UPSTREAM_REFRESH_ENV, GIT_SSH_COMMAND: "ssh -o LogLevel=DEBUG3" },
+        appendTruncationMarker: true,
+        keepLineCallbacksAfterTruncation: true,
+      }),
     };
     // Another fetch in the same repository, such as the background status
     // poll, can win the race for a remote-tracking ref. The loser fails, but
     // the ref is free again by the time a rerun needs it, so retry once.
     const runFetch = (fetchArgs: readonly string[]) => {
-      const run = executeGitWithStableDiagnostics(
-        "GitVcsDriver.fetchRemote",
-        input.cwd,
-        fetchArgs,
-        {
-          ...options,
-          allowNonZeroExit: true,
-        },
-      );
+      const run = Effect.gen(function* () {
+        // SSH debug noise must not crowd Git's retry and failure diagnostics out of the cap.
+        let diagnostics = "";
+        let awaitingApproval = false;
+        const result = yield* executeGitWithStableDiagnostics(
+          "GitVcsDriver.fetchRemote",
+          input.cwd,
+          fetchArgs,
+          {
+            ...options,
+            allowNonZeroExit: true,
+            ...(watchSshApproval && {
+              progress: {
+                onStderrLine: Effect.fn("GitVcsDriver.fetchRemote.observeSshApproval")(function* (
+                  line: string,
+                ) {
+                  if (!/^debug\d:/.test(line)) {
+                    diagnostics += (line + "\n").slice(
+                      0,
+                      DEFAULT_MAX_OUTPUT_BYTES - diagnostics.length,
+                    );
+                  }
+                  awaitingApproval = line.startsWith(SSH_SIGN_REQUEST_LINE_PREFIX)
+                    ? true
+                    : awaitingApproval && SSH_SIGNING_LINE.test(line);
+                }),
+              },
+            }),
+          },
+        ).pipe(
+          // Keep the command deadline; only explain it when ssh was still waiting to sign.
+          Effect.mapError((error) =>
+            awaitingApproval && error.detail === GIT_COMMAND_TIMEOUT_DETAIL
+              ? new GitCommandError({
+                  ...gitCommandContext({
+                    operation: "GitVcsDriver.fetchRemote",
+                    cwd: input.cwd,
+                    args: fetchArgs,
+                  }),
+                  detail: SSH_KEY_APPROVAL_TIMEOUT_DETAIL,
+                  cause: error,
+                })
+              : error,
+          ),
+        );
+        return watchSshApproval ? { ...result, stderr: diagnostics } : result;
+      });
       return run.pipe(
         Effect.filterOrElse(
           (result) => !(result.exitCode !== 0 && isRefLockFailure(result.stderr)),