Commit 4238a0e769c9f149d4083968823298ace1e2bd0b | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-06-20 11:53:53-07:00
committer	GitHub <noreply@github.com> 2026-06-20 11:53:53-07:00
log	4238a0e769c9f149d4083968823298ace1e2bd0b
tree	6f8c5e292a314581aa03be18f177595a7e464f0e
parent	ff0f702c7cb5006acf72b63edf5c0df7686f60c4
signature	Signed by PGP key B5690EEEBB952194

[codex] Enrich Git VCS driver errors (#3253)

Co-authored-by: codex <codex@users.noreply.github.com>

5 files changed, 407 insertions(+), 222 deletions(-)

apps
- server
  - src
    git
    GitManager.test.ts
    vcs
    GitVcsDriverCore.test.ts
    GitVcsDriverCore.ts
    VcsDriverRegistry.ts
packages
- contracts
  - src
    git.ts

apps/server/src/git/GitManager.test.ts+6-1

 @@ -3377,13 +3377,18 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         Effect.map((error) => error.message),
       );
-      expect(errorMessage).toContain("hook: fail");
+      expect(errorMessage).toContain("Git command failed in GitVcsDriver.commit.commit");
+      expect(errorMessage).not.toContain("hook: fail");
       expect(events).toEqual(
         expect.arrayContaining([
           expect.objectContaining({
             kind: "hook_started",
             hookName: "pre-commit",
           }),
+          expect.objectContaining({
+            kind: "hook_output",
+            text: "hook: fail",
+          }),
           expect.objectContaining({
             kind: "action_failed",
             phase: "commit",

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

...	@@ -78,6 +78,114 @@ const initRepoWithCommit = (	...	@@ -78,6 +78,114 @@ const initRepoWithCommit = (
78	});	78	});
79		79
80	it.layer(TestLayer)("GitVcsDriver core integration", (it) => {	80	it.layer(TestLayer)("GitVcsDriver core integration", (it) => {
		81	describe("structured errors", () => {
		82	it.effect("preserves structured spawn context and the platform cause", () =>
		83	Effect.gen(function* () {
		84	const parent = yield* makeTmpDir();
		85	const pathService = yield* Path.Path;
		86	const cwd = pathService.join(parent, "missing");
		87	const driver = yield* GitVcsDriver.GitVcsDriver;
		88
		89	const error = yield* driver
		90	.execute({
		91	operation: "GitVcsDriver.test.missingCwd",
		92	cwd,
		93	args: ["status", "--short"],
		94	})
		95	.pipe(Effect.flip);
		96
		97	assert.deepInclude(error, {
		98	_tag: "GitCommandError",
		99	operation: "GitVcsDriver.test.missingCwd",
		100	command: "git",
		101	argumentCount: 2,
		102	cwd,
		103	detail: "Failed to spawn Git process.",
		104	});
		105	if (!(error.cause instanceof PlatformError.PlatformError)) {
		106	return assert.fail("expected the original platform error cause");
		107	}
		108	assert.equal(error.cause.reason._tag, "NotFound");
		109	assert.notInclude(error.detail, error.cause.message);
		110	}),
		111	);
		112
		113	it.effect("does not retain git arguments or stderr in command failures", () =>
		114	Effect.gen(function* () {
		115	const cwd = yield* makeTmpDir();
		116	const driver = yield* GitVcsDriver.GitVcsDriver;
		117	yield* driver.initRepo({ cwd });
		118
		119	const secret = "secret-token-value";
		120	const error = yield* driver
		121	.execute({
		122	operation: "GitVcsDriver.test.redactedFailure",
		123	cwd,
		124	args: ["status", `--unknown-option=${secret}`],
		125	})
		126	.pipe(Effect.flip);
		127
		128	assert.deepInclude(error, {
		129	_tag: "GitCommandError",
		130	operation: "GitVcsDriver.test.redactedFailure",
		131	command: "git",
		132	argumentCount: 2,
		133	cwd,
		134	});
		135	assert.isNumber(error.exitCode);
		136	assert.isAbove(error.stderrLength ?? 0, 0);
		137	assert.notInclude(error.detail, secret);
		138	assert.notInclude(error.message, secret);
		139	assert.notProperty(error, "args");
		140	assert.notProperty(error, "stderr");
		141	}),
		142	);
		143
		144	it.effect("recovers a structurally identified missing cwd as a non-repository", () =>
		145	Effect.gen(function* () {
		146	const parent = yield* makeTmpDir();
		147	const pathService = yield* Path.Path;
		148	const cwd = pathService.join(parent, "missing");
		149	const driver = yield* GitVcsDriver.GitVcsDriver;
		150
		151	const [localStatus, remoteStatus, refs] = yield* Effect.all([
		152	driver.statusDetails(cwd),
		153	driver.statusDetailsRemote(cwd, { refreshUpstream: false }),
		154	driver.listRefs({ cwd }),
		155	]);
		156
		157	assert.equal(localStatus.isRepo, false);
		158	assert.equal(remoteStatus.isRepo, false);
		159	assert.equal(refs.isRepo, false);
		160	assert.deepStrictEqual(refs.refs, []);
		161	}),
		162	);
		163
		164	it.effect("does not wrap a remove-worktree command failure in a synthetic error", () =>
		165	Effect.gen(function* () {
		166	const cwd = yield* makeTmpDir();
		167	const pathService = yield* Path.Path;
		168	const missingWorktree = pathService.join(cwd, "missing-worktree");
		169	const driver = yield* GitVcsDriver.GitVcsDriver;
		170	yield* driver.initRepo({ cwd });
		171
		172	const error = yield* driver
		173	.removeWorktree({ cwd, path: missingWorktree })
		174	.pipe(Effect.flip);
		175
		176	assert.deepInclude(error, {
		177	_tag: "GitCommandError",
		178	operation: "GitVcsDriver.removeWorktree",
		179	command: "git",
		180	argumentCount: 3,
		181	cwd,
		182	});
		183	assert.notProperty(error, "cause");
		184	assert.notInclude(error.detail, "Git command failed in");
		185	}),
		186	);
		187	});
		188
81	describe("review diff previews", () => {	189	describe("review diff previews", () => {
82	it.effect("drops an unterminated path from truncated NUL-separated git output", () =>	190	it.effect("drops an unterminated path from truncated NUL-separated git output", () =>
83	Effect.sync(() => {	191	Effect.sync(() => {

apps/server/src/vcs/GitVcsDriverCore.ts+274-205

 @@ -36,7 +36,6 @@ import {
   parseRemoteRefWithRemoteNames,
 } from "../git/remoteRefs.ts";
 import { ServerConfig } from "../config.ts";
-const isGitCommandError = Schema.is(GitCommandError);
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 @@ -100,7 +99,7 @@ interface ExecuteGitOptions {
   stdin?: string | undefined;
   timeoutMs?: number | undefined;
   allowNonZeroExit?: boolean | undefined;
-  fallbackErrorMessage?: string | undefined;
+  fallbackErrorDetail?: string | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   maxOutputBytes?: number | undefined;
   appendTruncationMarker?: boolean | undefined;
 @@ -326,8 +325,15 @@ function deriveLocalBranchNameFromRemoteRef(branchName: string): string | null {
   return localBranch.length > 0 ? localBranch : null;
 }
-function commandLabel(args: readonly string[]): string {
+function gitCommandContext(
-  return `git ${args.join(" ")}`;
+  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
+) {
+  return {
+    operation: input.operation,
+    command: "git",
+    cwd: input.cwd,
+    argumentCount: input.args.length,
+  } as const;
 }
 function parseDefaultBranchFromRemoteHeadRef(value: string, remoteName: string): string | null {
 @@ -340,50 +346,28 @@ function parseDefaultBranchFromRemoteHeadRef(value: string, remoteName: string):
   return refName.length > 0 ? refName : null;
 }
-function createGitCommandError(
+function isMissingGitCwdError(error: GitCommandError): boolean {
-  operation: string,
+  if (!(error.cause instanceof PlatformError.PlatformError)) {
-  cwd: string,
+    return false;
-  args: readonly string[],
+  }
-  detail: string,
-  cause?: unknown,
-): GitCommandError {
-  return new GitCommandError({
-    operation,
-    command: commandLabel(args),
-    cwd,
-    detail,
-    ...(cause !== undefined ? { cause } : {}),
-  });
-}
-function quoteGitCommand(args: ReadonlyArray<string>): string {
+  const reason = error.cause.reason;
-  return `git ${args.join(" ")}`;
+  if (reason._tag === "NotFound") {
-}
+    return reason.pathOrDescriptor === error.cwd;
+  }
-function isMissingGitCwdError(error: GitCommandError): boolean {
-  const normalized = `${error.detail}\n${error.message}`.toLowerCase();
   return (
-    normalized.includes("no such file or directory") ||
+    reason._tag === "BadResource" &&
-    normalized.includes("notfound: filesystem.access") ||
+    reason.pathOrDescriptor === error.cwd &&
-    normalized.includes("enoent") ||
+    typeof reason.cause === "object" &&
-    normalized.includes("not a directory")
+    reason.cause !== null &&
+    "code" in reason.cause &&
+    reason.cause.code === "ENOTDIR"
   );
 }
-function toGitCommandError(
+function isNonRepositoryGitStderr(stderr: string): boolean {
-  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
+  return stderr.toLowerCase().includes("not a git repository");
-  detail: string,
-) {
-  return (cause: unknown) =>
-    isGitCommandError(cause)
-      ? cause
-      : new GitCommandError({
-          operation: input.operation,
-          command: quoteGitCommand(input.args),
-          cwd: input.cwd,
-          detail: `${cause instanceof Error && cause.message.length > 0 ? cause.message : "Unknown error"} - ${detail}`,
-          ...(cause !== undefined ? { cause } : {}),
-        });
 }
 interface Trace2Monitor {
 @@ -402,7 +386,11 @@ const addCurrentSpanEvent = (name: string, attributes: Record<string, unknown>)
     yield* Effect.sync(() => {
       span.event(name, timestamp, compactTraceAttributes(attributes));
     });
-  }).pipe(Effect.catch(() => Effect.void));
+  }).pipe(
+    Effect.catchTags({
+      NoSuchElementError: () => Effect.void,
+    }),
+  );
 function trace2ChildKey(record: Record<string, unknown>): string | null {
   const childId = record.child_id;
 @@ -451,7 +439,7 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
     const traceRecord = decodeJsonResult(Trace2Record)(trimmedLine);
     if (Result.isFailure(traceRecord)) {
       yield* Effect.logDebug(
-        `GitVcsDriver.trace2: failed to parse trace line for ${quoteGitCommand(input.args)} in ${input.cwd}`,
+        `GitVcsDriver.trace2: failed to parse trace line for ${input.operation} in ${input.cwd} (${input.args.length} arguments)`,
         traceRecord.failure,
       );
       return;
 @@ -574,9 +562,9 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
   };
 });
-const collectOutput = Effect.fnUntraced(function* <E>(
+const collectOutput = Effect.fnUntraced(function* (
   input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
-  stream: Stream.Stream<Uint8Array, E>,
+  stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
   maxOutputBytes: number,
   appendTruncationMarker: boolean,
   onLine: ((line: string) => Effect.Effect<void, never>) | undefined,
 @@ -614,10 +602,9 @@ const collectOutput = Effect.fnUntraced(function* <E>(
     const nextBytes = bytes + chunk.byteLength;
     if (!appendTruncationMarker && nextBytes > maxOutputBytes) {
       return yield* new GitCommandError({
-        operation: input.operation,
+        ...gitCommandContext(input),
-        command: quoteGitCommand(input.args),
+        detail: `Git output exceeded ${maxOutputBytes} bytes and was truncated.`,
-        cwd: input.cwd,
+        outputLength: nextBytes,
-        detail: `${quoteGitCommand(input.args)} output exceeded ${maxOutputBytes} bytes and was truncated.`,
       });
     }
 @@ -635,7 +622,14 @@ const collectOutput = Effect.fnUntraced(function* <E>(
   });
   yield* Stream.runForEach(stream, processChunk).pipe(
-    Effect.mapError(toGitCommandError(input, "output stream failed.")),
+    Effect.catchTags({
+      PlatformError: (cause) =>
+        new GitCommandError({
+          ...gitCommandContext(input),
+          detail: "Failed to read Git process output.",
+          cause,
+        }),
+    }),
   );
   const remainder = truncated ? "" : decoder.decode();
 @@ -669,7 +663,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         const trace2Monitor = yield* createTrace2Monitor(commandInput, input.progress).pipe(
           Effect.provideService(Path.Path, path),
           Effect.provideService(FileSystem.FileSystem, fileSystem),
-          Effect.mapError(toGitCommandError(commandInput, "failed to create trace2 monitor.")),
+          Effect.mapError(
+            (cause) =>
+              new GitCommandError({
+                ...gitCommandContext(commandInput),
+                detail: "Failed to create Git trace monitor.",
+                cause,
+              }),
+          ),
         );
         const child = yield* commandSpawner
           .spawn(
 @@ -682,7 +683,16 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
               },
             }),
           )
-          .pipe(Effect.mapError(toGitCommandError(commandInput, "failed to spawn.")));
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new GitCommandError({
+                  ...gitCommandContext(commandInput),
+                  detail: "Failed to spawn Git process.",
+                  cause,
+                }),
+            ),
+          );
         const [stdout, stderr, exitCode] = yield* Effect.all(
           [
 @@ -701,12 +711,26 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
               input.progress?.onStderrLine,
             ),
             child.exitCode.pipe(
-              Effect.mapError(toGitCommandError(commandInput, "failed to report exit code.")),
+              Effect.mapError(
+                (cause) =>
+                  new GitCommandError({
+                    ...gitCommandContext(commandInput),
+                    detail: "Failed to read Git process exit code.",
+                    cause,
+                  }),
+              ),
             ),
             input.stdin === undefined
               ? Effect.void
               : Stream.run(Stream.encodeText(Stream.make(input.stdin)), child.stdin).pipe(
-                  Effect.mapError(toGitCommandError(commandInput, "failed to write stdin.")),
+                  Effect.mapError(
+                    (cause) =>
+                      new GitCommandError({
+                        ...gitCommandContext(commandInput),
+                        detail: "Failed to write Git process input.",
+                        cause,
+                      }),
+                  ),
                 ),
           ],
           { concurrency: "unbounded" },
 @@ -714,15 +738,12 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         yield* trace2Monitor.flush;
         if (!input.allowNonZeroExit && exitCode !== 0) {
-          const trimmedStderr = stderr.text.trim();
           return yield* new GitCommandError({
-            operation: commandInput.operation,
+            ...gitCommandContext(commandInput),
-            command: quoteGitCommand(commandInput.args),
+            detail: "Git command exited with a non-zero status.",
-            cwd: commandInput.cwd,
+            exitCode,
-            detail:
+            stdoutLength: stdout.text.length,
-              trimmedStderr.length > 0
+            stderrLength: stderr.text.length,
-                ? `${quoteGitCommand(commandInput.args)} failed: ${trimmedStderr}`
-                : `${quoteGitCommand(commandInput.args)} failed with code ${exitCode}.`,
           });
         }
 @@ -743,10 +764,8 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
             onNone: () =>
               Effect.fail(
                 new GitCommandError({
-                  operation: commandInput.operation,
+                  ...gitCommandContext(commandInput),
-                  command: quoteGitCommand(commandInput.args),
+                  detail: "Git command timed out.",
-                  cwd: commandInput.cwd,
-                  detail: `${quoteGitCommand(commandInput.args)} timed out.`,
                 }),
               ),
             onSome: Effect.succeed,
 @@ -799,22 +818,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         if (options.allowNonZeroExit || result.exitCode === 0) {
           return Effect.succeed(result);
         }
-        const stderr = result.stderr.trim();
-        if (stderr.length > 0) {
-          return Effect.fail(createGitCommandError(operation, cwd, args, stderr));
-        }
-        if (options.fallbackErrorMessage) {
-          return Effect.fail(
-            createGitCommandError(operation, cwd, args, options.fallbackErrorMessage),
-          );
-        }
         return Effect.fail(
-          createGitCommandError(
+          new GitCommandError({
-            operation,
+            ...gitCommandContext({ operation, cwd, args }),
-            cwd,
+            detail: options.fallbackErrorDetail ?? "Git command exited with a non-zero status.",
-            args,
+            ...(result.exitCode === null ? {} : { exitCode: result.exitCode }),
-            `${commandLabel(args)} failed: code=${result.exitCode ?? "null"}`,
+            stdoutLength: result.stdout.length,
-          ),
+            stderrLength: result.stderr.length,
+          }),
         );
       }),
     );
 @@ -877,12 +888,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       }
     }
-    return yield* createGitCommandError(
+    return yield* new GitCommandError({
-      "GitVcsDriver.renameBranch",
+      ...gitCommandContext({
-      cwd,
+        operation: "GitVcsDriver.renameBranch",
-      ["branch", "-m", "--", desiredBranch],
+        cwd,
-      `Could not find an available branch name for '${desiredBranch}'.`,
+        args: ["branch", "-m", "--", desiredBranch],
-    );
+      }),
+      detail: `Could not find an available branch name for '${desiredBranch}'.`,
+    });
   });
   const resolveCurrentUpstream = Effect.fn("resolveCurrentUpstream")(function* (cwd: string) {
 @@ -1024,12 +1037,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     if (firstRemote) {
       return firstRemote;
     }
-    return yield* createGitCommandError(
+    return yield* new GitCommandError({
-      "GitVcsDriver.resolvePrimaryRemoteName",
+      ...gitCommandContext({
-      cwd,
+        operation: "GitVcsDriver.resolvePrimaryRemoteName",
-      ["remote"],
+        cwd,
-      "No git remote is configured for this repository.",
+        args: ["remote"],
-    );
+      }),
+      detail: "No git remote is configured for this repository.",
+    });
   });
   const resolvePushRemoteName = Effect.fn("resolvePushRemoteName")(function* (
 @@ -1174,19 +1189,31 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       cwd,
       ["rev-parse", "--abbrev-ref", "HEAD"],
       { allowNonZeroExit: true },
-    ).pipe(Effect.catchIf(isMissingGitCwdError, () => Effect.succeed(null)));
+    ).pipe(
+      Effect.catchTags({
+        GitCommandError: (error) =>
+          isMissingGitCwdError(error) ? Effect.succeed(null) : Effect.fail(error),
+      }),
+    );
     if (branchResult === null) {
       return NON_REPOSITORY_REMOTE_STATUS_DETAILS;
     }
     if (branchResult.exitCode !== 0) {
-      const stderr = branchResult.stderr.trim();
+      if (isNonRepositoryGitStderr(branchResult.stderr)) {
-      return yield* createGitCommandError(
+        return NON_REPOSITORY_REMOTE_STATUS_DETAILS;
-        "GitVcsDriver.statusDetailsRemote.branch",
+      }
-        cwd,
+      return yield* new GitCommandError({
-        ["rev-parse", "--abbrev-ref", "HEAD"],
+        ...gitCommandContext({
-        stderr || "git branch lookup failed",
+          operation: "GitVcsDriver.statusDetailsRemote.branch",
-      );
+          cwd,
+          args: ["rev-parse", "--abbrev-ref", "HEAD"],
+        }),
+        detail: "Git branch lookup failed.",
+        exitCode: branchResult.exitCode,
+        stdoutLength: branchResult.stdout.length,
+        stderrLength: branchResult.stderr.length,
+      });
     }
     const branchValue = branchResult.stdout.trim();
 @@ -1284,20 +1311,32 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       {
         allowNonZeroExit: true,
       },
-    ).pipe(Effect.catchIf(isMissingGitCwdError, () => Effect.succeed(null)));
+    ).pipe(
+      Effect.catchTags({
+        GitCommandError: (error) =>
+          isMissingGitCwdError(error) ? Effect.succeed(null) : Effect.fail(error),
+      }),
+    );
     if (statusResult === null) {
       return NON_REPOSITORY_STATUS_DETAILS;
     }
     if (statusResult.exitCode !== 0) {
-      const stderr = statusResult.stderr.trim();
+      if (isNonRepositoryGitStderr(statusResult.stderr)) {
-      return yield* createGitCommandError(
+        return NON_REPOSITORY_STATUS_DETAILS;
-        "GitVcsDriver.statusDetails.status",
+      }
-        cwd,
+      return yield* new GitCommandError({
-        ["status", "--porcelain=2", "--branch"],
+        ...gitCommandContext({
-        stderr || "git status failed",
+          operation: "GitVcsDriver.statusDetails.status",
-      );
+          cwd,
+          args: ["status", "--porcelain=2", "--branch"],
+        }),
+        detail: "Git status failed.",
+        exitCode: statusResult.exitCode,
+        stdoutLength: statusResult.stdout.length,
+        stderrLength: statusResult.stderr.length,
+      });
     }
     const [unstagedNumstatStdout, stagedNumstatStdout, defaultRefResult, hasPrimaryRemote] =
 @@ -1436,7 +1475,10 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     "statusDetails",
   )(function* (cwd) {
     yield* refreshStatusUpstreamIfStale(cwd).pipe(
-      Effect.catchIf(isMissingGitCwdError, () => Effect.void),
+      Effect.catchTags({
+        GitCommandError: (error) =>
+          isMissingGitCwdError(error) ? Effect.void : Effect.fail(error),
+      }),
       Effect.ignoreCause({ log: true }),
     );
     return yield* readStatusDetailsLocal(cwd);
 @@ -1446,7 +1488,10 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     Effect.fn("statusDetailsRemote")(function* (cwd, options) {
       if (options?.refreshUpstream !== false) {
         yield* refreshStatusUpstreamIfStale(cwd).pipe(
-          Effect.catchIf(isMissingGitCwdError, () => Effect.void),
+          Effect.catchTags({
+            GitCommandError: (error) =>
+              isMissingGitCwdError(error) ? Effect.void : Effect.fail(error),
+          }),
           Effect.ignoreCause({ log: true }),
         );
       }
 @@ -1474,7 +1519,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     Effect.fn("prepareCommitContext")(function* (cwd, filePaths) {
       if (filePaths && filePaths.length > 0) {
         yield* runGit("GitVcsDriver.prepareCommitContext.reset", cwd, ["reset"]).pipe(
-          Effect.catch(() => Effect.void),
+          Effect.catchTags({
+            GitCommandError: () => Effect.void,
+          }),
         );
         yield* runGit("GitVcsDriver.prepareCommitContext.addSelected", cwd, [
           "add",
 @@ -1550,12 +1597,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     const details = yield* statusDetails(cwd);
     const branch = details.branch ?? fallbackBranch;
     if (!branch) {
-      return yield* createGitCommandError(
+      return yield* new GitCommandError({
-        "GitVcsDriver.pushCurrentBranch",
+        ...gitCommandContext({
-        cwd,
+          operation: "GitVcsDriver.pushCurrentBranch",
-        ["push"],
+          cwd,
-        "Cannot push from detached HEAD.",
+          args: ["push"],
-      );
+        }),
+        detail: "Cannot push from detached HEAD.",
+      });
     }
     const requestedRemoteName = options?.remoteName?.trim() || null;
 @@ -1614,12 +1663,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     if (!details.hasUpstream) {
       const publishRemoteName = yield* resolvePushRemoteName(cwd, branch);
       if (!publishRemoteName) {
-        return yield* createGitCommandError(
+        return yield* new GitCommandError({
-          "GitVcsDriver.pushCurrentBranch",
+          ...gitCommandContext({
-          cwd,
+            operation: "GitVcsDriver.pushCurrentBranch",
-          ["push"],
+            cwd,
-          "Cannot push because no git remote is configured for this repository.",
+            args: ["push"],
-        );
+          }),
+          detail: "Cannot push because no git remote is configured for this repository.",
+        });
       }
       const publishBranch = yield* resolvePublishBranchName(cwd, branch);
       yield* runGit("GitVcsDriver.pushCurrentBranch.pushWithUpstream", cwd, [
 @@ -1668,20 +1719,24 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     const details = yield* statusDetails(cwd);
     const refName = details.branch;
     if (!refName) {
-      return yield* createGitCommandError(
+      return yield* new GitCommandError({
-        "GitVcsDriver.pullCurrentBranch",
+        ...gitCommandContext({
-        cwd,
+          operation: "GitVcsDriver.pullCurrentBranch",
-        ["pull", "--ff-only"],
+          cwd,
-        "Cannot pull from detached HEAD.",
+          args: ["pull", "--ff-only"],
-      );
+        }),
+        detail: "Cannot pull from detached HEAD.",
+      });
     }
     if (!details.hasUpstream) {
-      return yield* createGitCommandError(
+      return yield* new GitCommandError({
-        "GitVcsDriver.pullCurrentBranch",
+        ...gitCommandContext({
-        cwd,
+          operation: "GitVcsDriver.pullCurrentBranch",
-        ["pull", "--ff-only"],
+          cwd,
-        "Current branch has no upstream configured. Push with upstream first.",
+          args: ["pull", "--ff-only"],
-      );
+        }),
+        detail: "Current branch has no upstream configured. Push with upstream first.",
+      });
     }
     const beforeSha = yield* runGitStdout(
       "GitVcsDriver.pullCurrentBranch.beforeSha",
 @@ -1691,7 +1746,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     ).pipe(Effect.map((stdout) => stdout.trim()));
     yield* executeGit("GitVcsDriver.pullCurrentBranch.pull", cwd, ["pull", "--ff-only"], {
       timeoutMs: 30_000,
-      fallbackErrorMessage: "git pull failed",
+      fallbackErrorDetail: "git pull failed",
     });
     const afterSha = yield* runGitStdout(
       "GitVcsDriver.pullCurrentBranch.afterSha",
 @@ -1874,14 +1929,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       crypto.digest("SHA-256", new TextEncoder().encode(diff)).pipe(
         Effect.map(Encoding.encodeHex),
         Effect.mapError(
-          toGitCommandError(
+          (cause) =>
-            {
+            new GitCommandError({
               operation: "GitVcsDriver.getReviewDiffPreview.hash",
+              command: "crypto.digest SHA-256",
               cwd: input.cwd,
-              args: [],
+              detail: "Failed to hash review diff.",
-            },
+              cause,
-            "failed to hash review diff.",
+            }),
-          ),
         ),
       );
     const [dirtyDiffHash, baseDiffHash] = yield* Effect.all([
 @@ -1939,20 +1994,23 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
           allowNonZeroExit: true,
         },
       ).pipe(
-        Effect.catchIf(isMissingGitCwdError, () =>
+        Effect.catchTags({
-          Effect.succeed({
+          GitCommandError: (error) =>
-            exitCode: ChildProcessSpawner.ExitCode(128),
+            isMissingGitCwdError(error)
-            stdout: "",
+              ? Effect.succeed({
-            stderr: "fatal: not a git repository",
+                  exitCode: ChildProcessSpawner.ExitCode(128),
-            stdoutTruncated: false,
+                  stdout: "",
-            stderrTruncated: false,
+                  stderr: "fatal: not a git repository",
-          }),
+                  stdoutTruncated: false,
-        ),
+                  stderrTruncated: false,
+                })
+              : Effect.fail(error),
+        }),
       );
       if (localBranchResult.exitCode !== 0) {
         const stderr = localBranchResult.stderr.trim();
-        if (stderr.toLowerCase().includes("not a git repository")) {
+        if (isNonRepositoryGitStderr(stderr)) {
           return {
             refs: [],
             isRepo: false,
 @@ -1961,12 +2019,17 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
             totalCount: 0,
           };
         }
-        return yield* createGitCommandError(
+        return yield* new GitCommandError({
-          "GitVcsDriver.listRefs",
+          ...gitCommandContext({
-          input.cwd,
+            operation: "GitVcsDriver.listRefs",
-          ["branch", "--no-color", "--no-column"],
+            cwd: input.cwd,
-          stderr || "git branch failed",
+            args: ["branch", "--no-color", "--no-column"],
-        );
+          }),
+          detail: "Git branch listing failed.",
+          exitCode: localBranchResult.exitCode,
+          stdoutLength: localBranchResult.stdout.length,
+          stderrLength: localBranchResult.stderr.length,
+        });
       }
       const remoteBranchResultEffect = executeGit(
 @@ -1978,19 +2041,27 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
           allowNonZeroExit: true,
         },
       ).pipe(
-        Effect.catch((error) =>
+        Effect.catchTags({
-          Effect.logWarning(
+          GitCommandError: (error) =>
-            `GitVcsDriver.listRefs: remote refName lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote refName list.`,
+            Effect.logWarning(
-          ).pipe(
+              "Git remote ref lookup failed; falling back to an empty remote ref list.",
-            Effect.as({
+              {
-              exitCode: ChildProcessSpawner.ExitCode(1),
+                operation: error.operation,
-              stdout: "",
+                command: error.command,
-              stderr: "",
+                cwd: error.cwd,
-              stdoutTruncated: false,
+                detail: error.detail,
-              stderrTruncated: false,
+                cause: error,
-            } satisfies GitVcsDriver.ExecuteGitResult),
+              },
-          ),
+            ).pipe(
-        ),
+              Effect.as({
+                exitCode: ChildProcessSpawner.ExitCode(1),
+                stdout: "",
+                stderr: "",
+                stdoutTruncated: false,
+                stderrTruncated: false,
+              } satisfies GitVcsDriver.ExecuteGitResult),
+            ),
+        }),
       );
       const remoteNamesResultEffect = executeGit(
 @@ -2002,19 +2073,27 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
           allowNonZeroExit: true,
         },
       ).pipe(
-        Effect.catch((error) =>
+        Effect.catchTags({
-          Effect.logWarning(
+          GitCommandError: (error) =>
-            `GitVcsDriver.listRefs: remote name lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote name list.`,
+            Effect.logWarning(
-          ).pipe(
+              "Git remote name lookup failed; falling back to an empty remote name list.",
-            Effect.as({
+              {
-              exitCode: ChildProcessSpawner.ExitCode(1),
+                operation: error.operation,
-              stdout: "",
+                command: error.command,
-              stderr: "",
+                cwd: error.cwd,
-              stdoutTruncated: false,
+                detail: error.detail,
-              stderrTruncated: false,
+                cause: error,
-            } satisfies GitVcsDriver.ExecuteGitResult),
+              },
-          ),
+            ).pipe(
-        ),
+              Effect.as({
+                exitCode: ChildProcessSpawner.ExitCode(1),
+                stdout: "",
+                stderr: "",
+                stdoutTruncated: false,
+                stderrTruncated: false,
+              } satisfies GitVcsDriver.ExecuteGitResult),
+            ),
+        }),
       );
       const [defaultRef, worktreeList, remoteBranchResult, remoteNamesResult, branchLastCommit] =
 @@ -2175,7 +2254,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       : ["worktree", "add", worktreePath, input.refName];
     yield* executeGit("GitVcsDriver.createWorktree", input.cwd, args, {
-      fallbackErrorMessage: "git worktree add failed",
+      fallbackErrorDetail: "git worktree add failed",
     });
     if (input.newRefName && input.baseRefName) {
 @@ -2214,7 +2293,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
           `+refs/pull/${input.prNumber}/head:refs/heads/${input.branch}`,
         ],
         {
-          fallbackErrorMessage: "git fetch pull request branch failed",
+          fallbackErrorDetail: "git fetch pull request branch failed",
         },
       );
     });
 @@ -2227,7 +2306,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
         ["fetch", "--quiet", input.remoteName],
         {
           env: STATUS_UPSTREAM_REFRESH_ENV,
-          fallbackErrorMessage: `git fetch ${input.remoteName} failed`,
+          fallbackErrorDetail: `git fetch ${input.remoteName} failed`,
         },
       );
     },
 @@ -2302,18 +2381,8 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     args.push(input.path);
     yield* executeGit("GitVcsDriver.removeWorktree", input.cwd, args, {
       timeoutMs: 15_000,
-      fallbackErrorMessage: "git worktree remove failed",
+      fallbackErrorDetail: "git worktree remove failed",
-    }).pipe(
+    });
-      Effect.mapError((error) =>
-        createGitCommandError(
-          "GitVcsDriver.removeWorktree",
-          input.cwd,
-          args,
-          `${commandLabel(args)} failed (cwd: ${input.cwd}): ${error.message}`,
-          error,
-        ),
-      ),
-    );
   });
   const renameBranch: GitVcsDriver.GitVcsDriver["Service"]["renameBranch"] = Effect.fn(
 @@ -2330,7 +2399,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       ["branch", "-m", "--", input.oldBranch, targetBranch],
       {
         timeoutMs: 10_000,
-        fallbackErrorMessage: "git branch rename failed",
+        fallbackErrorDetail: "git branch rename failed",
       },
     );
 @@ -2407,7 +2476,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       yield* executeGit("GitVcsDriver.switchRef.checkout", input.cwd, checkoutArgs, {
         timeoutMs: 10_000,
-        fallbackErrorMessage: "git checkout failed",
+        fallbackErrorDetail: "git checkout failed",
       });
       const refName = yield* runGitStdout("GitVcsDriver.switchRef.currentBranch", input.cwd, [
 @@ -2423,7 +2492,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     function* (input) {
       yield* executeGit("GitVcsDriver.createRef", input.cwd, ["branch", input.refName], {
         timeoutMs: 10_000,
-        fallbackErrorMessage: "git branch create failed",
+        fallbackErrorDetail: "git branch create failed",
       });
       if (input.switchRef) {
         yield* switchRef({ cwd: input.cwd, refName: input.refName });
 @@ -2436,7 +2505,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
   const initRepo: GitVcsDriver.GitVcsDriver["Service"]["initRepo"] = (input) =>
     executeGit("GitVcsDriver.initRepo", input.cwd, ["init"], {
       timeoutMs: 10_000,
-      fallbackErrorMessage: "git init failed",
+      fallbackErrorDetail: "git init failed",
     }).pipe(Effect.asVoid);
   const listLocalBranchNames: GitVcsDriver.GitVcsDriver["Service"]["listLocalBranchNames"] = (

apps/server/src/vcs/VcsDriverRegistry.ts+13-15

 @@ -36,13 +36,6 @@ export class VcsDriverRegistry extends Context.Service<
   }
 >()("t3/vcs/VcsDriverRegistry") {}
-const unsupported = (operation: string, kind: VcsDriverKind, detail: string) =>
-  new VcsUnsupportedOperationError({
-    operation,
-    kind,
-    detail,
-  });
 function detectionCacheKey(input: {
   readonly cwd: string;
   readonly requestedKind: VcsDriverKind | "auto";
 @@ -78,7 +71,11 @@ export const make = Effect.gen(function* () {
     const driver = drivers[kind];
     if (!driver) {
       return Effect.fail(
-        unsupported("VcsDriverRegistry.get", kind, `No ${kind} VCS driver is registered.`),
+        new VcsUnsupportedOperationError({
+          operation: "VcsDriverRegistry.get",
+          kind,
+          detail: `No ${kind} VCS driver is registered.`,
+        }),
       );
     }
     return Effect.succeed(driver);
 @@ -137,13 +134,14 @@ export const make = Effect.gen(function* () {
       }
       const requestedKind = input.requestedKind ?? "auto";
-      return yield* unsupported(
+      return yield* new VcsUnsupportedOperationError({
-        "VcsDriverRegistry.resolve",
+        operation: "VcsDriverRegistry.resolve",
-        requestedKind === "auto" ? "unknown" : requestedKind,
+        kind: requestedKind === "auto" ? "unknown" : requestedKind,
-        requestedKind === "auto"
+        detail:
-          ? `No supported VCS repository was detected at ${input.cwd}.`
+          requestedKind === "auto"
-          : `No ${requestedKind} repository was detected at ${input.cwd}.`,
+            ? `No supported VCS repository was detected at ${input.cwd}.`
-      );
+            : `No ${requestedKind} repository was detected at ${input.cwd}.`,
+      });
     },
   );

packages/contracts/src/git.ts+6-1

 @@ -324,11 +324,16 @@ export class GitCommandError extends Schema.TaggedErrorClass<GitCommandError>()(
   operation: Schema.String,
   command: Schema.String,
   cwd: Schema.String,
+  argumentCount: Schema.optional(Schema.Number),
+  exitCode: Schema.optional(Schema.Number),
+  stdoutLength: Schema.optional(Schema.Number),
+  stderrLength: Schema.optional(Schema.Number),
+  outputLength: Schema.optional(Schema.Number),
   detail: Schema.String,
   cause: Schema.optional(Schema.Defect()),
 }) {
   override get message(): string {
-    return `Git command failed in ${this.operation}: ${this.command} (${this.cwd}) - ${this.detail}`;
+    return `Git command failed in ${this.operation} (${this.cwd}): ${this.detail}`;
   }
 }