terramend 0.2.0

package/src/utils/gitAuth.test.ts

@@ -0,0 +1,322 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { GitAuthServer } from "#app/utils/gitAuthServer";
+
+const execSyncMock = vi.fn();
+const readFileSyncMock = vi.fn();
+const realpathSyncMock = vi.fn();
+const unlinkSyncMock = vi.fn();
+const spawnMock = vi.fn();
+const shellMock = vi.fn();
+
+vi.mock("node:child_process", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("node:child_process")>()),
+  execSync: (...args: unknown[]) => execSyncMock(...args),
+}));
+
+vi.mock("node:fs", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("node:fs")>()),
+  readFileSync: (...args: unknown[]) => readFileSyncMock(...args),
+  realpathSync: (...args: unknown[]) => realpathSyncMock(...args),
+  unlinkSync: (...args: unknown[]) => unlinkSyncMock(...args),
+}));
+
+vi.mock("#app/utils/subprocess", () => ({
+  spawn: (params: unknown) => spawnMock(params),
+}));
+
+vi.mock("#app/utils/shell", () => ({
+  $: (...args: unknown[]) => shellMock(...args),
+}));
+
+vi.mock("#app/utils/secrets", () => ({
+  filterEnv: () => ({ PATH: "/usr/bin" }),
+}));
+
+type GitAuthModule = typeof import("#app/utils/gitAuth");
+
+// resolveGit/setGitAuthServer mutate module-level state — each test gets a
+// fresh module instance.
+async function loadGitAuth(): Promise<GitAuthModule> {
+  vi.resetModules();
+  return await import("#app/utils/gitAuth");
+}
+
+function makeAuthServer(): GitAuthServer {
+  return {
+    port: 45678,
+    register: vi.fn(() => "code-1234"),
+    revoke: vi.fn(),
+    writeAskpassScript: vi.fn(() => "/tmp/askpass-test.js"),
+    close: vi.fn(async () => {}),
+    [Symbol.asyncDispose]: async () => {},
+  };
+}
+
+/** loads a fresh module with resolveGit() done and a fake auth server installed. */
+async function loadReadyGitAuth(): Promise<{ gitAuth: GitAuthModule; authServer: GitAuthServer }> {
+  const gitAuth = await loadGitAuth();
+  execSyncMock.mockReturnValueOnce("/usr/bin/git\n");
+  realpathSyncMock.mockReturnValueOnce("/usr/libexec/git-core/git");
+  readFileSyncMock.mockReturnValue(Buffer.from("git-binary-bytes"));
+  gitAuth.resolveGit();
+  const authServer = makeAuthServer();
+  gitAuth.setGitAuthServer(authServer);
+  return { gitAuth, authServer };
+}
+
+function okSpawnResult(overrides: Partial<Record<string, unknown>> = {}) {
+  return { stdout: "ok\n", stderr: "", exitCode: 0, ...overrides };
+}
+
+beforeEach(() => {
+  spawnMock.mockResolvedValue(okSpawnResult());
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("resolveGit / verifyGitBinary", () => {
+  it("resolves the git path through which + realpath and fingerprints it", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    expect(execSyncMock).toHaveBeenCalledWith("which git", { encoding: "utf-8" });
+    expect(realpathSyncMock).toHaveBeenCalledWith("/usr/bin/git");
+
+    await gitAuth.$git("fetch", ["origin"], { token: "tok" });
+    const spawnParams = spawnMock.mock.calls[0]?.[0] as { cmd: string };
+    expect(spawnParams.cmd).toBe("/usr/libexec/git-core/git");
+  });
+
+  it("$git refuses to run before resolveGit()", async () => {
+    const gitAuth = await loadGitAuth();
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      /git binary not initialized/,
+    );
+  });
+
+  it("$git refuses to run when the binary hash changed since startup", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    readFileSyncMock.mockReturnValue(Buffer.from("tampered-binary-bytes"));
+    await expect(gitAuth.$git("push", ["origin", "main"], { token: "tok" })).rejects.toThrow(
+      /git binary tampered/,
+    );
+    expect(spawnMock).not.toHaveBeenCalled();
+  });
+
+  it("$git refuses to run before setGitAuthServer()", async () => {
+    const gitAuth = await loadGitAuth();
+    execSyncMock.mockReturnValueOnce("/usr/bin/git\n");
+    realpathSyncMock.mockReturnValueOnce("/usr/bin/git");
+    readFileSyncMock.mockReturnValue(Buffer.from("git-binary-bytes"));
+    gitAuth.resolveGit();
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      /git auth server not initialized/,
+    );
+  });
+});
+
+describe("$git invocation hardening", () => {
+  it("pins core.hooksPath=/dev/null by default (security control)", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    await gitAuth.$git("push", ["origin", "feature"], { token: "tok" });
+
+    const spawnParams = spawnMock.mock.calls[0]?.[0] as { args: string[] };
+    const args = spawnParams.args;
+    const hooksFlagIndex = args.indexOf("core.hooksPath=/dev/null");
+    expect(hooksFlagIndex).toBeGreaterThan(0);
+    expect(args[hooksFlagIndex - 1]).toBe("-c");
+    // the pin must come BEFORE the subcommand so it acts as a config override
+    expect(hooksFlagIndex).toBeLessThan(args.indexOf("push"));
+  });
+
+  it("keeps the hooksPath pin when disableHooks is explicitly true", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    await gitAuth.$git("push", ["origin", "feature"], { token: "tok", disableHooks: true });
+
+    const spawnParams = spawnMock.mock.calls[0]?.[0] as { args: string[] };
+    expect(spawnParams.args).toContain("core.hooksPath=/dev/null");
+  });
+
+  it("omits the hooksPath pin only when disableHooks is explicitly false", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    await gitAuth.$git("push", ["origin", "feature"], { token: "tok", disableHooks: false });
+
+    const spawnParams = spawnMock.mock.calls[0]?.[0] as { args: string[] };
+    expect(spawnParams.args).not.toContain("core.hooksPath=/dev/null");
+    // the other -c overrides stay in place regardless
+    expect(spawnParams.args).toContain("credential.helper=");
+  });
+
+  it("passes the full defense-in-depth -c overrides and askpass env", async () => {
+    const { gitAuth, authServer } = await loadReadyGitAuth();
+    const result = await gitAuth.$git("fetch", ["origin", "main"], {
+      token: "tok",
+      cwd: "/work/repo",
+    });
+
+    expect(result).toEqual({ stdout: "ok", stderr: "" });
+    expect(authServer.register).toHaveBeenCalledWith("tok");
+    expect(authServer.writeAskpassScript).toHaveBeenCalledWith("code-1234");
+
+    const spawnParams = spawnMock.mock.calls[0]?.[0] as {
+      args: string[];
+      cwd: string;
+      env: Record<string, string>;
+    };
+    expect(spawnParams.cwd).toBe("/work/repo");
+    expect(spawnParams.args).toEqual([
+      "-c",
+      "core.fsmonitor=false",
+      "-c",
+      "credential.helper=",
+      "-c",
+      "protocol.file.allow=never",
+      "-c",
+      "core.sshCommand=ssh",
+      "-c",
+      "core.hooksPath=/dev/null",
+      "fetch",
+      "origin",
+      "main",
+    ]);
+    expect(spawnParams.env.GIT_ASKPASS).toBe("/tmp/askpass-test.js");
+    expect(spawnParams.env.GIT_TERMINAL_PROMPT).toBe("0");
+    expect(spawnParams.env.GIT_CONFIG_COUNT).toBe("0");
+    expect(spawnParams.env.GIT_CONFIG_PARAMETERS).toBe("");
+    // token must never appear in the subprocess env
+    expect(Object.values(spawnParams.env)).not.toContain("tok");
+  });
+
+  it("revokes the code and deletes the askpass script even on success", async () => {
+    const { gitAuth, authServer } = await loadReadyGitAuth();
+    await gitAuth.$git("fetch", ["origin"], { token: "tok" });
+
+    expect(authServer.revoke).toHaveBeenCalledWith("code-1234");
+    expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/askpass-test.js");
+  });
+
+  it("revokes the code when spawn rejects, and swallows unlink failures", async () => {
+    const { gitAuth, authServer } = await loadReadyGitAuth();
+    spawnMock.mockRejectedValueOnce(new Error("spawn blew up"));
+    unlinkSyncMock.mockImplementationOnce(() => {
+      throw new Error("already gone");
+    });
+
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      "spawn blew up",
+    );
+    expect(authServer.revoke).toHaveBeenCalledWith("code-1234");
+  });
+
+  it("treats askpass-compromised stderr as a fatal auth failure", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock.mockResolvedValueOnce(
+      okSpawnResult({ stderr: "askpass-compromised\n", exitCode: 0 }),
+    );
+    await expect(gitAuth.$git("push", ["origin", "x"], { token: "tok" })).rejects.toThrow(
+      /askpass code was replayed after revoke/,
+    );
+  });
+
+  it("surfaces stderr and stdout detail on non-zero exit", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock.mockResolvedValueOnce(
+      okSpawnResult({ exitCode: 128, stderr: "fatal: not a repo", stdout: "smart-proto detail" }),
+    );
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      "git fetch failed (exit 128): fatal: not a repo\n--- stdout ---\nsmart-proto detail",
+    );
+  });
+
+  it("falls back to stdout-only detail, then to (no output)", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock.mockResolvedValueOnce(okSpawnResult({ exitCode: 1, stderr: "", stdout: "only out" }));
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      "git fetch failed (exit 1): only out",
+    );
+
+    spawnMock.mockResolvedValueOnce(okSpawnResult({ exitCode: 1, stderr: "", stdout: "" }));
+    await expect(gitAuth.$git("fetch", ["origin"], { token: "tok" })).rejects.toThrow(
+      "git fetch failed (exit 1): (no output)",
+    );
+  });
+});
+
+describe("$gitFetchWithDeepen", () => {
+  it("passes through on first-attempt success", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    const result = await gitAuth.$gitFetchWithDeepen(["origin", "main"], { token: "tok" });
+    expect(result.stdout).toBe("ok");
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+    expect(shellMock).not.toHaveBeenCalled();
+  });
+
+  it("rethrows non-shallow-unreachable errors unchanged", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock.mockResolvedValueOnce(okSpawnResult({ exitCode: 1, stderr: "permission denied" }));
+    await expect(gitAuth.$gitFetchWithDeepen(["origin", "main"], { token: "tok" })).rejects.toThrow(
+      /permission denied/,
+    );
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("stringifies non-Error rejections when checking for shallow-unreachable", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock.mockRejectedValueOnce("raw string failure");
+    await expect(gitAuth.$gitFetchWithDeepen(["origin"], { token: "tok" })).rejects.toBe(
+      "raw string failure",
+    );
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("rethrows shallow-unreachable errors when the repo is not shallow", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    const oid = "a".repeat(40);
+    spawnMock.mockResolvedValueOnce(
+      okSpawnResult({ exitCode: 1, stderr: `fatal: Could not read ${oid}` }),
+    );
+    shellMock.mockReturnValueOnce("false\n");
+
+    await expect(gitAuth.$gitFetchWithDeepen(["origin", "main"], { token: "tok" })).rejects.toThrow(
+      /Could not read/,
+    );
+    expect(shellMock).toHaveBeenCalledWith("git", ["rev-parse", "--is-shallow-repository"], {
+      log: false,
+    });
+    expect(spawnMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries once with --deepen and strips caller --depth on shallow repos", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    const oid = "b".repeat(64);
+    spawnMock
+      .mockResolvedValueOnce(okSpawnResult({ exitCode: 1, stderr: `Could not read ${oid}` }))
+      .mockResolvedValueOnce(okSpawnResult({ stdout: "deepened" }));
+    shellMock.mockReturnValueOnce("true\n");
+
+    const result = await gitAuth.$gitFetchWithDeepen(
+      ["--depth=50", "origin", "main"],
+      { token: "tok" },
+      "checkout fetch",
+    );
+
+    expect(result.stdout).toBe("deepened");
+    const retryParams = spawnMock.mock.calls[1]?.[0] as { args: string[] };
+    expect(retryParams.args).toContain("--deepen=1000");
+    expect(retryParams.args).not.toContain("--depth=50");
+  });
+
+  it("also recovers from the 'remote did not send all necessary objects' wording", async () => {
+    const { gitAuth } = await loadReadyGitAuth();
+    spawnMock
+      .mockResolvedValueOnce(
+        okSpawnResult({ exitCode: 1, stderr: "remote did not send all necessary objects" }),
+      )
+      .mockResolvedValueOnce(okSpawnResult({ stdout: "deepened" }));
+    shellMock.mockReturnValueOnce("true");
+
+    const result = await gitAuth.$gitFetchWithDeepen(["origin", "main"], { token: "tok" });
+    expect(result.stdout).toBe("deepened");
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/utils/gitAuth.ts

@@ -0,0 +1,263 @@
+/**
+ * git authentication via GIT_ASKPASS.
+ *
+ * a localhost HTTP server serves tokens via UUID codes whose lifetime is
+ * bounded by the parent $git() invocation: register() makes the code active,
+ * the script (and any sibling subprocess — e.g. git-lfs pre-push) can fetch
+ * the token any number of times, and $git()'s finally calls revoke() to
+ * close the window. each $git() call writes a unique askpass script with
+ * the server port+code baked into the file body — no secrets in subprocess
+ * env. a replay of a revoked code trips a 409 and revokes the underlying
+ * github installation token.
+ *
+ * see wiki/askpass.md for full security documentation.
+ */
+
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { log } from "#app/utils/cli";
+import type { GitAuthServer } from "#app/utils/gitAuthServer";
+import { filterEnv } from "#app/utils/secrets";
+import { $ } from "#app/utils/shell";
+import { spawn } from "#app/utils/subprocess";
+
+type SafeGitSubcommand = "fetch" | "push";
+
+type GitAuthOptions = {
+  token: string;
+  cwd?: string;
+  // when true (the default), this invocation runs with `core.hooksPath=/dev/null`
+  // so a repo-/agent-planted git hook (e.g. a `pre-push` written into
+  // `.git/hooks` or via an agent-set `core.hooksPath`) cannot fire while
+  // GIT_ASKPASS is live and read the installation token back out of the askpass
+  // script. Callers pass `false` only when the operator has granted full trust
+  // (shell: enabled), where honoring repo hooks (e.g. git-lfs pre-push upload)
+  // is intended and the agent could read the token through its shell anyway.
+  disableHooks?: boolean;
+};
+
+type GitResult = {
+  stdout: string;
+  stderr: string;
+};
+
+// --- git binary resolution and tamper detection ---
+
+type GitBinaryInfo = {
+  path: string;
+  sha256: string;
+};
+
+let gitBinary: GitBinaryInfo | undefined;
+
+function hashFile(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/**
+ * resolve and fingerprint the git binary. must be called once at startup
+ * (in main()) before any agent code runs, so the path and hash reflect
+ * the untampered binary.
+ *
+ * resolves symlinks via realpath so the hash is of the actual binary.
+ * a malicious agent with sudo could replace the binary later, which is
+ * caught by verifyGitBinary() before each authenticated call.
+ */
+export function resolveGit(): void {
+  const whichPath = execSync("which git", { encoding: "utf-8" }).trim();
+  const resolvedPath = realpathSync(whichPath);
+  const sha256 = hashFile(resolvedPath);
+  gitBinary = { path: resolvedPath, sha256 };
+  log.debug(`» git binary: ${resolvedPath} (sha256: ${sha256.slice(0, 12)}...)`);
+}
+
+function verifyGitBinary(): string {
+  if (!gitBinary) {
+    throw new Error("git binary not initialized — call resolveGit() at startup");
+  }
+  const currentHash = hashFile(gitBinary.path);
+  if (currentHash !== gitBinary.sha256) {
+    throw new Error(
+      `git binary tampered: expected sha256 ${gitBinary.sha256}, got ${currentHash}. ` +
+        `path: ${gitBinary.path}`,
+    );
+  }
+  return gitBinary.path;
+}
+
+// --- auth server ---
+
+let authServer: GitAuthServer | undefined;
+
+export function setGitAuthServer(server: GitAuthServer): void {
+  authServer = server;
+}
+
+/**
+ * execute authenticated git command via ASKPASS.
+ *
+ * subcommand is restricted to "fetch" | "push" — operations that talk to
+ * a remote and need credentials. working-tree operations (checkout, merge)
+ * use $() from shell.ts which has no token.
+ *
+ * per call: registers a code with the auth server (valid for the lifetime
+ * of this invocation), writes a unique askpass script with port+code baked
+ * in, spawns git with GIT_ASKPASS pointing to the script. on completion,
+ * revokes the code and deletes the script in finally. multiple sibling
+ * askpass calls within one invocation (e.g. git itself + git-lfs pre-push)
+ * all see a valid code; replay attempts after finally trip a 409 and the
+ * server revokes the underlying github token as a tamper signal.
+ *
+ * @example
+ * await $git("fetch", ["origin", "main"], { token });
+ * await $git("push", ["-u", "origin", "feature"], { token });
+ */
+export async function $git(
+  subcommand: SafeGitSubcommand,
+  args: string[],
+  options: GitAuthOptions,
+): Promise<GitResult> {
+  const gitPath = verifyGitBinary();
+
+  if (!authServer) {
+    throw new Error("git auth server not initialized — call setGitAuthServer() at startup");
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+
+  const code = authServer.register(options.token);
+  const scriptPath = authServer.writeAskpassScript(code);
+
+  // -c flags override local .git/config — defense-in-depth against
+  // agent-set config that could spawn subprocesses before ASKPASS runs.
+  // a command-line `-c` wins over any value the agent may have written into
+  // .git/config (e.g. via the MCP `git config` tool in restricted mode), which
+  // is why hook neutralization belongs here and not only at setup.
+  const fullArgs = [
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    "credential.helper=",
+    "-c",
+    "protocol.file.allow=never",
+    "-c",
+    "core.sshCommand=ssh",
+    // neutralize git hooks for this authenticated call unless the caller opted
+    // out (shell: enabled). a planted `pre-push`/`pre-receive` would otherwise
+    // run in the action process with GIT_ASKPASS set and could exfiltrate the
+    // token by invoking the askpass script itself.
+    ...(options.disableHooks === false ? [] : ["-c", "core.hooksPath=/dev/null"]),
+    subcommand,
+    ...args,
+  ];
+
+  log.debug(`git ${fullArgs.join(" ")}`);
+
+  try {
+    const result = await spawn({
+      cmd: gitPath,
+      args: fullArgs,
+      cwd,
+      env: {
+        ...filterEnv(),
+        GIT_ASKPASS: scriptPath,
+        GIT_TERMINAL_PROMPT: "0",
+        // blocks env-based git config injection from outer processes.
+        // GIT_CONFIG_COUNT=0 blocks the newer KEY_n/VALUE_n mechanism.
+        // GIT_CONFIG_PARAMETERS="" clears the legacy quoted-list mechanism.
+        // both are needed — they are independent systems.
+        GIT_CONFIG_COUNT: "0",
+        GIT_CONFIG_PARAMETERS: "",
+      },
+      activityTimeout: 0,
+    });
+
+    if (result.stderr.includes("askpass-compromised")) {
+      log.info("askpass code was replayed after revoke — token has been revoked");
+      throw new Error("git auth failed — askpass code was replayed after revoke, token revoked");
+    }
+
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim();
+      const stdout = result.stdout.trim();
+      // stderr is the primary channel for git diagnostics, but in rare cases
+      // (e.g. some HTTPS smart-protocol failures) the only useful detail is
+      // on stdout — without it the agent / operator sees an empty error.
+      // include exit code so we can distinguish e.g. signal-killed (1 with
+      // empty output) from a genuine git-level rejection.
+      const detail =
+        stderr && stdout
+          ? `${stderr}\n--- stdout ---\n${stdout}`
+          : stderr || stdout || "(no output)";
+      const message = `git ${subcommand} failed (exit ${result.exitCode}): ${detail}`;
+      log.info(message);
+      throw new Error(message);
+    }
+
+    return {
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    };
+  } finally {
+    authServer.revoke(code);
+    try {
+      unlinkSync(scriptPath);
+    } catch {
+      // script may already be gone (e.g. tmpdir cleanup raced us)
+    }
+  }
+}
+
+/**
+ * shallow-clone unreachable: when an existing local depth is too shallow for
+ * git to traverse to the requested ref's ancestry, the remote walk fails with
+ * one of these wordings (git emits the full OID via oid_to_hex, so the bound
+ * is 40 for SHA-1 or 64 for SHA-256). detecting both lets a single deepen
+ * retry recover before the error reaches the agent — see issue #564 for the
+ * original `git_fetch` precedent and #656 for the `checkout_pr` follow-up.
+ */
+export const SHALLOW_UNREACHABLE_PATTERNS: RegExp[] = [
+  /Could not read [a-f0-9]{40,64}/,
+  /remote did not send all necessary objects/,
+];
+
+/**
+ * large enough to clear the merge base on most real-world PRs without
+ * downloading the full history; matches the fallback used by
+ * `checkoutPrBranch` when the GitHub compare API is unavailable.
+ */
+export const DEEPEN_RETRY_DEPTH = 1000;
+
+/**
+ * authenticated `git fetch` that recovers from shallow-unreachable errors
+ * by retrying once with `--deepen=1000`. callers pass the same args they
+ * would to `$git("fetch", ...)`; on shallow-unreachable failures in a
+ * shallow repo, the second attempt prepends `--deepen=N` and strips any
+ * caller-supplied `--depth=` (the two flags are mutually exclusive, and
+ * the caller's depth is what got us into this mess).
+ *
+ * non-shallow-unreachable errors and non-shallow repos rethrow unchanged,
+ * so this is safe to wrap any fetch without changing fast-path behavior.
+ */
+export async function $gitFetchWithDeepen(
+  args: string[],
+  options: GitAuthOptions,
+  label?: string,
+): Promise<GitResult> {
+  try {
+    return await $git("fetch", args, options);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const isShallowUnreachable = SHALLOW_UNREACHABLE_PATTERNS.some((p) => p.test(msg));
+    if (!isShallowUnreachable) throw err;
+    const isShallow =
+      $("git", ["rev-parse", "--is-shallow-repository"], { log: false }).trim() === "true";
+    if (!isShallow) throw err;
+    log.info(
+      `» ${label ?? "git fetch"} hit shallow-unreachable error, retrying with --deepen=${DEEPEN_RETRY_DEPTH}`,
+    );
+    const retryArgs = args.filter((a) => !a.startsWith("--depth="));
+    return await $git("fetch", [`--deepen=${DEEPEN_RETRY_DEPTH}`, ...retryArgs], options);
+  }
+}