fix(server): refresh file search outside checkpoint processing

[juliusmarminge]

Workspace file-search refresh runs inside the checkpoint worker. A blocked native scan delays completion receipts and other workspaces even after their checkpoint Git ref is saved.

Run search refresh in a separate scoped, drainable worker after capture/restore. Coalesce queued requests by workspace, allowing one follow-up while that workspace's scan is running. Refresh failures are logged without failing checkpoint processing, and shutdown/drain still waits for the refresh worker.

Verification: a Deferred-controlled scan remains blocked while turns in two real Git repositories finish and their latest checkpoint contents are verified. Repeated requests for the busy workspace yield only one queued follow-up; releasing the scan and draining produces three refresh calls across both workspaces. Integrated reactor suite: 45 tests passed; targeted lint and server-only typecheck passed.

Depends on #12307. The fifth dependent fix is #12181, retained on its author's fork and based on this branch. GitHub excludes fork PRs from native stack grouping.

Prepared with Codex.

Summary by CodeRabbit

• Bug Fixes
  • Checkpoint capture and revert operations now refresh workspace entries reliably after completion.
  • Duplicate refresh requests are consolidated while ensuring each workspace reaches its latest state.
  • Checkpoint receipts and snapshots remain available when workspace refreshes are delayed.
  • Completion and shutdown now wait for pending workspace updates, improving consistency across multiple workspaces.
  • Refresh failures are handled more clearly while interruption-related failures continue to be reported.

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	13.5 KiB	—	15.1 KiB	✅
Codex	Thread snapshot wire	—	7.1 KiB	—	7.3 KiB	✅
Codex	Live turn WebSocket wire	—	6.4 KiB	—	7.8 KiB	✅
Codex	Live turn WebSocket decoded	—	56.2 KiB	—	66.4 KiB	✅
Codex	Live turn messages	—	9	—	21	✅
Claude	Total thread wire	—	13.5 KiB	—	15.1 KiB	✅
Claude	Thread snapshot wire	—	7.1 KiB	—	7.3 KiB	✅
Claude	Live turn WebSocket wire	—	6.4 KiB	—	7.8 KiB	✅
Claude	Live turn WebSocket decoded	—	57.0 KiB	—	66.4 KiB	✅
Claude	Live turn messages	—	9	—	21	✅

Baseline: unavailable · PR result: 38dc191 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 114.0 KiB
• Claude decoded thread snapshot: 114.6 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Approved at 7a863a3

Macroscope's review found this PR approvable — This focused server bug fix asynchronously refreshes the existing file-search index so checkpoint processing is not blocked, while coalescing duplicate workspace scans and draining pending work during shutdown. A regression test covers blocked refreshes, multiple workspaces, checkpoint completion, and coalescing.

No code changes detected at 38dc191. Prior analysis still applies.

^{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: Team

Run ID: 7fed747f-37a7-402f-8594-41a3b2f8104a

📥 Commits

Reviewing files that changed from the base of the PR and between ba04a6b and 73f8a1f.

📒 Files selected for processing (2)

• apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
• apps/server/src/orchestration/Layers/CheckpointReactor.ts

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

---

📝 Walkthrough

Walkthrough

Checkpoint capture and revert now queue coalesced workspace-entry refreshes. Reactor draining waits for queued refreshes. Tests cover blocked refreshes across two workspaces.

Changes

Workspace refresh coordination

Layer / File(s)	Summary
Queued workspace refresh execution apps/server/src/orchestration/Layers/CheckpointReactor.ts	Checkpoint capture and revert queue workspace-entry refreshes. The reactor coalesces refreshes, handles failures, removes formatted causes from git-status warnings, and drains the refresh worker.
Multi-workspace refresh validation apps/server/src/orchestration/Layers/CheckpointReactor.test.ts	The test harness accepts a workspace refresh callback. Tests verify checkpoint receipts, snapshot persistence, refresh coalescing, and later execution across two workspaces.

Priority: ⬇️ Low

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CheckpointReactor
  participant WorkspaceRefreshWorker
  participant WorkspaceEntries
  CheckpointReactor->>WorkspaceRefreshWorker: Queue workspace refresh
  CheckpointReactor->>WorkspaceRefreshWorker: Drain queued refreshes
  WorkspaceRefreshWorker->>WorkspaceEntries: Execute coalesced refresh
  WorkspaceEntries-->>WorkspaceRefreshWorker: Complete or interrupt
  WorkspaceRefreshWorker-->>CheckpointReactor: Report drain completion

Loading

Suggested reviewers: t3dotgg

Merge Risk: ⚪ Minimal · up to 73f8a

The asynchronous refresh path preserves checkpoint completion and coalesces later workspace updates without a concrete unresolved merge risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 summarizes the primary change: moving server file-search refresh outside checkpoint processing.
Description check	✅ Passed	The description explains what changed, why it changed, the worker behavior, failure handling, drain behavior, verification, and dependency context. It omits the template checklist, but the core requir…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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

Dismissing prior approval to re-evaluate 7a863a3