fix(server): checkpoint workspaces with empty nested repositories

[saphid]

An untracked embedded repository created with git init empty has no commit, so Git rejects checkpoint staging with does not have a commit checked out. Checkpoint capture should still save the surrounding workspace.

Keep the existing nested-repository fix from saphid: after staging fails, discover untracked embedded repositories without a HEAD commit and retry using literal path exclusions. Successful captures do no extra scan, committed embedded repositories remain gitlinks, and the user's index is preserved. Incomplete recovery listings and unrelated clean-filter failures still fail capture.

Bound this exceptional path to 64 candidate directories and one five-second budget across discovery, Git queue admission, HEAD probes, and the staging retry. Excessive or timed-out recovery returns the original staging error, publishes no checkpoint ref, and removes the private temporary index and its lock file. Cancellation remains interruption. Nested HEAD probes clear inherited repository bindings, so an outer GIT_DIR cannot make an empty child appear committed.

Verification: Git driver and checkpoint store tests: 52 passed. Added cases cover the candidate cap before any probe, blocked discovery/probe/retry with TestClock and Deferred, and cancellation/private-index cleanup, including a lock left behind by interrupted staging, and inherited outer GIT_DIR. Existing cases cover literal paths with spaces/brackets, multiple empty repositories, committed gitlinks, sparse/index behavior, clean-filter rejection, and truncated listings. Across all five stack layers, 116 focused tests pass; targeted lint, formatting, diff checks, and server-only typecheck pass. No UI changes.

This reuses the original PR and retains its existing commit authors. The four preceding checkpoint fixes, ending with #12308, have landed. This PR is now rebased directly onto main and contains only the Git driver fix and its tests. The separate v2 startup recovery from #12153 addresses startup handling rather than this staging failure.

After rebasing onto main, all 52 Git driver and checkpoint store tests passed again. The nine remaining commits are content-equivalent to the previously reviewed implementation.

Prepared with Codex.

Summary by CodeRabbit

• Bug Fixes
  • Checkpoint capture now recovers from staging failures caused by uncommitted nested repositories.
  • Nested repositories without a commit are skipped, while committed nested repositories are recorded correctly.
  • Untracked files and staged content are captured without altering the existing index or nested repository files.
  • Failed or interrupted captures now clean up temporary checkpoint state and locks.
  • Recovery respects time limits and safely aborts when repository discovery is incomplete or exceeds supported limits.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 99659016-6605-4e1e-b81b-f968bda0d516

📥 Commits

Reviewing files that changed from the base of the PR and between 2d53a60 and 2999887.

📒 Files selected for processing (2)

• apps/server/src/vcs/GitVcsDriver.test.ts
• apps/server/src/vcs/GitVcsDriver.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

captureCheckpoint now retries staging after excluding uncommitted nested repositories. It enforces candidate and deadline limits, sanitizes nested probes, removes temporary index locks, and preserves original failures or interruptions. Tests cover these paths.

Changes

Checkpoint capture

Layer / File(s)	Summary
Staging retry for nested repositories apps/server/src/vcs/GitVcsDriver.ts	captureCheckpoint uses bounded recovery after staging failure. It discovers nested repositories without HEAD, retries with literal exclusions, sanitizes nested probes, and removes temporary index locks.
Checkpoint capture validation apps/server/src/vcs/GitVcsDriver.test.ts	Tests verify committed and unborn nested repositories, inherited GIT_DIR, clean-filter and truncated-list failures, excessive candidates, shared deadlines, interruption, and cleanup.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant captureCheckpoint
  participant GitVcsDriver
  participant Git
  participant Filesystem
  captureCheckpoint->>GitVcsDriver: stage files
  GitVcsDriver->>Git: git add -A
  Git-->>GitVcsDriver: staging failure
  GitVcsDriver->>Git: list untracked paths
  GitVcsDriver->>Filesystem: probe nested HEAD with sanitized environment
  GitVcsDriver->>Git: retry staging with exclusions
  GitVcsDriver-->>captureCheckpoint: checkpoint result or original failure

Loading

Suggested reviewers: t3dotgg

Merge Risk: ⚪ Minimal · up to 29998

Checkpoint recovery remains bounded and preserves the intended nested-repository behavior without a concrete outstanding merge risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: fixing checkpoint capture for workspaces with empty nested Git repositories.
Description check	✅ Passed	The description explains what changed, why it was needed, the recovery limits, cleanup behavior, test coverage, and that there are no UI changes. It does not use the template headings or checklist, bu…

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved at 2999887

Macroscope's review found this PR approvable — This is a contained checkpointing bug fix that preserves normal captures and adds bounded recovery for empty nested repositories. Extensive tests cover the retry, timeout, cancellation, truncation, filtering, and Git-environment cases.

Notes:

• Diff unchanged. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate db4d52a

Dismissing prior approval to re-evaluate e83e5f7

Dismissing prior approval to re-evaluate d95e95e

[macroscopeapp]

All clear

^{Posted via Macroscope — Effect Service Conventions}