feat(desktop, chat): per-turn changes card, turn snapshots and Undo (SUPER-2736)
Links
- Linear: SUPER-2736
- Walkthrough with screenshots: https://app.superset.sh/page/per-turn-changes-card-kca6uv
Summary
Under every settled chat turn that changed files, the ACP chat now shows what the turn changed. It is built in three layers, each a pair of commits, and each layer works on its own:
- Card from tool calls: "Edited N files +a −d" under the turn's last reply, outside the run fold. A row per file. Review opens the diff pane narrowed to the turn's files.
- Per-turn git snapshots: exact totals that include shell edits, a "This turn" diff scope, and a live "Changes · N files" pill above the composer while a turn runs.
- Undo (files only, the chat stays): restores the turn's files from its "before" snapshot. Every file is hash-checked first. Undo is refused when HEAD moved, when another chat in the worktree is working, or when the turn shared the worktree.
Snapshots are off by default. Layers 2 and 3 run only for people who turn on Track file changes per turn in Settings → Experimental. The row shows only with the acp-chat flag. With it off, the card comes from the tool calls, there is no live pill and no Undo, and no prompt waits.
Also includes: Codex's "this diff deletes its file" mark is now kept; PathActionsMenuItems moves up to the workspace components; openDiffPane takes a path filter and is reachable from chat.
How to review: commit by commit. After the three phases come the review fixes (7c342d1359 to 281dac8d71), the Experimental setting (45b45ace64), and the latest review fixes (da8d7b39df, see Testing).
Part 1: card from tool calls
Why
Today each edit is its own row inside a run that starts collapsed. Nothing totals a turn, and nothing opens a turn's diff.
What / How
transcriptRowsemits achanged_filesrow right under the last reply of each settled turn. It skips turns that have no file edits and no commands. The reply footer moves below the card.turnChangedFilesderives the list from the turn's completed tool calls:- one row per path, with created/deleted marks merged across calls;
- stats summed from each call's hunks, cached per diff object;
- the first changed line from
locationsplus the hunk's leading context.
- A reopened chat (bodies omitted) lists files from
locations, and the card asks for the bodies when it scrolls near. - Rows show a file icon and a dimmed folder that gives way before the name does. They also show new/deleted marks, aligned stat columns, and ↗ to open the file at its first change. Clicking a row opens the diff at that file. Right-click gives Open, Reveal in Finder, Copy Path and Copy Relative Path. Up to 7 rows, else 5 plus "Show N more files".
ChatPaneActions.openDiffreachesopenDiffPane, which now takes an optionalDiffPaneFilter; any caller that doesn't pass one clears it. The diff pane narrows to the filter's paths behind a chip that clears it.- Agent paths map to repo-relative ones, falling back to a case-insensitive match, because macOS lets one folder have two spellings.
Part 2: per-turn git snapshots
Why
Tool-call diffs miss shell edits and double-count repeated edits. Exact numbers need the worktree itself.
What / How
- This recovers the checkpoint module #8585 built and later removed, reshaped per turn.
- A prompt sent with
snapshotWorktree: truewaits for a snapshot before it goes to the agent (5 s cap). The snapshot is namedrefs/superset/chat-turns/<session>/<turn>/beforewhen the turn starts, and…/afteris taken when the turn settles or the chat closes mid-turn. A prompt without the field goes at once. - Snapshots go through a private
GIT_INDEX_FILEseeded from the real one (add -A,write-tree,commit-treewith HEAD as parent). The user's index, HEAD and branch are never written. Git work runs in the host worker pool. A kept snapshot index that git can no longer read is dropped and seeded again. getTurnChanges(new chat procedure) diffs before→after with numstat and name-status.- HEAD moved during the turn: files that changed only because of the move (a pull or rebase) are dropped. A file stays if it differed from HEAD in either snapshot, or appears in commits made while the turn ran.
- Turn still running:
livesnapshots the worktree now.
- When two chats work in one worktree at the same time, both turns are marked "shared".
- Every prompted turn reports its start and end to the host, with or without a snapshot, so this works when only one chat has snapshots on. Overlap counts from the snapshot before each prompt, or from the turn's start when it has none.
- A shared turn's card lists only the files this chat's tools touched; the rest go under "Also changed in this workspace".
- Review and rows open the diff pane on the turn's own commits (before→after) under a "This turn" chip.
- The live pill takes a fresh snapshot as tool calls finish, at most every 3 s.
Part 3: Undo
- Where: only the chat's newest card offers Undo, only while no turn runs, and only when the turn has snapshots and didn't share its worktree. It confirms in-app first ("Undo the file changes in this card?").
- What it restores: only files that still hold exactly the turn's result (same blob and mode, regular files) at a path whose folders are still plain folders. Everything else is left alone and listed.
- How: it removes files the turn created first, with the folders the turn made for them (an empty folder that was there before stays), then recreates the rest through
checkout-indexon a private index. A snapshot in the same worktree waits for an Undo there to finish. - Refusals and results: refusals are said inline (busy, HEAD moved, shared, missing, older host). An undone turn collapses to "File changes undone". The
undoneref holds the before snapshot plus the files Undo skipped, so a reopened chat still lists them ("Left alone, changed since this turn"). - Committed work: files committed since the turn drop off the card, and the card goes once all are. A broad
git:changedevent re-reads settled cards. - Resume: a chat resumed after a restart replays under new session and turn ids. Settled turns are also kept under
by-call/<agent session id>/<first tool call id>, which survive a resume, so old cards keep their snapshots and Undo.
Part 4: the Experimental setting
useChatTurnSnapshotsEnabled(persisted storechat-turn-snapshots, registered in the persisted-key registry) is true only when the switch is on and theacp-chatflag is on.- The desktop sends
snapshotWorktree: trueon each prompt and on an edited message (rewindSession) while it is on. The choice rides on each prompt, so it needs no host setting or migration and applies on the next prompt. - Released desktops, mobile and the CLI never send it, so they never snapshot and never wait. Prompts that an app update re-sends go without a snapshot.
- Turns that already have snapshots keep their full card when the switch is turned off.
Manual QA Checklist
Verified live in the dev app, in the ACP chat with Claude. The agent edited files inside an untracked scratch folder. Screenshots are on the walkthrough page.
Card and Review
- A turn that edited 4 files: mixed new and modified, aligned stats, header tooltip
- Review opens the diff pane narrowed to the turn's 4 files; a row click moves to that file
- ↗ opens the file at its first changed line; right-click menu; Copy Relative Path reaches the clipboard
- A ~230 px wide pane keeps the header and the Review button usable
Snapshots
- A file created and a file deleted by a shell command both appear, with exact totals
- "This turn" diff shows exactly the turn's before→after
- The live pill mid-turn goes 1 → 3 → 4 files and disappears when the turn settles
- After an Electron restart resumes the chat under new ids, the card still finds its snapshots
Undo
- Undo restores 3 files, leaves one I edited after the turn alone, and names it
- Undo is refused after HEAD moved
- Undo re-checked live after the earlier review fixes (at
58a8a63b54)
Experimental setting
- The "Track file changes per turn" row shows, off by default, with the
acp-chatflag - The row is hidden when the
acp-chatflag is off
Not verified live
- The round-4 fixes in
da8d7b39df: tests only. The dev app reloads with them and shows its cards. - Two chats in one worktree at once (shared split and refusal): tests only
- Codex harness: tests only; live runs used Claude
- Packaged build
Testing
- Typecheck:
apps/desktop,packages/chat-runtime,packages/host-serviceexit 0.packages/chatexits 1 locally only on TS1149/TS1261: one file reached under two path spellings (worktrees/Supersetvssuperset), an artifact of this macOS checkout. bun testatda8d7b39df:- desktop ChatSession, ChatPane, settings and stores: 760
packages/chat-runtime: 413packages/chat: 103packages/host-servicesrc/chat-v3+src/workers/tasks: 78
- Host tests run on small temp repos: exact files including shell edits, index untouched; HEAD-move filter; shared overlap, also against a turn without a snapshot; resume lookup; Undo restore and skip, and the skipped list read back later; file/folder swaps; folders removed only when the turn made them; a
:-named file; same-second edits; symlinked root; commit clears; shared refusal; an unreadable snapshot index rebuilt. bun run check:i18n: every new string translated in all locales.biome checkon touched files.- Independent reviews: the first found 9 defects, two of them Undo deleting user files, fixed in
7c342d1359. A/code-reviewon 2026-10-29 found 14;da8d7b39dffixes 8 of them. The rest are listed under Known Limitations. New tests for the shared-turn, steer, rejected-prompt, folder and index fixes fail on the old code. The partial-Undo record is new, so its tests were not run against the old code. The flag change has no test. - CI green on
da8d7b39df.
Compatibility
getTurnChangesandundoTurnFilesare new, additive procedures on the host's chat router. Desktop treats a missing procedure as "unsupported" and keeps the tool-call card, so this desktop works against older (for example cloud) hosts.- Protocol additions are optional fields only:
deletedon diff content;liveandanchorItemIdson the new inputs;snapshotWorktreeon the prompt and rewind inputs;undoSkippedon thegetTurnChangesoutput.
Known Limitations
- Snapshot refs and commits are never pruned (
refs/superset/chat-turns/*). They show ingit log --alland keep snapshot objects alive; this needs a retention rule. - With snapshots on, every prompt waits for its snapshot: about 0.45 s on this 14k-file repo and on a 100k-file repo, 2.3–4.5 s on a 300k-file repo. A 500 MB untracked file that is not ignored makes every snapshot time out (5 s before the prompt, 30 s after the turn) and leaves temporary objects in
.git. That is why the setting is off by default. - The 5 s cap also counts time spent queued behind the previous turn's "after" snapshot, which has no cap of its own.
- Untracked, non-ignored files are captured into snapshot objects, as
git add -Awould. - Turns the agent starts on its own, with no prompt, are not reported for shared detection.
- Cards and the live pill still ask the host for changes when the setting is off. Each request is cheap, but it waits in the worktree's snapshot queue.
- Undo is not atomic: a failure partway can leave some files restored and the turn not marked undone.
- Only the newest card offers Undo. After undoing it, older cards do not become undoable.
- Turns without snapshots keep the tool-call card. Its counts are estimates: a file edited twice can count a line twice, and a reopened chat can show slightly different counts once tool bodies load.
- The diff pane's filter paths persist in the pane layout. That is bounded to one filter per diff pane.
Rollout
- The Experimental setting is off for everyone. Turning it on is per app install.
- Before widening it, leave out large untracked files, stop snapshotting a worktree after a timeout, and give the "after" snapshot a time limit.
Rollback
- Turn the setting off to stop snapshots and Undo. Revert the PR to remove the card.
- The refs left behind are inert. They can be removed with:
git for-each-ref --format='%(refname)' refs/superset/chat-turns/ | xargs -n1 git update-ref -d
Summary by cubic
Under every settled chat turn that changed files, the ACP chat now shows what the turn changed: an "Edited N files" card, a "This turn" diff scope, and a live "Changes · N files" pill while the turn runs. Snapshots and Undo are gated behind the new "Track file changes per turn" experimental setting (Settings > Experimental), which shows with the acp-chat flag; with it off, the card falls back to the tool-call list and no live pill or Undo is shown.
Turn changes
- The card is built from the turn's tool calls and, when the setting is on, from per-turn git snapshots that capture shell edits without double-counting.
- Review and each file row open the diff pane narrowed to the turn's files and commits.
- Snapshots run one at a time per worktree, never touch the user's index, HEAD, or branch, and never drop a prompt waiting on its snapshot; a prompt the agent rejects is discarded with an error notice instead of killing the session.
- Turn overlap is reported for every prompted turn, snapshotted or not, and a shared turn lists only this chat's tool files; a shell-only shared turn keeps its card without Undo.
- Snapshots and Undo drop inherited
GIT_DIRand related env vars, an unreadable snapshot index is rebuilt, large turns review by commit range instead of per-path filter, and the card header adapts to a narrow pane.
Undo
- The newest card restores the turn's files from its "before" snapshot, hash-checking each file first, unstaging what the turn staged, and leaving files changed since alone.
- A partial Undo keeps the skipped files visible after a reload, and folders are removed only when the turn created them; the turn is marked undone only when at least one file was restored.
- Undo is refused when HEAD moved, another chat in the worktree is working, or the turn shared its worktree.
Summary by CodeRabbit
- New Features
- View files changed during a chat turn, including change types and addition/deletion counts, and open those changes for review.
- Expand or collapse file lists and distinguish turn-related changes from other workspace changes.
- Undo eligible file changes from the latest turn, with confirmation and clear results for restored or skipped files.
- Filter the diff pane to a turn’s files or changes, and clear the filter to return to the full view.
- See live change summaries while a turn is in progress.
- Bug Fixes
- Deleted files are now correctly identified in change summaries.