[Bug]: Checkpoint capture fails with exit 1 on every turn when the project folder is gitignored by a parent repo #13712

Activity

1. juliusmarminge commented on Sep 25, 2026

   

   juliusmarminge

   on Sep 25, 2026

   Member

   More actions

   Triage

   Confirmed on current main (ed809f7ad). This is a real server checkpoint bug. Not already fixed. v0.0.42 (719a76ca1) already runs git add -A -- . from the project directory, and the commits since that tag do not handle an ignored project folder. Reproduced on Linux with git 2.43.0. The reported Apple Git 2.54.0 message is the same hint.

   What you reported. The project folder sits inside a git repo whose ignore rules exclude that folder (an allowlist .gitignore is the usual way to get there). Every finished turn reports:

   VCS process failed in GitVcsDriver.checkpoints.captureCheckpoint: git (/path/to/repo/sub) exited with 1 - Process exited with a non-zero status.
   

   The thread never gets a checkpoint, so the turn diff and Go back stay unavailable. The agent itself keeps working.

   Your diagnosis is right. The command T3 actually runs is git add -A -- . with cwd set to the project directory, not git add -A -- sub from the parent. Both forms exit 1 with The following paths are ignored by one of your .gitignore files. Naming the ignored directory is what fails. git rev-parse --is-inside-work-tree still prints true, so T3 treats the folder as a normal git project and tries to capture it.

   What the code does

   1. An ignored subdirectory still counts as a git repo, so capture runs.

   resolveCheckpointCwd only skips the workspace when repository detection fails:

   t3code/apps/server/src/orchestration/Layers/CheckpointReactor.ts

   Lines 233 to 239 in ed809f7

   	if (!cwd) {
   	return undefined;
   	}
   	if (!(yield* checkpointStore.isGitRepository(cwd))) {
   	return undefined;
   	}
   	return cwd;

   Detection is git rev-parse --is-inside-work-tree:

   t3code/apps/server/src/vcs/GitVcsDriver.ts

   Lines 522 to 533 in ed809f7

   	const isInsideWorkTree: VcsDriver.VcsDriver["Service"]["isInsideWorkTree"] = (cwd) =>
   	gitCommand(
   	vcsProcess,
   	"GitVcsDriver.isInsideWorkTree",
   	cwd,
   	["rev-parse", "--is-inside-work-tree"],
   	{
   	allowNonZeroExit: true,
   	timeoutMs: 5_000,
   	maxOutputBytes: 4_096,
   	},
   	).pipe(Effect.map((result) => result.exitCode === 0 && result.stdout.trim() === "true"));

   From inside the ignored folder that command prints true, and --show-toplevel is the parent repo. There is no per-project way to turn checkpoints off.

   2. Staging names the project directory, which Git then refuses.

           const stageFiles = (exclusions: ReadonlyArray<string>) =>
             execute({
               operation,
               cwd: input.cwd,
               // Preserve absent skipped entries, but capture present nonignored files outside the cone.
               args: [
                 ...indexConfig,
                 ...durableWrite,
                 "add",
                 ...(sparseCheckout ? ["--sparse"] : []),
                 "-A",
                 "--",
                 ".",
                 ...exclusions,
               ],
               env: commitEnv,
             });

   On v0.0.42 the same pathspec is already there, without the later sparse and durable-write flags:

   t3code/apps/server/src/vcs/GitVcsDriver.ts

   Lines 784 to 789 in 719a76c

   	yield* execute({
   	operation,
   	cwd: input.cwd,
   	args: ["add", "-A", "--", "."],
   	env: commitEnv,
   	});

   The . pathspec is required for a project that is a subdirectory of a larger repo. Dropping it is the wrong fix: git add -A with no pathspec updates the entire working tree (confirmed: from the ignored folder it staged a modified file in a sibling directory). git add -f is also the wrong fix. In the allowlist repro it staged sub/.venv/secret along with the project file.

   3. The nested-repo recovery does not catch this.

   On main, a failed git add looks for untracked nested repos and retries with exclusions (#12181). That scan is git ls-files --others --exclude-standard, which prints nothing for an ignored directory, so the original error is rethrown. v0.0.42 does not have this recovery at all. The exit is not retried either: #11665 only retries a lock file or a missing path, and paths are ignored matches neither.

   4. The activity hides Git's real message.

   Turn completion records checkpoint.capture.failed with summary Checkpoint capture failed and this error as the detail:

   t3code/apps/server/src/orchestration/Layers/CheckpointReactor.ts

   Lines 985 to 996 in ed809f7

   	yield* captureCheckpointFromTurnCompletion(event).pipe(
   	Effect.catch((error) =>
   	Effect.flatMap(nowIso, (createdAt) =>
   	appendCaptureFailureActivity({
   	threadId: event.threadId,
   	turnId,
   	detail: error.message,
   	createdAt,
   	}).pipe(Effect.catch(() => Effect.void)),
   	),
   	),
   	);

   VcsProcessExitError replaces stderr with Process exited with a non-zero status. Git's own text (The following paths are ignored… / Use -f if you really want to add them.) is discarded. That opacity is #4380 and #12224, not this bug.

   The baseline capture on thread.message-sent, thread.turn-start-requested, and turn.started fails too. Those misses are only a reactor warning (checkpoint reactor failed to process input), because the baseline never sticks. The visible activity is once per completed turn.

   Reproduction

   Allowlist ignore, then git add -A -- . from the ignored folder, including after read-tree HEAD into a private index (the capture sequence):

   git check-ignore -q -- .   # exit 0, ignored
   git add -A -- .             # exit 1
   The following paths are ignored by one of your .gitignore files:
   sub
   
   git add -A                  # exit 0, but stages the whole parent work tree
   git add -f -A -- .          # exit 0, and stages .venv/secret
   

   The same exit 1 happens for a sub/ rule. A normal subdirectory, a subdirectory whose files are ignored while the directory itself is not (sub/*), and a /* ignore with !sub/ and !sub/** all exit 0. git check-ignore -q -- . at the repo root exits 1.

   One sibling the check-ignore probe misses: if files inside the folder were committed and the directory was ignored afterward, git check-ignore -q -- . exits 1, but git add -A -- . still exits 1, even when the only edit is one of those tracked files. git add -u -- . stages the tracked edit and leaves new ignored files out. The reported allowlist folder has nothing tracked, so check-ignore catches it.

   Not a duplicate

   • [Bug]: Checkpoint fail in git repos #2017 — same visible checkpoint failure, no cause identified. This layout is one way to get that error. The report there does not show an ignored project folder.
   • [Bug]: Checkpoint capture fails with exit 128 on every turn when the project path is a symlink to a repository subdirectory #13187 and open PR fix(server): capture checkpoints through symlinked repository subdirectories #13223 — symlink to a repo subdirectory, exit 128, because path.resolve joins a relative --git-common-dir. Different command, different exit.
   • [Bug]: Partial .git directory makes checkpoint reactor attempt VCS operations for a non-repository project #8873 — a partial .git directory makes the reactor attempt checkpoints for a directory Git does not consider a repo. Different error (VcsUnsupportedOperationError).
   • Git command errors discard stderr, making failures opaque to callers #4380 and [Bug]: PullRequestSyncReactor's gh calls fail with an opaque error — VcsProcessExitError discards stderr, so the real cause can't be diagnosed #12224 — stderr dropped from VcsProcessExitError. That is why this trace does not say paths are ignored.

   No open issue covers checkpoint capture of a project directory that a parent repo gitignores.

   Fix direction

   Skip capture when the project directory itself is ignored. Do not git add -f, and do not publish the parent HEAD tree in its place. git add -u exits 0 in the fully ignored folder and write-tree then writes the parent tree. diffCheckpoints diffs those whole trees with no path limiter, so the thread diff would be the rest of the repo and still would not contain the ignored files.

   1. Before stageFiles, from the project cwd, run git check-ignore -q -- .. Exit 0 means this folder is ignored. Skip the capture and record one notice that checkpoints are unavailable because the folder is ignored by git. Do not append checkpoint.capture.failed again on later turns.
   2. On the tracked-then-ignored variant above, check-ignore stays silent while git add -A -- . still exits 1. Fall back to git add -u -- . for that failure so tracked edits are captured and ignored untracked files are not. Do not use -f.
   3. Test both layouts with a real git repo: the allowlist repro must not call git add and must not write a checkpoint ref; a subdirectory that is not ignored must still snapshot only that subdirectory. A third case, tracked files inside a directory that was ignored later, must capture the tracked edit via git add -u and must not stage a new ignored file.

   Workaround

   The agent can keep working. Checkpoints, the turn diff, and Go back stay unavailable for this project until a fix ships.

   Opening the parent repository stops the exit 1, because capture no longer names the ignored directory. Files inside the ignored folder are still left out of the snapshot. To checkpoint that folder it has to be a path Git will track (negation rules, or its own repository). Forcing the add would pull in .venv, caches, and secrets.

   Accepting as a server checkpoint bug.
2. juliusmarminge

   added

   bugSomething is broken or behaving incorrectly.Something is broken or behaving incorrectly.

   acceptedfeature request acceptedfeature request accepted

   via-triageFiled through npx t3 triageFiled through npx t3 triage

   on Sep 25, 2026
3. juliusmarminge

   closed this as completedin #14892on Oct 20, 2026