fix(server): add sanitized hints for common VCS command failures

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

@@ -623,6 +623,96 @@ it.effect("fails a ref snapshot when for-each-ref exits unsuccessfully", () =>
   ).pipe(Effect.provide(ServerConfigLayer.pipe(Layer.provideMerge(NodeServices.layer)))),
 );
 
+const makeDeniedHandle = () =>
+  ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(128)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.empty,
+    stderr: Stream.encodeText(Stream.make("fatal: cannot mkdir .git: Permission denied")),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+
+it.effect("surfaces a sanitized hint when a git command is denied filesystem access", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const delegate = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const cwd = yield* makeTmpDir();
+      const deniedSpawner = ChildProcessSpawner.make((command) =>
+        Effect.gen(function* () {
+          if (!ChildProcess.isStandardCommand(command)) {
+            return yield* Effect.die("expected a standard Git command");
+          }
+          if (command.args.includes("remote")) {
+            return makeDeniedHandle();
+          }
+          return yield* delegate.spawn(command);
+        }),
+      );
+      const driver = yield* makeGitVcsDriverCore().pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, deniedSpawner),
+      );
+
+      const error = yield* driver
+        .ensureRemote({ cwd, preferredName: "origin", url: "https://github.com/t3code/demo.git" })
+        .pipe(Effect.flip);
+
+      assert.deepInclude(error, {
+        _tag: "GitCommandError",
+        operation: "GitVcsDriver.ensureRemote.listRemoteUrls",
+        detail:
+          "Permission denied. Check that the directory is owned by your user account and writable.",
+        exitCode: 128,
+      });
+    }),
+  ).pipe(Effect.provide(ServerConfigLayer.pipe(Layer.provideMerge(NodeServices.layer)))),
+);
+
+it.effect("surfaces a sanitized hint when a raw execute command is denied filesystem access", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const delegate = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const cwd = yield* makeTmpDir();
+      const deniedSpawner = ChildProcessSpawner.make((command) =>
+        Effect.gen(function* () {
+          if (!ChildProcess.isStandardCommand(command)) {
+            return yield* Effect.die("expected a standard Git command");
+          }
+          if (command.args.includes("remote")) {
+            return makeDeniedHandle();
+          }
+          return yield* delegate.spawn(command);
+        }),
+      );
+      const driver = yield* makeGitVcsDriverCore().pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, deniedSpawner),
+      );
+
+      const error = yield* driver
+        .execute({
+          operation: "GitVcsDriver.test.rawDenied",
+          cwd,
+          args: ["remote", "get-url", "origin"],
+          timeoutMs: 10_000,
+        })
+        .pipe(Effect.flip);
+
+      assert.deepInclude(error, {
+        _tag: "GitCommandError",
+        operation: "GitVcsDriver.test.rawDenied",
+        detail:
+          "Permission denied. Check that the directory is owned by your user account and writable.",
+        exitCode: 128,
+      });
+    }),
+  ).pipe(Effect.provide(ServerConfigLayer.pipe(Layer.provideMerge(NodeServices.layer)))),
+);
+
 it.effect("marks the current branch when worktree metadata is unavailable", () =>
   Effect.scoped(
     Effect.gen(function* () {

apps/server/src/vcs/GitVcsDriverCore.ts

@@ -35,6 +35,7 @@ import { parseT3ProjectFile } from "@t3tools/shared/t3ProjectFile";
 import { resolveProjectFileBackedSetting } from "@t3tools/shared/projectSettings";
 import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../observability/Metrics.ts";
 import * as GitVcsDriver from "./GitVcsDriver.ts";
+import { resolveCommandFailureHint } from "./VcsProcess.ts";
 import {
   parseRemoteNames,
   parseRemoteNamesInGitOrder,
@@ -922,7 +923,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         if (!input.allowNonZeroExit && exitCode !== 0) {
           return yield* new GitCommandError({
             ...gitCommandContext(commandInput),
-            detail: "Git command exited with a non-zero status.",
+            detail:
+              resolveCommandFailureHint(stderr.text) ??
+              "Git command exited with a non-zero status.",
             exitCode,
             stdoutLength: stdout.text.length,
             stderrLength: stderr.text.length,
@@ -1007,7 +1010,10 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         (result) =>
           new GitCommandError({
             ...gitCommandContext({ operation, cwd, args }),
-            detail: options.fallbackErrorDetail ?? "Git command exited with a non-zero status.",
+            detail:
+              options.fallbackErrorDetail ??
+              resolveCommandFailureHint(result.stderr) ??
+              "Git command exited with a non-zero status.",
             ...(result.exitCode === null ? {} : { exitCode: result.exitCode }),
             stdoutLength: result.stdout.length,
             stderrLength: result.stderr.length,

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

@@ -292,6 +292,70 @@ describe("VcsProcess.run", () => {
     }).pipe(provideLive),
   );
 
+  it.effect("includes a sanitized hint for permission-denied failures", () =>
+    Effect.gen(function* () {
+      const rawStderr = "fatal: cannot mkdir .git: Permission denied";
+      const error = yield* run({
+        operation: "test.permission",
+        command: "node",
+        args: ["-e", "process.stderr.write(process.argv[1]); process.exit(128)", rawStderr],
+        cwd: process.cwd(),
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(VcsProcessExitError);
+      expect(error).toMatchObject({
+        detail:
+          "Permission denied. Check that the directory is owned by your user account and writable.",
+        failureKind: "command-failed",
+      });
+      expect(error.message).not.toContain("cannot mkdir");
+      expect(error.message).not.toContain(rawStderr);
+    }).pipe(provideLive),
+  );
+
+  it.effect("includes a sanitized hint for dubious-ownership failures", () =>
+    Effect.gen(function* () {
+      const rawStderr = "fatal: detected dubious ownership in repository at '/workspace'";
+      const error = yield* run({
+        operation: "test.dubious-ownership",
+        command: "node",
+        args: ["-e", "process.stderr.write(process.argv[1]); process.exit(128)", rawStderr],
+        cwd: process.cwd(),
+      }).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        detail:
+          "The directory is owned by a different user, which git refuses to trust. Fix the directory ownership or add it to git's safe.directory list.",
+      });
+      expect(error.message).not.toContain(rawStderr);
+    }).pipe(provideLive),
+  );
+
+  it.effect("includes a sanitized hint for SSH authentication failures", () =>
+    Effect.gen(function* () {
+      const sshHint =
+        "SSH authentication failed. Check that your SSH key is set up for this host, or use an HTTPS URL.";
+      for (const rawStderr of [
+        "git@github.com: Permission denied (publickey).",
+        "git@gitlab.com: Permission denied (publickey,password).",
+        "Permission denied (keyboard-interactive,publickey).",
+      ]) {
+        const error = yield* run({
+          operation: "test.ssh-auth",
+          command: "node",
+          args: ["-e", "process.stderr.write(process.argv[1]); process.exit(128)", rawStderr],
+          cwd: process.cwd(),
+        }).pipe(Effect.flip);
+
+        expect(error).toMatchObject({
+          detail: sshHint,
+          failureKind: "command-failed",
+        });
+        expect(error.message).not.toContain("publickey");
+      }
+    }).pipe(provideLive),
+  );
+
   it.effect("writes stdin before waiting for exit", () =>
     Effect.gen(function* () {
       const result = yield* run({

apps/server/src/vcs/VcsProcess.ts

@@ -113,6 +113,30 @@ const isTransientGitExit = (stderr: string) =>
   /unable to create [^\n]*\.lock['"]?: file exists/i.test(stderr) ||
   /(?:unable to stat|lstat\(|error: open\()[^\n]+: no such file or directory/i.test(stderr);
 
+/**
+ * Fixed, secret-free hints for common failure modes. stderr is matched but never echoed, since
+ * VCS CLIs may print credentials. Order matters: more specific patterns come first.
+ */
+const COMMAND_FAILURE_HINTS: ReadonlyArray<readonly [RegExp, string]> = [
+  [
+    /permission denied \([^)]*(?:publickey|password|keyboard-interactive)[^)]*\)/i,
+    "SSH authentication failed. Check that your SSH key is set up for this host, or use an HTTPS URL.",
+  ],
+  [
+    /detected dubious ownership in repository/i,
+    "The directory is owned by a different user, which git refuses to trust. Fix the directory ownership or add it to git's safe.directory list.",
+  ],
+  [
+    /permission denied/i,
+    "Permission denied. Check that the directory is owned by your user account and writable.",
+  ],
+  [/not a git repository/i, "The directory is not a git repository."],
+];
+
+/** Resolves a sanitized failure hint from stderr without retaining any of its content. */
+export const resolveCommandFailureHint = (stderr: string): string | undefined =>
+  COMMAND_FAILURE_HINTS.find(([pattern]) => pattern.test(stderr))?.[1];
+
 export const make = Effect.gen(function* () {
   const processRunner = yield* ProcessRunner.ProcessRunner;
   const vcsProcesses = yield* Semaphore.make(VCS_PROCESS_CONCURRENCY);
@@ -177,12 +201,15 @@ export const make = Effect.gen(function* () {
 
     if (!input.allowNonZeroExit && result.code !== 0) {
       const failureKind = classifyNonZeroExit(input.command, result.stderr);
+      const failureDetail =
+        failureKind === "command-failed" ? resolveCommandFailureHint(result.stderr) : undefined;
       return yield* VcsProcessExitError.fromProcessExit(
         baseError,
         {
           exitCode: result.code,
           stderr: result.stderr,
           stderrTruncated: result.stderrTruncated,
+          ...(failureDetail !== undefined ? { failureDetail } : {}),
         },
         failureKind,
         input.command === "git" &&

packages/contracts/src/vcs.ts

@@ -85,6 +85,8 @@ export interface VcsProcessExitFailure {
   readonly exitCode: number;
   readonly stderr: string;
   readonly stderrTruncated: boolean;
+  /** Server-derived, secret-free detail describing the failure, when known. Never raw stderr. */
+  readonly failureDetail?: string;
 }
 
 export class VcsProcessSpawnError extends Schema.TaggedError<VcsProcessSpawnError>()(
@@ -146,7 +148,7 @@ export class VcsProcessExitError extends Schema.TaggedError<VcsProcessExitError>
               : context.command === "gh" || context.command === "az"
                 ? "Pull request not found."
                 : "VCS resource not found."
-            : "Process exited with a non-zero status.";
+            : (error.failureDetail ?? "Process exited with a non-zero status.");
 
     return new VcsProcessExitError({
       ...context,