@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/{extensions/question/README.md → docs/extensions/question.md}

@@ -4,37 +4,48 @@ A single model-facing tool, `ask_user_question`, that lets the model ask the
 human one or more structured questions mid-turn and wait for typed answers.
 Modelled on Claude Code's `AskUserQuestion`.
 
-<img src="../../assets/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%">
+<img src="../../assets/screens/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%">
 
-```
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Mid-turn asking | `ask_user_question` | The model asks 1–4 questions and the turn waits until you answer or cancel. | Shipped |
+| Labelled options | `questions[].options` | Each question offers up to four choices, each with an optional second line describing it. | Shipped |
+| Free-form answers | the automatic `Other (type something)` row, `questions[].options` omitted | You can type an answer the options do not cover, and a question with no options asks for plain text. | Shipped |
+| Multiple selections | `questions[].multiSelect` | `Space` toggles options and `Enter` confirms the set. | Shipped |
+| Batched questions | `questions[]` | Up to four questions ride in one call and are answered in one pass. | Shipped |
+| Submit gating | the `Submit` tab | Submit refuses until every question is answered and names the missing ones; a single question submits on `Enter` without a Submit tab. | Shipped |
+| Tab headers | `questions[].header` | Each question gets a short tab label, defaulted to `Q{n}` and clipped to 12 columns. | Shipped |
+| Language-aware batch | `dialogUI.language` | A remote turn in Chinese gets the batch prompt, retry text, and format line in Chinese. | Shipped |
+| Dialog fallback | `select`, `input`, `editor` | RPC and remote turns answer the same questions without the TUI screen. | Shipped |
+| No-UI degradation | `print`, `json` | The tool returns `unavailable` with an error instead of hanging when no dialog channel exists. | Shipped |
+| Cancelling | `Esc` | The model is told you cancelled and can continue or ask in prose. | Shipped |
+| Branch-scoped answers | tool-result `details` | The answers stay with the transcript, so `/resume` and `/tree` show the same history. | Shipped |
+
+## Quickstart
+
+```bash
 pi --extension ./extensions/question   # load just this extension
 pi -e .                                # load the whole @gavin-hu/my-pi-agent package
 pi install ./                          # install the package
 ```
 
-## Tool rendering
+The tool is declared in every session and activated where a UI exists, so ask
+the model for a decision and the questionnaire takes the screen.
 
-How the `ask_user_question` call and its result look in the transcript — the call line as a headline and the body indented under it:
+## Tool
 
 <img src="../../assets/tools/ask_user_question.png" alt="The ask_user_question tool's call and result: the call line and an indented body with the question headers, the options, and the answers" width="100%">
 
-## What it does
-
 The model calls `ask_user_question` with 1–4 questions. Each question offers up
 to four labelled options (plus an automatic **“Other (type something)”** free-form
 entry); a question with no options asks for free-form text. The tool blocks until
 the user answers or cancels, then returns the answers as text the model can act
 on.
 
-- Multiple questions: a tab bar, per-question answered indicators, and a Submit
-  tab that refuses to submit until every question is answered.
-- `multiSelect: true`: `Space` toggles options, `Enter` confirms the set. On the
-  `Other` row `Space` opens the editor, like `Enter`.
-- `Esc` cancels; the model receives “User cancelled the question.” and can
-  continue or ask in prose.
-
-## Tool
-
 | | |
 |---|---|
 | Name | `ask_user_question` |
@@ -87,22 +98,37 @@ ask_user_question 2 questions (Auth, Scope)
 ✓ Format: (wrote) json for logs
 ```
 
+### The questionnaire
+
+- Multiple questions: a tab bar, per-question answered indicators, and a Submit
+  tab that refuses to submit until every question is answered.
+- `multiSelect: true`: `Space` toggles options, `Enter` confirms the set. On the
+  `Other` row `Space` opens the editor, like `Enter`.
+- `Esc` cancels; the model receives “User cancelled the question.” and can
+  continue or ask in prose.
+
 ## Behaviour by mode
 
-| Mode | Behavior |
+| Mode | Behaviour |
 |---|---|
 | Interactive TUI (local turn) | Full tabbed questionnaire with descriptions, multi-select, and an inline editor |
 | RPC (`hasUI`) | Forwarded dialogs: `select` per question, `input` for “Other”/free-form, `editor` for multi-select |
 | Remote turn (WeChat) | Same forwarded dialogs, routed to the remote channel by the `ctx.ui` adapter; the full-screen component is skipped |
 | `print` / `json` | The tool is registered inactive (`defaultActive: false`) and never switched on; if invoked anyway it returns a clear error telling the model to ask in prose |
 
+On a dialog-only host, two or more questions become one batch editor prompt and
+one reply (`1: 2; 2: A, B`), with one retry if the format is unclear; the TUI
+keeps its tabbed screen.
+
 Whether a turn uses the rich component or dialogs is decided by
-`askHuman(ctx, { custom, dialogs })` from `lib/interaction.ts`, not by reading
-`ctx.mode`; a remote-answered turn reports no custom-UI support.
+`askHuman(ctx, { custom, dialogs })` from
+[`lib/interaction.ts`](../../lib/interaction.ts), not by reading `ctx.mode`; a
+remote-answered turn reports no custom-UI support.
 
 ## Configuration
 
-None in v1 — the tool is either available (a UI exists) or not.
+None. There are no keys: the tool is available exactly when the session has a
+UI.
 
 ## Limitations
 
@@ -170,7 +196,7 @@ None in v1 — the tool is either available (a UI exists) or not.
 - **Transcript rendering is driven by `details`.** `renderCall` summarises the
   question count and headers and lists one option line per question;
   `renderResult` renders `✓ Auth: 1. OAuth` per answer, `(wrote)` for custom
-  text, warning-colored `Cancelled`, and error-colored `No UI` when unavailable
+  text, warning-coloured `Cancelled`, and error-coloured `No UI` when unavailable
   (matching the result rail its `isError` draws). The call
   summary reads the call's *streaming* args, so a field that has not arrived yet
   — a question `header`, an option `label` — reads as absent instead of
@@ -181,14 +207,14 @@ None in v1 — the tool is either available (a UI exists) or not.
 
 | File | Responsibility |
 |---|---|
-| `index.ts` | Extension factory: register the tool, gate it by UI availability |
-| `schema.ts` | TypeBox parameters, validation, defaulting (pure) |
-| `types.ts` | Shared raw/normalized types |
-| `answers.ts` | Answer normalization and model-facing formatting (pure) |
-| `tui-state.ts` | Pure keyboard/navigation state machine |
-| `tui.ts` | Custom terminal component (render + input), drawn from the `lib/tui/` kit (`titleRule`/`plainRule`, `checkbox`, `flowCells`, `screenHint`, `editorTheme`). |
-| `dialogs.ts` | `select`/`input`/`editor` fallback driver |
-| `tools.ts` | Tool registration and transcript renderers |
+| [`index.ts`](../../extensions/question/index.ts) | Extension factory: register the tool, gate it by UI availability |
+| [`schema.ts`](../../extensions/question/schema.ts) | TypeBox parameters, validation, defaulting (pure) |
+| [`types.ts`](../../extensions/question/types.ts) | Shared raw/normalized types |
+| [`answers.ts`](../../extensions/question/answers.ts) | Answer normalization and model-facing formatting (pure) |
+| [`tui-state.ts`](../../extensions/question/tui-state.ts) | Pure keyboard/navigation state machine |
+| [`tui.ts`](../../extensions/question/tui.ts) | Custom terminal component (render + input), drawn from the `lib/tui/` kit (`titleRule`/`plainRule`, `checkbox`, `flowCells`, `screenHint`, `editorTheme`). |
+| [`dialogs.ts`](../../extensions/question/dialogs.ts) | `select`/`input`/`editor` fallback driver |
+| [`tools.ts`](../../extensions/question/tools.ts) | Tool registration and transcript renderers |
 
 ## Testing
 

package/{extensions/rewind/README.md → docs/extensions/rewind.md}

@@ -2,92 +2,93 @@
 
 Snapshot the working tree at the start of each task and return to an earlier
 prompt from a menu — restoring the **code**, the **conversation**, or **both**.
-`/review` uses the same snapshot to show the latest turn's changes and revert one
-file or the whole turn. A snapshot is a git commit kept under
-`refs/pi/rewind/<id>`; restoring one rewrites the working tree **without
-touching the real index or moving HEAD**, so commits, branches, staged state, and
-the reflog are untouched. Conversation rewind uses Pi's session tree, so the
-branch you leave is not erased.
-
-This is the `rewind` extension entrypoint; it is one of two sibling git
-extensions in this package (`worktree` is the other).
-
-<img src="../../assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%">
-
-<img src="../../assets/review.png" alt="The /review screen: changed files with M, A, and D marks, line counts, and the focused file's detail" width="100%">
-
-```
-pi --extension ./extensions/rewind   # load this extension alone
+Snapshots are git commits under `refs/pi/rewind/<id>`, so restoring one rewrites
+the working tree without touching the real index or moving HEAD, and a
+conversation rewind moves Pi's session tree without erasing the branch you leave.
+`/review` uses the same snapshot to show the latest turn's changes and revert a
+file, a selection, or the whole turn.
+
+<img src="../../assets/screens/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and a detail line naming the snapshot the focused prompt holds" width="100%">
+
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Automatic snapshots | the `autoSnapshots` key | One snapshot per prompt, taken before its first mutating call, so every task has a restore point. | Shipped |
+| Durable snapshots | `refNamespace` | Snapshots survive the session and are listed from git rather than from session state. | Shipped |
+| Prompt timeline | `/rewind` | Every user prompt on the active branch, newest first, marked `⬥` where a code snapshot was captured. | Shipped |
+| Scoped restore | `/rewind` | Code, conversation, or both, from the prompt you pick. | Shipped |
+| Undoable restore | the `safetySnapshot` key | A code restore snapshots the state it replaces first, so it can itself be undone. | Shipped |
+| Partial restore | `/rewind` | The changed paths grouped by directory, chosen with a checklist, and previewed as the subset you selected. | Shipped |
+| Latest-turn review | `/review` | The changed files of the latest prompt, with `M`/`A`/`D`/`R` marks and line counts. | Shipped |
+| File, batch, and hunk revert | `/review` | Revert one file, a selection, the whole turn, or chosen hunks, each with its own safety snapshot. | Shipped |
+| Busy-git refusal | `/rewind`, `/review` | A merge, rebase, cherry-pick, revert, or bisect in progress refuses the restore instead of fighting it. | Shipped |
+| Root-scoped snapshots | `refs/pi/rewind` | Worktrees share the ref store, while another root's snapshot is filtered out and refused. | Shipped |
+| Untracked capture | `autoSnapshots` | Non-ignored untracked files are captured, and a restore removes the ones that appeared after the snapshot. | Shipped |
+| Ref cap and auto-prune | `max`, `autoPrune` | The snapshot store is bounded and pruned instead of growing without limit. | Shipped |
+| Review plan guard | `/review` in plan mode | Review refuses while plan mode is on, matching the read-only planning rule. | Shipped |
+| Prompt-count chip | `↺ N`, the `showStatus` key | The status bar counts the prompts on the active branch, whether or not each has a snapshot. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/rewind   # load just this extension
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package
 pi install ./                        # install the package
 ```
 
-## What it does
-
-- Takes **one automatic snapshot per user prompt**, before the prompt's first
-  mutating tool call. A read-only prompt snapshots nothing.
-- `/review` compares the working tree with the snapshot taken before the latest
-  prompt on the active branch. The file list carries `M`/`A`/`D`/`R` and line
-  counts; `Enter` opens a scrollable patch, `Space` selects files, `r` reverts
-  the selection (or the focused file when nothing is selected), and `R` reverts
-  every changed path. A modified text file's diff offers `h`, which opens a hunk
-  checklist; the chosen hunks revert as one reverse patch with its own
-  pre-restore safety snapshot. A rename is one `R` row, so reverting it restores
-  the old path and removes the new one together. A selected batch is one restore
-  and one pre-restore safety snapshot, not one per file. When the working tree
-  matches HEAD, the screen says the changes are already committed and a revert
-  leaves the commits in place.
-- `/rewind` lists **every user prompt on the active branch** (newest first), each
-  marked `⬥` when a code snapshot was captured for it.
-- Picking a point asks what to restore: **Code and conversation**,
-  **Conversation only**, or **Code only**.
-  - *Code* rewrites the working tree to the snapshot and is itself undoable
-    (a `pre-restore` safety snapshot is taken first).
-  - When code moves, a second step asks **Restore what?** — **Everything (N
-    files)** or **Choose paths…**. The checklist lists every changed path
-    grouped by directory (`M` modified, `D` deleted since the snapshot, `A`
-    created after it, `R` renamed), with all of them selected, so `Enter` twice
-    reproduces a whole-tree restore. `Space` toggles a file or a directory,
-    `a`/`n` select all/none, and the confirm that follows previews only the
-    chosen subset.
-  - *Conversation* moves the session tree back to that prompt and puts the
-    prompt text back in the editor; the abandoned branch stays in the session.
-- Shows a `↺ N` status chip counting the prompts on the active branch — the
-  same points `/rewind` lists (its list size), whether or not each has a code
-  snapshot.
-- Stores metadata in the commit body, so snapshots survive across sessions and
-  are listed from git rather than from session state.
+```text
+/rewind                             # pick a prompt, then a scope, then the paths
+/review                             # the latest turn's changes, ready to revert
+```
 
-Snapshots include tracked files plus (by default) untracked, non-ignored files.
-`.gitignore`d files are never captured. Because refs live in the shared git
-directory, a snapshot taken inside a [`worktree`](../worktree/) is visible from
-the main checkout; `list`/matching filter to the current root by default.
+Nothing is registered for the model: snapshots are taken automatically, and both
+commands are user-driven.
 
-## Command
+## Commands
 
 | Command | What it does |
 |---|---|
 | `/rewind` | Open the timeline; pick a prompt, then a restore scope, then (for code) the paths. |
 | `/review` | Review the latest prompt's changes; open a diff, select files with `Space`, revert the selection or all files, or revert chosen hunks with `h`. |
 
-The path checklist is its own `ctx.ui.custom` screen: `Space` toggles the focused
-row, `a`/`n` select all or none, `Enter` returns the selection, and `Esc` cancels
-the rewind.
+The timeline is keyboard-driven: `↑`/`↓` or `j`/`k` move,
+`PgUp`/`PgDn`/`Home`/`End` jump, `Enter` chooses the focused prompt, the mouse
+wheel scrolls, and `Esc` closes. The scope choice and the confirmation (with a
+diff preview) run after the screen closes. Picking a point asks what to restore:
+**Code and conversation**, **Conversation only**, or **Code only**. A conversation
+rewind moves the session tree back to that prompt and puts the prompt text back in
+the editor; the abandoned branch stays in the session.
+
+When code moves and more than one path changed, a second step asks **Restore
+what?** — **Everything (N files)** or **Choose paths…**. The path checklist is
+its own `ctx.ui.custom` screen: it lists every changed path grouped by directory
+(`M` modified, `D` deleted since the snapshot, `A` created after it, `R`
+renamed), with all of them selected, so `Enter` twice reproduces a whole-tree
+restore. `Space` toggles a file or a directory, `a`/`n` select all or none, and
+`Enter` returns the selection. The confirm that follows previews only the chosen
+subset.
+
+<img src="../../assets/screens/review.png" alt="The /review screen: changed files with M, A, and D marks, line counts, and the focused file's detail" width="100%">
+
+`/review` compares the working tree with the snapshot taken before the latest
+prompt on the active branch. The list is keyboard-driven too: `↑`/`↓` or `j`/`k`
+move, `PgUp`/`PgDn` and `Home`/`End` jump, `Space` toggles the focused file,
+`a`/`n` select all or none, `Enter` opens the focused file's diff, `r` reverts the
+selection (or the focused file when nothing is selected), `R` reverts every
+changed path, and `Esc` closes. A selected batch is one restore and one
+pre-restore safety snapshot, not one per file. A rename is one `R` row, so
+reverting it restores the old path and removes the new one together.
 
-The timeline is keyboard-driven: `↑`/`↓` or `j`/`k` move, `PgUp`/`PgDn`/`Home`/`End`
-jump, `Enter` chooses the focused prompt, the mouse wheel scrolls, `Esc` closes.
-The scope choice and the confirmation (with a diff preview) run after the screen
-closes. The path checklist is the same grammar: `Space` toggles, `a`/`n` select
-all or none, `Enter` restores the selection, `Esc` cancels the rewind.
-
-The review list is keyboard-driven too: `↑`/`↓` or `j`/`k` move, `PgUp`/`PgDn` and
-`Home`/`End` jump, `Space` toggles the focused file, `a`/`n` select all or none,
-`Enter` opens the focused file's diff, `r` reverts the selection (or the focused
-file when nothing is selected), `R` reverts every changed path, and `Esc` closes.
 In the diff, `j`/`k`, the arrows, `PgUp`/`PgDn`, and `g`/`G` scroll, `r` reverts
 the file, and `Esc` goes back. A modified text file's diff offers `h` for the
 hunk checklist: `Space` toggles, `a`/`n` select all or none, `Enter` reverts the
-chosen hunks, and `Esc` cancels back to the diff.
+chosen hunks, and `Esc` cancels back to the diff. The chosen hunks revert as one
+reverse patch with its own pre-restore safety snapshot. When the working tree
+matches HEAD, the screen says the changes are already committed and a revert
+leaves the commits in place.
 
 ## Behaviour by mode
 
@@ -99,40 +100,32 @@ chosen hunks, and `Esc` cancels back to the diff.
 
 ## Configuration
 
-The `rewind` section of the shared `bytefly.json` (global document, then
-`<root>/.pi/bytefly.json`, project wins).
-
-```json
-// bytefly.json → "rewind"
-{
-  "autoSnapshots": true,
-  "max": 20,
-  "includeUntracked": true,
-  "safetySnapshot": true,
-  "autoPrune": true,
-  "showStatus": true,
-  "watch": [],
-  "ignore": [],
-  "refNamespace": "refs/pi/rewind"
-}
-```
-
-| Key | Meaning |
-|---|---|
-| `autoSnapshots` | Take one automatic snapshot per prompt. Default `true`. |
-| `max` | Snapshot refs kept per root; automatic and pre-restore safety snapshots both count. |
-| `includeUntracked` | Capture untracked, non-ignored files. |
-| `safetySnapshot` | Save the current state before a code restore. |
-| `autoPrune` | Delete the oldest refs beyond `max` after an automatic snapshot. |
-| `showStatus` | Draw the `↺ N` status chip. |
-| `watch` | Extra tool names to treat as mutating. |
-| `ignore` | Tool names never to snapshot; this package's own tools are always excluded. |
-| `refNamespace` | Ref namespace for stored snapshots. |
+The `rewind` section of the shared `bytefly.json`; resolution rules are in
+[`../configuration.md`](../configuration.md#rewind--snapshots).
+
+| Key | Default | Meaning |
+|---|---|---|
+| `autoSnapshots` | `true` | Take one automatic snapshot per prompt. |
+| `max` | `20` | Snapshot refs kept per root; automatic and pre-restore safety snapshots both count. |
+| `includeUntracked` | `true` | Capture untracked, non-ignored files. |
+| `safetySnapshot` | `true` | Save the current state before a code restore. |
+| `autoPrune` | `true` | Delete the oldest refs beyond `max` after an automatic snapshot. |
+| `showStatus` | `true` | Draw the `↺ N` status chip. |
+| `watch` | `[]` | Extra tool names to treat as mutating. |
+| `ignore` | `[]` | Tool names never to snapshot; this package's own tools are always excluded. |
+| `refNamespace` | `"refs/pi/rewind"` | Ref namespace for stored snapshots. |
 
 A restore's safety snapshot is not pruned immediately, so the snapshot it
 restored from stays available for a follow-up restore; the next automatic
 snapshot applies the cap.
 
+## What a snapshot captures
+
+Snapshots include tracked files plus (by default) untracked, non-ignored files.
+`.gitignore`d files are never captured. Because refs live in the shared git
+directory, a snapshot taken inside a [`worktree`](./worktree.md) is visible from
+the main checkout; `list`/matching filter to the current root by default.
+
 ## How snapshots are stored
 
 Each snapshot is a commit under `refs/pi/rewind/<id>` whose body carries a
@@ -272,26 +265,26 @@ commit. These refs are not branches and are not touched by `git push --all`.
 |---|---|
 | `index.ts` | Registrar: wire the runtime, the commands, and the run-state module to Pi's events (`registerRewind`). |
 | `types.ts` | `Snapshot`, `SnapshotReason`, `RestoreSummary`. |
-| `config.ts` | Config defaults and merge/normalize over `lib/config.ts`. |
-| `git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes (name status, stat, patch, and `--numstat`), the reverse apply a hunk revert uses, and the production `RunGit`. |
-| `snapshot.ts` | Create a snapshot (tree from a temporary index → commit → ref). |
-| `snapshot-run.ts` | Per-run automatic-snapshot state: one snapshot per prompt, with a synchronous guard. |
-| `restore.ts` | Plan and apply a working-tree rewind, whole or for a chosen subset of paths, recreating a rename's source and removing its destination. |
-| `paths.ts` | Pure: the changed-path list from `git diff --name-status` (a rename is one paired entry), its directory grouping, the change marks, the `--numstat` counts, and the restore counts. |
-| `checklist.ts` | The shared multi-select checklist screen: the cursor, `Space`/`a`/`n`/`Enter`, the height math, and the dock frame. The three checklists below supply only their rows and their words. |
-| `path-picker.ts` | The partial restore's checklist, a `ChecklistScreen` over grouped paths: directory toggles, the change marks, and the selection it returns. |
-| `patch.ts` | Pure: split a single-file unified diff into its header and hunks, and rebuild a patch from chosen hunks. |
-| `hunk-picker.ts` | The hunk checklist a modified file's diff opens, a `ChecklistScreen` over the hunks: previews, the indices it returns, and its own row budget. |
-| `store.ts` | Versioned metadata encoding and ref-backed listing/pruning. |
-| `policy.ts` | Which tool calls are worth a snapshot. |
-| `temp-index.ts` | Per-process `GIT_INDEX_FILE` paths: create, release, and sweep stale files. |
-| `status.ts` | The `↺ N` status chip. |
-| `queue.ts` | The serialized git operation queue for staging calls (`GIT_INDEX_FILE`). |
-| `runtime.ts` | Root/config caches and the snapshot/list/plan/patch/numstat/restore/hunk-revert operations. |
-| `timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
-| `rewind.ts` | Scope choice, the path step, confirmation, and applying code + conversation rewind. |
-| `review.ts` | The `/review` orchestration: the latest snapshot, the list/diff loop, the hunk step, confirmations, and the reverts. |
-| `review-tui.ts` | The changed-file list (a `ChecklistScreen`) and the scrollable per-file diff, which offers the hunk checklist. |
-| `rewind-tui.ts` | The selectable, width-safe timeline component, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
-| `commands.ts` | The `/rewind` and `/review` commands. |
-| `format.ts` | Pure rewind and review text, including diff bounding and the hunk prompt. |
+| `config/config.ts` | Config defaults and merge/normalize over `lib/config.ts`. |
+| `transport/git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes (name status, stat, patch, and `--numstat`), the reverse apply a hunk revert uses, and the production `RunGit`. |
+| `transport/snapshot.ts` | Create a snapshot (tree from a temporary index → commit → ref). |
+| `state/snapshot-run.ts` | Per-run automatic-snapshot state: one snapshot per prompt, with a synchronous guard. |
+| `transport/restore.ts` | Plan and apply a working-tree rewind, whole or for a chosen subset of paths, recreating a rename's source and removing its destination. |
+| `text/paths.ts` | Pure: the changed-path list from `git diff --name-status` (a rename is one paired entry), its directory grouping, the change marks, the `--numstat` counts, and the restore counts. |
+| `view/checklist.ts` | The shared multi-select checklist screen: the cursor, `Space`/`a`/`n`/`Enter`, the height math, and the dock frame. The three checklists below supply only their rows and their words. |
+| `view/path-picker.ts` | The partial restore's checklist, a `ChecklistScreen` over grouped paths: directory toggles, the change marks, and the selection it returns. |
+| `text/patch.ts` | Pure: split a single-file unified diff into its header and hunks, and rebuild a patch from chosen hunks. |
+| `view/hunk-picker.ts` | The hunk checklist a modified file's diff opens, a `ChecklistScreen` over the hunks: previews, the indices it returns, and its own row budget. |
+| `transport/store.ts` | Versioned metadata encoding and ref-backed listing/pruning. |
+| `state/policy.ts` | Which tool calls are worth a snapshot. |
+| `transport/temp-index.ts` | Per-process `GIT_INDEX_FILE` paths: create, release, and sweep stale files. |
+| `view/status.ts` | The `↺ N` status chip. |
+| `transport/queue.ts` | The serialized git operation queue for staging calls (`GIT_INDEX_FILE`). |
+| `state/runtime.ts` | Root/config caches and the snapshot/list/plan/patch/numstat/restore/hunk-revert operations. |
+| `state/timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
+| `commands/rewind.ts` | Scope choice, the path step, confirmation, and applying code + conversation rewind. |
+| `commands/review.ts` | The `/review` orchestration: the latest snapshot, the list/diff loop, the hunk step, confirmations, and the reverts. |
+| `view/review-tui.ts` | The changed-file list (a `ChecklistScreen`) and the scrollable per-file diff, which offers the hunk checklist. |
+| `view/rewind-tui.ts` | The selectable, width-safe timeline component, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
+| `commands/commands.ts` | The `/rewind` and `/review` commands. |
+| `text/format.ts` | Pure rewind and review text, including diff bounding and the hunk prompt. |