feat: go back a turn — take back messages on any backend, optionally restoring the files (#355)

[saucam]

Closes #355 · Builds on #361 (#354, merged).

What this does

You can now take back a message, or go back to any earlier point in a session, on any backend.
The agent forgets what was taken back, and the message comes back to your input box to edit and resend.
Optionally, the files go back too, to exactly how they were when that message was sent.

• Where:
  • Web: an "↩ go back to here" action on each of your messages, an "↩ undo" control in the session bar, and a dialog that previews what will happen before anything does.
  • TUI and codeoid attach: /undo takes back the last message; /undo files previews restoring the files; /undo files yes does it.
  • CLI: codeoid undo <session> [files [yes|force]].
• Every backend, after a restart too. The cut happens in codeoid's own copy of the conversation. The backend is then reset and re-seeded with what's kept, the same way a backend switch works. Nothing depends on a backend's own session format.
• Files are opt-in and careful:
  • What changes: files the agent changed or deleted get their old content back, and files created since are removed. Ignored files (build output, dependencies) and secret files are never touched.
  • Your own edits: if you edited a file by hand since the agent's last turn, going back reports it and refuses to overwrite it unless you confirm.
• Honest about limits. The preview lists what going back can't undo: external tool calls (MCP), and shell commands whose effects live outside the working directory, such as git push, gh, curl, installs or deployments.
• A running turn is stopped first, along with background agents. Messages you send after going back are not affected.
• Permissions:
  • Going back needs send rights.
  • The preview also needs read access.
  • Restoring files needs approve rights, because it writes outside the approval gate.
  • Stopping a busy session needs interrupt rights.
• Confirm does exactly what was previewed. If anything changed in between, it refuses and shows the fresh preview.
• Records. What was taken back is hidden from the session view (live, after a restart, when paging, and in forks) but kept on disk. A visible "↩ Went back to before …" notice marks the spot, and the action is audit-logged.

How it was checked

Live, against a real daemon with the real Claude backend (scratch git repo):

Step	Result
Turn 1: "My codename is PELICAN. Create hello.txt = one". Turn 2: "Correction: codename is now FALCON. Append two, create notes.md".	Files: hello.txt = one/two, notes.md exists.
Dry run of going back to turn 2 with files	Would restore hello.txt, remove notes.md, no conflicts. Nothing changed.
Go back to turn 2 with files	hello.txt = one, notes.md gone, the turn-2 prompt returned.
"Without tools: what is my codename?"	PELICAN. FALCON was forgotten.
Edit hello.txt by hand, then codeoid undo <s> files and files yes	Preview flags hello.txt (edited by you since). files yes refuses; the hand edit survives.
codeoid undo <s> (conversation only)	The last message is taken back and printed for resending.
Restart the daemon	The turn list and both "went back" notices persist, and the taken-back rows stay hidden.

Repeated after both audit rounds. Two undos in a row, after taking everything back: "No, you haven't told me a codename". The agent forgets on a real backend.

Tests: typecheck, lint and build pass, plus 2,886 daemon tests and 585 web tests. Each guard added during the audits was mutation-checked: removing it makes a test fail.

• New daemon tests: rewind.test.ts (30) covers:
  • the conversation cut, client views, restarts, forks and permissions;
  • a running turn, a pending approval, background reports, and a message sent during a rewind;
  • file restore: hand edits after the last turn and between removed turns, fail-closed when a snapshot is missing, ignored files, symlinked parents, a preview/confirm mismatch, and non-git folders;
  • the agent forgetting after two undos, and after a restart.
  • Also terminal-rewind.test.ts (5) and CLI replay tests.
• New web tests: RewindModal.test.tsx (6) and two MessageRow tests.

Audits: two rounds, each with a correctness reviewer and a security reviewer. All findings were fixed here. The ones that shaped the design:

• Restore: it's a single git operation that refuses rather than half-restores. It never deletes a file that was ignored when the snapshot was taken.
• Hand edits: they're checked across every taken-back turn and fail closed.
• Permissions: the scopes are listed above.
• The agent really forgets: every backend drops its queued history on reset. Background reports from removed turns don't wake the agent, and a restart before the next message re-seeds the kept history.

🤖 Implementation context (for agents / maintainers)

Protocol (packages/protocol/src/turns.ts)

• session.rewind { sessionId, turnId, restoreFiles?, dryRun?, force? } returns session.rewind.result { removedTurns, restoredPrompt, files?: { restore, remove, conflicts, late?, applied }, filesUnavailable?, irreversible, refused?, dryRun }. Scope: session:send + ownership. Refused for conductor/role sessions.

Daemon (src/daemon/session.ts)

• rewind(): dry runs go straight to #planRewind. Real runs serialize on the send chain via #rewindInner.
• #rewindInner takes these steps in order:
  1. Interrupt the running turn, any send still preparing, and background work.
  2. Plan.
  3. Refuse on conflicts unless force.
  4. restoreTree.
  5. #teardownProvider + accumulator.seed(kept).
  6. Trim the turn index, then resetToNewSession (new backing id) + #seedProviderFromHistory.
  7. Append a marker row {event: "session.rewound", turnId, removedTurnIds, fromMessageId}.
  8. Rebuild the scrollback via applyRewinds, rotate #resumeKey, #replay a snapshot to every client, and audit.
• End-of-turn snapshots (<turnId>-end, #snapshotTurnEnd on idle/error). Snapshots are serialized through #checkpointChain so a start snapshot waits on the previous end.
• irreversibleEffects() covers MCP tool calls and run_shell commands matching an outside-effect pattern.

Checkpoints (src/daemon/checkpoints.ts)

• currentTree stages the work tree, without a ref.
• diffTrees is diff-tree -r -z --name-status.
• restoreTree:
  • Path checks first: every path must resolve inside the workdir's realpath through no symlinked parent.
  • Created since: removed.
  • Changed or deleted since: written back with git checkout <sha> --pathspec-from-file under GIT_LITERAL_PATHSPECS.

Transcript (src/daemon/transcript.ts)

• applyRewinds runs inside loadTranscript. It cuts positionally from fromMessageId to the marker, and falls back to dropping rows stamped with removedTurnIds. That covers resume, fork priming and paging.

Clients

• Web: components/RewindModal.tsx. The taken-back prompt goes back to the draft via a codeoid:prompt-draft-changed event that PromptBox listens for. MessageRow gets the "go back to here" action and SessionControls the UndoButton.
• TUI: /undo in App.tsx, plus ws turns / rewind.
• CLI: /undo in attach (prefills via rl.write) and codeoid undo. Shared grammar and wording in src/terminal/rewind.ts.

Known limits

• Memory episodes already indexed for the taken-back turns stay in memory search.
• Usage totals are not rolled back.
• Git commits made by the agent are listed as irreversible, not reverted.

🤖 Generated with Claude Code