feat(mcp): inspect durable checkpoints

[juliusmarminge]

Checkpoint metadata and diffs existed behind internal services, but coding agents could not discover or inspect a durable restore target through MCP.

This adds bounded t3_checkpoint_list and t3_checkpoint_diff tools scoped to the caller's current project. Results expose stable scope/source identity, per-checkpoint availability and restore support, bounded file summaries, and UTF-16-safe diff cursors without duplicating checkpoint storage.

Behavior:

• validates thread, scope, checkpoint, and filesystem ref identity before reading diffs
• slices checkpoint pages before availability I/O and isolates unreadable entries
• exposes read tools consistently through the MCP server, provider allowlists, presentation, and user/internal docs
• marks ambiguous materialized baselines and null-ordinal targets unsupported instead of mapping them to thread start

Focused validation:

• checkpoint contract and service tests
• production MCP tools/list root-object schema coverage
• presentation and Claude read-only allowlist coverage
• targeted contracts/server/shared typecheck, lint, and formatting

Dependency: bottom layer of native stack #8713, rooted on agents/mcp-controls/base-490318a at the agreed V2 pin.

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

Note

Add CheckpointMcpService with t3_checkpoint_list and t3_checkpoint_diff MCP tools

• Introduces a new read-only MCP service exposing two tools for inspecting durable checkpoints: list (with bounded file summaries and pagination) and diff (with UTF-16-safe slicing and cursor pagination)
• Adds shared schemas, error types, and a checkpointRollbackAppRunOrdinal helper in checkpointMcp.ts and orchestrationV2.ts
• Wires the toolkit into McpHttpServer.ts, registers handlers in handlers.ts, and pre-approves both tools in the Claude read-only allowlist in ClaudeAdapterV2.ts
• Behavioral Change: Claude read-only sandbox sessions now pre-approve mcp__t3-code__t3_checkpoint_list and mcp__t3-code__t3_checkpoint_diff via CLAUDE_READ_ONLY_T3_MCP_ALLOWED_TOOLS; the read-only tool aggregation test in ClaudeAdapterV2.test.ts must include CheckpointToolkit

^{Macroscope summarized 9889acb.}

---

Note

Medium Risk
Read-only MCP surface, but it reads full thread projections and workspace refs with restore-advisory logic tied to provider rollback semantics; incorrect rollback ordinal resolution could mislead agents about restore eligibility.

Overview
Adds t3_checkpoint_list and t3_checkpoint_diff so agents can inspect durable workspace checkpoints over MCP without mutating state. A new CheckpointMcpService loads thread projections via ThreadManagementService, enforces orchestration capability and same-project thread boundaries, and talks to CheckpointStore only for the paginated slice.

List returns newest-first checkpoints with bounded file summaries, per-entry ref availability (failures isolated so one bad ref does not break the page), and restoreSupport blockers derived from thread/run state, provider capabilities, and checkpointRollbackAppRunOrdinal. Diff validates thread/scope/checkpoint identity before reading refs or returning an empty patch, then serves UTF-16-safe paginated diff text.

Shared contracts live in checkpointMcp.ts; tools register on the HTTP MCP server with read-only annotations, UI presentation labels, and Claude sandbox allowlist entries. checkpointRollbackAppRunOrdinal treats null app ordinals as thread start only for ordinal-zero root scopes—materialized baselines and manual scopes surface rollback_target_ambiguous instead of implying restore. Docs and tests cover contracts, service behavior, MCP tools/list, and capture scenarios for materialized baselines.

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

[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: 8c209607-1ca1-4cdd-9029-7344a74a80a2

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.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

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

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

[macroscopeapp]

UI consistency review found one environment-routing regression in the shared markdown renderer, plus a small dead-CSS addition. Details inline.

^{Posted via Macroscope — UI Consistency}

[macroscopeapp]

Macroscope has since reviewed this pull request. An earlier review was skipped by a cost limit; a review has now completed, so that notice no longer applies.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds two new production MCP capabilities and roughly 1.3k lines of cross-layer logic for checkpoint metadata, filesystem-ref reads, provider rollback support, and paginated diffs. The operations are read-only and scoped, but the new server surface and agent preapproval behavior make this a substantial feature requiring human review.

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

[macroscopeapp]

Reviewed the new checkpoint MCP service, toolkit, and contracts against the Effect service conventions. Structure (namespace imports, inline Context.Service interface, exported make/layer, Service["Service"] typing, Layer.mock test seams) follows the existing WorktreeMcpService/OrchestratorMcpService pattern. One error-translation issue below.

^{Posted via Macroscope — Effect Service Conventions}

[github-actions]

Thread transfer impact

⚠️ The latest CI run did not produce a thread transfer result for 9889acb.

This comment will update automatically after the next completed run.