fix(server): capture checkpoints in sparse checkouts

[Gigioxx]

Large cone-mode sparse checkouts rejected checkpoint index reuse, then failed on untracked files outside the cone.

Keep the copied index and refresh it with Git instead of listing every tracked path. When a fresh index is needed, stage existing files first, then apply in-cone deletions. This preserves excluded tracked files, captures outside-cone artifacts, and leaves the workspace index untouched.

Fixes #12080.

Verification:

• Reproduced the original failure in tests and an isolated browser. All 38 focused Git driver/checkpoint store tests, server typecheck, and targeted lint pass. The ten sparse cases pass on Git 2.34, 2.52, and 2.53, including missing/corrupt indexes, assumed-unchanged deletions, racy edits, and deleted directories.
• A synthetic WSL repo with 458,319 tracked files, 247,000 in-cone, and a 45 MB listing captured in 19 seconds. Confirmed index reuse, byte-for-byte workspace index preservation, and only the intended edit/new artifact in the checkpoint.
• Real Codex turns in the isolated browser verify edits and deletions. Native Windows desktop was not separately exercised.

Reviewed with Claude Opus 5; review findings fixed and rechecked.

Model: GPT-6. Harness: Codex.

Summary by CodeRabbit

• Bug Fixes
  • Improved checkpoint capture for sparse checkouts, preserving included file changes while keeping excluded files out of the working tree.
  • Better handling of deleted, assumed-unchanged, missing, and invalid index states.
  • Preserved the user’s existing Git index, including its original state and contents.
  • Fixed cleanup of temporary checkpoint data when an existing index cannot be reused.

[macroscopeapp]

Approvability

Verdict: Approved at 6dbb73b

Macroscope's review found this PR approvable — This is a contained server-side bug fix that improves checkpoint capture for cone-mode sparse checkouts while preserving existing non-sparse behavior and the user's Git index. The added tests cover sparse-index variants and degraded index states, with no product-default or static-analysis configuration changes.

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

[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: 69609399-57d5-43e5-803e-0d2e0da79d81

📥 Commits

Reviewing files that changed from the base of the PR and between f4ef515 and 6dbb73b.

📒 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; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

captureCheckpoint now detects sparse cone checkouts, validates whether a temporary index can be reused, and uses sparse-aware staging when rebuilding the index. Tests cover sparse and non-sparse indexes across normal, assumed, missing, and invalid states.

Changes

Sparse checkpoint capture

Layer / File(s)	Summary
Sparse index reuse and fallback apps/server/src/vcs/GitVcsDriver.ts	captureCheckpoint detects sparse cone mode, preserves temporary index timestamps, refreshes assume-unchanged entries, checks deleted files, and cleans up before rebuilding the index.
Sparse staging and validation apps/server/src/vcs/GitVcsDriver.ts, apps/server/src/vcs/GitVcsDriver.test.ts	Fresh sparse checkouts use git add --sparse with deletion handling. Tests cover sparse-index modes, index states, checkpoint contents, working-tree files, and unchanged index bytes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant captureCheckpoint
  participant GitConfig
  participant TemporaryIndex
  participant GitIndex
  participant Checkpoint
  captureCheckpoint->>GitConfig: read sparse checkout settings
  captureCheckpoint->>TemporaryIndex: copy and inspect index
  TemporaryIndex->>GitIndex: refresh assumed entries and detect deletions
  GitIndex-->>captureCheckpoint: reuse or rebuild decision
  captureCheckpoint->>Checkpoint: capture sparse-aware file state

Loading

Suggested reviewers: t3dotgg

Merge Risk: ⚪ Minimal · up to 6dbb7

The sparse-checkout checkpoint changes are mergeable after normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: fixing checkpoint capture for sparse checkouts.
Description check	✅ Passed	The description gives a clear problem statement, implementation summary, rationale, issue reference, and detailed verification results. It does not use the template headings or include the checklist, …
Linked Issues check	✅ Passed	The PR addresses #12080. In sparse cone mode, captureCheckpoint avoids the large ls-files -v listing, refreshes assumed-unchanged entries, checks deletions with bounded output, and uses a copied i…
Out of Scope Changes check	✅ Passed	The reviewed changes are limited to GitVcsDriver.captureCheckpoint and its focused tests. They directly implement and verify the checkpoint behavior required by #12080. No unrelated product behavior…
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…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[juliusmarminge]

Closing as superseded by #12154, which is now merged and covers the same sparse-checkpoint fix.