fix(runtime): threads own the restore points on their turns; undo restores or refuses (#6621)

[Hmbown]

Closes #6621
Closes #6659

Root cause

A Runtime thread had no lasting identity for its workspace snapshots:

• ensure_engine_loaded built every engine with EngineConfig.session_id = None. The engine therefore tagged each pre-turn, tool and post-turn snapshot with a random uuid. The uuid changed on every rebuild (restart, LRU eviction), and nothing recorded it.
• patch-undo and file-revert decided ownership from ThreadRecord.session_id, which is really a link to the saved-session document. It is None on a fresh thread, and save, resume and fork rebind it to ids that own no snapshots.

The result on a fresh thread: patch-undo returned 201 with files_restored: false and forked the conversation while the files stayed changed, and file-revert returned 409.

Even when the tag matched, the selection was wrong. patch-undo restored the newest differing snapshot over the whole tree. For a turn with two writes, the first write survived. Unrelated later edits by the user or another thread were reverted.

Fix

Engine identity

• The engine runs every Runtime thread under the thread's own id, in both EngineConfig and SyncSession, across restarts and eviction.
• The saved-session binding no longer changes the engine's identity, so rebinding it no longer creates a conversation boundary partway through a thread.

Recorded restore points

• The engine reports each snapshot it takes as Event::WorkspaceSnapshotTaken. This is also a new protocol EventMsg kind.
• The Runtime sets await_post_turn_snapshot, so the post-turn snapshot is taken before TurnComplete. The TUI keeps its fire-and-forget post-turn snapshot (Post-turn UI freeze: terminal unresponsive for seconds after stream ends before copy/paste/selection works #234).
• monitor_turn appends each receipt to TurnRecord.workspace_snapshots and publishes it as turn.workspace_snapshot. Forks clone turn records, so a fork owns the restore points of the turns it inherited.

Resolution

• A restore point resolves by tree id, session tag and label kind against the full, uncapped store listing.
• The snapshot prune runs after every snapshot once there are more than 50. It rewrites every commit id but keeps trees, so the tree id is what holds up.

patch-undo

• It undoes whole turns. For each dropped turn's pre-to-post window it takes the changed paths, and restores only those paths to their content before the first dropped turn.
• Later edits by the user or another thread in the same workspace survive.
• It refuses when a path changed after the turns or between them.
• It never forks over files it could not restore. Instead it returns 409 with error.code:
  • restore_point_unavailable
  • restore_point_pruned
  • workspace_changed_since_turn
  • restore_requires_trust
  • workspace_unavailable
• 201 with files_restored: false now means there was provably nothing to restore: the turns ran here without tools, or their files are already back.

file-revert

• It accepts only a tool or pre_turn restore point recorded on the thread's own turns. Another thread's or a TUI session's snapshot gets 409.

Docs

• docs/RUNTIME_API.md now covers ownership, the receipts, the event and the error codes.

Behaviour changes a client will see

• Imported (resume-thread) and pre-upgrade turns that may have changed files have no recorded restore point. patch-undo on them now returns 409 restore_point_unavailable instead of a 201 that changed nothing. The client should offer POST /undo instead.
• The client adoption work is tracked in Hmbown/codewhale-app#127.
• The TUI /undo gaps (whole-tree restore, list(100) cap, fork-inherited restore points) are filed as TUI /undo: path-scoped restore, uncapped lookup, and fork-inherited restore points #6644.
• A path changed during a dropped turn outside the turn's own tool spans (another thread, an editor, a background job) now refuses the undo with workspace_changed_since_turn rather than being reverted.
• A file-tool write to a gitignored, built-in-excluded or out-of-workspace path refuses with path_not_snapshotted. A shell command declares no paths, so its writes under excluded paths (build output, installs) stay outside what patch-undo restores; the docs say so.

Critic points

1. Whole-tree restore and isolation: fixed. The restore is limited to the paths the turn changed, and refuses paths changed since (threads_cannot_restore_each_others_snapshots, patch_undo_helper_refuses_to_overwrite_later_edits).
2. Post-turn receipts: recorded, and awaited before TurnComplete on the Runtime.
3. One identity rule: the engine id is always thread.id.
4. Restore-point selection: the earliest pre_turn is paired with the post_turn that closes it, in FIFO record order. An unclosed window gets 409.
5. Pruned-snapshot detection: no list(100) cap. Lookup is by tree, so a prune rewrite still resolves (patch_undo_helper_survives_a_prune_that_rewrites_commit_ids).
6. Client contract: receipts appear in the thread/turn JSON, the SSE stream and the protocol EventMsg. Refusals carry a stable error.code. The client follow-up is filed.
7. The TUI still uses its own selection; that is filed as TUI /undo: path-scoped restore, uncapped lookup, and fork-inherited restore points #6644 and is not claimed as fixed here.
8. A receipt that fails to save is logged at warn. The turn is then left without that restore point and fails closed.
9. Nameless save: a PUT /v1/sessions with no id updates the thread's bound document (for a resumed thread, the document it came from); only an unbound thread gets a new document named after its thread id.

Verification (local macOS, focused)

• 8 new HTTP tests with real engines built by ensure_engine_loaded, with only the model client scripted (runtime_api::tests::thread_snapshot_ownership). They cover:
  • a fresh thread (new file plus existing file, two writes in one turn)
  • depth=1 and chained undo
  • fork and fork-at-turn
  • eviction and restart
  • save, rebind and resume
  • cross-thread and TUI snapshots
  • file-revert from turn records
  • honest refusals: snapshots off, legacy seeded turn, pruned, untrusted
• Rewritten patch-undo and file-revert helper tests.
• Focused selection: 134 passed, 0 failed.
• fork/undo/sync_session/session_id/evict/snapshot/resume: 521 passed (1 ignored).
• core::engine, core::turn and protocol_parity: 633 passed.
• runtime_threads: 263 passed.
• codewhale-protocol: 90 passed.
• cargo fmt --check and clippy (tui and protocol, CI flags) are clean.
• The blocking-calls, dead-code, command-boundary and module-graph gates pass.
• Changelog sync/derive, check-versions, contributor credit, and web public-copy (6 passed) are all green.
• The full suite has not been run locally; it runs in CI.

Review follow-up (6cfe53b)

• Web client / red CI: turn.workspace_snapshot is registered in STREAM_EVENT_NAMES and applied to its turn's workspace_snapshots.
• Cross-thread attribution: the Runtime engine bounds every tool call that may write (not read-only: file tools, shell, programs, write-capable MCP) with tool and new post_tool snapshots. Each receipt records changed_paths since the turn's previous one, and a file tool's tool receipt records its declared write_paths. Patch-undo keeps a path only if it changed inside one of the turn's tool spans and, in a file tool's span, is a declared path. Anything else changed during the turn refuses with workspace_changed_since_turn. A span with no recorded changes fails closed with restore_point_unavailable.
• Unsnapshottable writes: a declared write (from receipts or turn items; failed or canceled calls excluded) to a path git check-ignore excludes, or to a path outside the workspace, gets 409 path_not_snapshotted.
• Pruning: prune_keep_last_n keeps the newest N snapshots plus the newest N pre-turn:/post-turn: boundaries, so a turn's own restore points survive a burst of more than 50 tool snapshots.
• Nameless save: see point 9 above.
• Blocking-call budget: raised by 2 path_canonicalize in runtime_api.rs. Both are in declared_write_path, which only runs inside patch_undo_workspace_files on spawn_blocking. They resolve absolute declared paths through symlinked roots.
• Verification (local, focused): 2037 passed, 0 failed, 8 ignored across snapshot, undo, session, fork, evict, resume, revert, protocol_parity, core::turn, core::engine, runtime_threads and turn_loop. That run includes the new HTTP tests: concurrent writer refused, a bash write undone, gitignored write refused, a turn over the snapshot cap still undoes, nameless save of a resumed thread. It also includes the new helper and prune tests. The web client test passes 37/37. Clippy (tui and protocol, CI flags) and fmt are clean. The lint gates pass, and the changelog pipeline is green. The full suite has not been run locally; it runs in CI.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[devin-ai-integration]

Devin Review found 3 potential issues.

[devin-ai-integration]

🔴 Parallel tool writes cannot be undone

When multi_tool_use.parallel writes files, bounded_tool never brackets its execution. The parallel-tool branch bypasses this path, so patch-undo treats those writes as foreign and refuses undo.

Learn more

The turn loop handles multi_tool_use.parallel before reaching the ordinary tool-call branch. Unlike ordinary write-capable calls, that branch takes no tool or post_tool restore point. attribute_window treats changes outside a bounded tool span as foreign, so a turn that writes through the parallel tool cannot pass patch-undo even when nobody else edited the workspace.

Example: A parallel call writes a.txt and b.txt. The only receipts are pre_turn and post_turn; patch-undo sees both changed paths outside a tool span and returns 409 workspace_changed_since_turn.

Recommended fix: Bound the MULTI_TOOL_PARALLEL_NAME execution branch with tool and post-tool restore points when recording receipts, including its cancellation path. Validate that its nested writes are attributed to the enclosing call.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔴 Multi-source undo can leave partial files

When different files need different source snapshots, restore_path_plan checks them out in separate commands. If a later checkout fails, earlier files stay reverted while patch-undo leaves the conversation unchanged.

(Refers to this code)

Learn more

Patch-undo builds one plan with each file's state before its first dropped turn. patch_undo_workspace_files calls this method once, but the method runs one checkout per distinct source tree. A failed later checkout leaves successful earlier checkouts applied despite the returned error. The safety snapshot retains the old files but does not automatically recover them.

Example: Turn one changes a.txt; turn two first changes b.txt. A depth-one undo checks out a.txt successfully, then the checkout for b.txt fails. The response is an error, a.txt is already rolled back, and both turns remain in the original thread.

Recommended fix: Make the multi-source restore atomic from the caller's perspective: stage all resulting files before mutation or automatically roll back every previously applied path from the mandatory safety snapshot on any checkout/removal failure. Test a failure on the second source.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔍 Defer changelog entries until merge

Both changelogs contain new PR entries. Contribution guidance reserves these edits for a batched commit on main to avoid merge conflicts.

---

Was this helpful? React with 👍 or 👎 to provide feedback.