feat(mcp): restore durable checkpoints

[juliusmarminge]

Agents could identify durable checkpoints but had no safe MCP path to request the application's existing serialized rollback workflow or observe its durable outcome.

This adds explicit t3_checkpoint_restore over ordinary V2 checkpoint.rollback, including exact scope/checkpoint identity, an explicit discard acknowledgement, durable idempotency keys, accepted receipts, and truthful REQUESTED/APPLIED/FAILED/PARTIAL outcomes.

Behavior:

• rejects stale, foreign, unsupported, active, ambiguous, or concurrently changed restore targets
• preflights the provider session, refreshes the projection, then serializes restore with ordinary same-thread V2 admission through finalization
• guards tracked, untracked, and staged workspace state, rejecting incomplete Git index reads while retaining the unavoidable external-process writer window
• classifies precondition rejection, retryable preflight failure, and uncertain post-mutation outcomes with distinct typed errors
• classifies uncertain filesystem, execution-defect, process-loss, and post-restore failures as partial without replay
• preserves retry behavior for proven pre-mutation failures and legacy unguarded clients
• reports a committed request as REQUESTED with unavailable observation when post-acceptance receipt reads fail

Focused validation:

• 119 focused assertions across contracts, MCP schema/service, VCS, orchestration, outbox recovery, presentation, and provider exposure
• temporary real-Git coverage for tracked, untracked, staged-only, and nested-cwd fingerprints
• real V2 effect-worker and managed fake-provider coverage for admission ordering, applied restore, provider/finalization partial outcomes, process loss, and same-key replay
• targeted contracts/server/mobile typecheck, lint, and formatting

Dependency: upper layer of native stack #8713; requires #8702 for checkpoint discovery, identity, and MCP registration.

Implemented by GPT-5.6-Sol via Codex in T3 Code.

---

Note

High Risk
Destructive Git workspace restore with new concurrency guards and partial-failure semantics; mistakes could corrupt worktrees or mis-report rollback outcomes to agents.

Overview
Adds t3_checkpoint_restore, an MCP entry point that accepts an exact checkpoint/scope, requires discardChanges: true, and drives the existing V2 checkpoint.rollback command with durable clientRequestId idempotency, receipts, and REQUESTED / APPLIED / FAILED / PARTIAL status from outbox effects.

Before dispatch, the service validates thread idle state, provider rollback support, ref availability, and captures an expectedWorkspaceFingerprint via new readWorkspaceFingerprint (Git temp-index hash of tracked, untracked, and staged state scoped to restore cwd). CheckpointService.restore refuses to mutate the worktree when the fingerprint drifts or optional pre-restore checks fail.

CheckpointRollbackService now runs under ThreadDispatchLockV2, re-reads projections at admission, rejects ambiguous rollback targets, and maps filesystem/provider/persistence failures into rejected, retryable preflight, or partial errors. Guarded rollbacks carry expectedIdle and the fingerprint on outbox provider-thread.rollback effects; the worker assigns checkpoint_restore_rejected / checkpoint_restore_partial failure codes, avoids retrying partial outcomes, and marks uncertain guarded restores failed after process loss.

Unit and integration tests cover MCP restore behavior, fingerprint edge cases, admission races, and rollback error classification.

^{Reviewed by Cursor Bugbot for commit 8f94a42. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add durable t3_checkpoint_restore MCP tool with guarded, idempotent checkpoint rollback

• Adds a new MCP tool t3_checkpoint_restore that dispatches a checkpoint.rollback command with expectedIdle and expectedWorkspaceFingerprint guards, then reports idempotent results (REQUESTED, APPLIED, FAILED, PARTIAL) via durable command receipts and effect status.
• Introduces readWorkspaceFingerprint in GitVcsDriver and CheckpointStore to hash the worktree tree OID and staged index, detecting concurrent changes before a restore.
• Wraps rollback execution in a per-thread ThreadDispatchLockV2 serial executor and performs two-phase admission: an initial snapshot check, then a validateBeforeRestore precondition check immediately before mutating the workspace.
• Classifies rollback failures into CheckpointRollbackRejectedError (precondition/idle/target violations), CheckpointRollbackPreflightError (retryable preflight failures), and CheckpointRollbackPartialError (restore completed but provider rollback or finalization failed); these map to structured failureCode values persisted in the effect outbox.
• On process loss, reconcileAfterProcessLoss terminally fails guarded rollback effects as checkpoint_restore_partial instead of requeueing, preventing unsafe replay after a partial filesystem restore.
• Risk: CheckpointServiceV2Error replaces the single CheckpointRestoreError with a union of three variants; callers that pattern-matched on the old CheckpointRestoreError tag must update to handle CheckpointRestorePreconditionError, CheckpointRestorePreflightError, and CheckpointRestoreOutcomeUnknownError.

^{Macroscope summarized 8f94a42.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c6095f52-2c53-45a3-9c43-10425f775faa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[macroscopeapp]

Effect service conventions review of the changed TypeScript. Three findings, all in the new checkpoint-restore path: two concern classifying tagged failures by message/tag text instead of structurally, and one is a namespace-erasing service import in the new integration test. Everything else (new CheckpointStore.readWorkspaceFingerprint, VcsCheckpointOps extension, Schema.TaggedErrorClass usage, layer wiring) follows the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new destructive MCP checkpoint-restore workflow spanning contracts, Git state handling, orchestration, provider rollback, durable outbox recovery, and shared concurrency control. Its filesystem and provider side effects, partial-failure semantics, and changes to existing rollback execution require human review.

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

[macroscopeapp]

One convention finding: the new optional reason discriminator on CheckpointRestoreError drives caller control flow (and the caller-visible PARTIAL/FAILED status), which the conventions ask to model as distinct error classes. The three issues raised on the previous revision (message-substring classification of orchestrator failures, lastError.includes("result is partial"), and layer as ... aliased service imports in the integration test) are all resolved.

^{Posted via Macroscope — Effect Service Conventions}

[github-actions]

Thread transfer impact

⚠️ The latest CI run did not produce a thread transfer result for 8f94a42.

This comment will update automatically after the next completed run.

[macroscopeapp]

Effect service conventions review: one finding on error modeling for the new checkpoint restore path. The import/namespace and Effect.catchTags issues raised on the previous revision look addressed.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit dbf55ef. Configure here.}

[macroscopeapp]

One convention finding on the new guarded-restore failure classification. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention issue found in the new checkpoint rollback error model.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

One convention finding on the new checkpoint rollback error split. Everything else in the changed Effect service code (namespace imports, Foo["Service"] usage, Effect.catchTags at the MCP dispatch boundary, structured Schema.TaggedErrorClass failures with preserved cause, and the new ThreadDispatchLockV2 tag/layer wiring) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}