@aragon-agent/cli 0.6.25 → 0.6.26

package/CHANGELOG.md

@@ -8,6 +8,46 @@ were written.
 ## Unreleased
 
 ### Added
+- **`Ctrl+L` branches this session into a new terminal - and `Ctrl+R` now
+  redraws (KEY BINDING CHANGE).** One keystroke opens a PowerShell (Windows) or
+  bash (macOS/Linux) window in the session's current `/cwd`, running
+  `aragon --resume <id>` there: the child derives its own id and only ever writes
+  its own file, so the TUI you branched from keeps running untouched. The session
+  is force-flushed to disk BEFORE anything is spawned, because the child reads
+  that file first and the normal checkpoint is debounced. Works mid-run too - the
+  child inherits the last settled turn. Platforms: a new Windows Terminal tab
+  (`wt -d <cwd> ... --`), a new console window (`cmd /c start`), a Terminal.app
+  window via `osascript`, or the first available Linux emulator; each rung carries
+  the working directory itself, because `--resume` does not restore one. No
+  terminal (SSH, container) prints a pasteable `aragon --resume <id>` instead of
+  failing silently. `ARAGON_BRANCH_COMMAND` / `ARAGON_BRANCH_SHELL` override what
+  runs and which shell; presses are throttled to one window per two seconds and a
+  failed attempt never starts the cooldown. New `/branch` is the same code path.
+  The header (top right) now shows `^L branch` next to `^I Index` and `^G more`,
+  spending a fixed cell budget: `^I` therefore appears from 52 columns
+  (collapsed) / 62 columns (expanded) instead of 72, and on a very narrow terminal
+  the branch hint degrades to the bare `^L` before it is dropped.
+  **Breaking:** the redraw previously bound to `Ctrl+L` moved to `Ctrl+R` - same
+  behaviour, same overlay guard (the settings screen keeps its own `Ctrl+R`).
+
+- **A TUI session now has an id, and another terminal can continue it.** Every
+  interactive session is written to `~/.aragon-agent/sessions/<id>.json` as it
+  runs and shows that id at the right end of the status bar (`id a4k2m9`, or
+  `a4k2m9` on a narrow terminal - the id itself is never truncated). Checkpoints
+  are written after the first frame, after every settled turn (debounced), on
+  `/session pin`, and once on exit; each one is an atomic replace, because a
+  second terminal may be reading. `aragon --resume <id|path>` continues a saved
+  session under a NEW id and never writes the file it came from, so branching
+  while the original TUI keeps running is safe - including
+  `aragon exec --resume <tui-id>`, which now writes a session of its own instead
+  of overwriting yours. `aragon --save <id>` names this run's id and pins it
+  against `sessions prune`. New `/session [copy|pin]` reports the id, the file and
+  the branch parent, copies the resume command through the same clipboard door as
+  `/copy` (OSC 52 included), and pins the file. A checkpoint taken mid-tool is
+  repaired on the saved copy only, so resuming it cannot produce an illegal
+  history, and a tool card that was still running is settled so nothing spins
+  after a resume. `aragon -p` writes one checkpoint at exit: context only, no
+  transcript, because nothing was displayed.
 
 - **A model profile can be verified where it is written.** The profile editor
   gains two action rows: **Test connection** (`Ctrl+R`) and **Discover models**
@@ -23,8 +63,57 @@ were written.
   describe a model, endpoint or key the user has since edited. The progress line
   is static text: no new animated site, so `single-spinner` still holds.
 
+### Changed
+
+- **`aragon sessions list` gained an `origin` column** and shows TUI checkpoints,
+  which are managed files now. `sessions prune` defaults to `--origin exec`, so it
+  behaves exactly as before for every file that existed before this release; the
+  new `--origin tui|all` selects the other writer. `prune` never deletes a pinned
+  session or one whose owner process is still alive, and `--all` now means only
+  "also consider files with no session metadata" - it can no longer reach a TUI
+  checkpoint. `/resume` inside the TUI moves the session to a new id and restarts
+  the spend counter, because a new id's file must not bill the previous
+  conversation.
+
 ### Fixed
 
+- **A conversation saved mid-tool could be resumed into an illegal history.**
+  A `tool_call` with no matching `tool_result` makes the next request fail. The
+  checkpoint writer closes every dangling call on the copy it writes and re-checks
+  sendability before replacing the file; a history it cannot make sendable is not
+  written at all, so the previous good checkpoint survives.
+- **A checkpoint could carry a tool card that never stopped spinning.** A card
+  saved while its tool was running kept `ToolCard` animated and kept the
+  transcript's settled boundary from ever passing it, which re-rendered the tail
+  on every frame for the rest of the resumed session. Cards are now settled on the
+  saved copy only, which leaves `/save` (an explicit export you are watching) and
+  its documented behaviour untouched.
+- **`aragon exec --resume <tui-id>` overwrote the session it resumed.** The
+  write-back id preferred the file's own metadata, so exec took the TUI's id and
+  replaced the checkpoint - silent, unrecoverable loss of the conversation still
+  running in the other terminal. A TUI file now always yields a fresh id, and the
+  same rule covers `--session-id`, which used to return the typed id verbatim.
+- **`sessions prune --origin tui --yes` could delete a running session's
+  checkpoint.** The `live` marker was written by the TUI but the process lock it
+  is checked against was only ever taken by `exec`, so the liveness guard answered
+  "nobody owns this" for exactly the files it was written for. The TUI checkpoint
+  writer now holds the session lock for as long as it owns the file, releases it
+  on exit, and moves it when `/resume` rotates the id.
+- **`aragon --save <id>` said "already exists" for an id that does not exist.**
+  A session directory that cannot be written (read-only home, full disk) was
+  reported as a name collision, which sends the user to `--resume <id>` and then
+  to "no such session". It now names the directory instead.
+- **A hand-written `/save` file resumed as if it were a branch of itself.**
+  `--resume ./notes.json` recorded `notes` as `meta.branchOf` and announced it as
+  the parent session, though it is not a session id. Lineage is now recorded only
+  for ids this CLI minted, and a collision while deriving a branch id re-mints the
+  suffix instead of dropping the branch shape.
+- **`/session` answered `pinned  no` right after `/session pin`.** The file was
+  marked and the report was not. The identity is now updated with the pin.
+- **An id rotation could write one turn into the old id's file.** For the window
+  between `/resume` claiming a new id and the next render, the writer still aimed
+  at the previous file while recording the new parent. The rotation now republishes
+  the writer's id in the same step.
 - **`/clear` did not clear the context.** It reset the visible transcript and the
   todo panel and left `agent.state.messages` - the history that is actually sent,
   billed, measured by `/context` and compacted - completely untouched. A long

package/README.md

@@ -197,7 +197,7 @@ supplying it is frequently the least trusted input in the pipeline.
 aragon sessions list [--json] [-n 20] [--all]
 aragon sessions show <id> [--json]
 aragon sessions rm <id> --yes
-aragon sessions prune [--older-than 7] [--dry-run] [--all] --yes
+aragon sessions prune [--older-than 7] [--dry-run] [--all] [--origin exec|tui|all] --yes
 aragon sessions path
 ```
 
@@ -312,19 +312,25 @@ section is the one that would be misled by their omission.
    **On Windows only Ctrl-C does** — Node does not deliver the other two to
    listeners, so `taskkill` ends the process outright. Resolve on process exit as
    well as on `result`, or a killed run hangs your parent process.
-3. **A session created by `aragon exec` and resumed with `aragon --resume`
-   carries the model's full memory and shows no scrollback** for the turns that
-   ran headlessly. The reverse direction is fully faithful: a TUI `/save` resumed
-   by `aragon exec --resume <id>` keeps everything.
-4. **`aragon sessions prune` shares a directory with the TUI's `/save`**, so it
-   only ever touches sessions `exec` created — files that carry an exec `meta`
-   block — unless you pass `--all`. `sessions show` and `sessions rm` accept any
-   id, because you named it.
+3. **Resuming carries the model's full context, and only the scrollback that
+   was actually recorded.** `aragon --resume <id>` continues any saved session
+   — a TUI checkpoint, a TUI `/save` export, an `exec` session — under a NEW id,
+   with the whole conversation and no transcript replay for turns that ran
+   headlessly (`aragon -p`). A TUI checkpoint replays its screen faithfully.
+4. **`aragon sessions prune` never deletes what you are still using.** It only
+   touches sessions this CLI wrote (files with a session metadata block), and it
+   defaults to `--origin exec`, so a TUI checkpoint is out of scope unless you
+   ask for it with `--origin tui`. `--all` widens "which rows exist" to
+   hand-written `/save` files and never reaches a TUI checkpoint; `pinned`
+   sessions and files whose owner process is still alive are never deleted.
+   `sessions show` and `sessions rm` accept any id, because you named it.
 
 ## Usage
 
 ```
 aragon [prompt]                 Start the interactive TUI (or one-shot with -p / piped stdin)
+aragon --resume <id|path>       Continue a saved session under a NEW id (TUI or -p)
+aragon --save <id>              Name this session's id and pin it against `sessions prune`
 aragon -p, --print [prompt]     Headless: stream the answer to stdout, then exit
 aragon exec [prompt]            Machine-facing run: JSON events, sessions, permissions, budgets
 aragon sessions <sub> [id]      Manage exec sessions: list | show | rm | prune | path
@@ -397,6 +403,76 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 `3` stopped by a caller-set budget (`aragon exec` only) · `128 + signo` when a
 signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 
+## Session identity, resume and branching
+
+Every TUI session has a short id - six characters from an alphabet that omits
+`0 o 1 l i`, so it can be read off a screen without a transcription mistake - and
+that id is shown at the right end of the status bar. It is also written to
+`~/.aragon-agent/sessions/<id>.json` as the conversation proceeds, which is what
+lets a second terminal continue the same conversation.
+
+**The chip.** `id a4k2m9` when there is room (72 columns and up), `a4k2m9` below
+that, and nothing at all when even the id would crowd the status fields. An id is
+never truncated: half an id is a `--resume` command that cannot work, which is
+worse than no id, and `/session` reports the full id at any width. In the one
+layout where the status row itself is not drawn (a terminal too short for a single
+status line), the chip is absent by design and `/session` is the way to read it.
+
+**When it is written.** After the first frame (so the id on screen is resumable
+before the first message), after every settled turn (debounced, so a run that
+restarts itself does not write twice), on `/session pin`, and once on the way out.
+`aragon -p` has no screen and no turn events, so it writes exactly once, at exit.
+Every write replaces the file atomically - this is the first session file in this
+CLI that a reader may be looking at while it is rewritten.
+
+**What a checkpoint contains.** The full conversation, the todo list, the model
+and the transcript, plus a `meta` block naming the writer. A turn interrupted
+mid-tool is repaired ON THE COPY: the dangling `tool_call` gets an `isError`
+`tool_result` so the next request is legal, and any tool card still running is
+settled, so a resumed session has nothing left spinning. The live conversation is
+never edited to achieve this.
+
+**Branching.** `aragon --resume <id|path>` reads the named session and continues
+it under a **new** id (`a4k2m9-x7f2`, or a fresh id when the file was a
+hand-written `/save` export). The session it came from is not written again by
+this process - not its contents, not its `savedAt` - and `--continue` never points
+at it. That is what makes it safe to branch while the original TUI keeps running.
+(`aragon exec --resume <id>` follows the same rule: it reads your session and
+writes one of its own. `--continue` then names the newest **exec** session, which
+is the new one - it never names the TUI session it read.)
+
+Three entry points, three different behaviours, on purpose:
+
+| Command | Reads | Writes |
+| --- | --- | --- |
+| `aragon --resume <id\|path>` | the session you name | a NEW branch session; the parent is never touched |
+| `/resume [file]` (inside the TUI) | the file you name | this process moves to a NEW id, and the spend counter restarts |
+| `aragon exec --resume <id\|path>` | the session you name | a new exec session of its own - including when the session you named was written by the TUI |
+
+**Naming a session.** `aragon --save <id>` names this run's persistent id and pins
+it: `sessions prune` will never delete it. The value must be an id, not a path
+(`--save ./notes.json` exits 2 and says so); use `/save` inside the TUI to export
+to a file. `aragon --save <id>` refuses an id that already exists, and refuses the
+id you are resuming - either would mean writing over a session you still have.
+
+**`/session`.** Bare `/session` reports the id, the file it is written to, the
+branch parent (if any), whether it is pinned, and the two commands worth pasting.
+`/session copy` puts `aragon --resume <id>` on the clipboard through the same door
+`/copy` uses (OSC 52 included, so it works over SSH). `/session pin` writes once
+and marks the file as never-prunable.
+
+**Why there is no switch.** Sessions are recorded by default, exactly as
+`aragon exec` already wrote them by default, and there is deliberately no
+"show the id but do not save it" mode: it would leave an id you can copy and
+cannot use. `sessions rm <id> --yes` is the explicit way to delete one, and
+nothing is ever deleted automatically.
+
+**Headless checkpoints carry context, not scrollback.** A session continued with
+`aragon -p` records the conversation but no transcript, because nothing was ever
+displayed. `aragon --resume` of such a file inherits the full context and shows an
+empty screen until the next turn - the alternative, inventing entries, would put
+a conversation the user never saw onto their screen.
+
 ## Slash commands (interactive)
 
 | Command | Action |
@@ -410,8 +486,9 @@ signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 | `/clear` | Start a new conversation: interrupt the run, archive the old session, clear the context, transcript, queues and todo panel. `/clear screen` only clears the screen |
 | `/reset` | Alias of `/clear` - one implementation, so the two cannot drift apart |
 | `/cwd [dir]` | Show / change the tool working directory |
-| `/save [file]` | Save the session to JSON |
-| `/resume [file]` | Load a saved session |
+| `/save [file]` | Export the session to JSON - a file you keep, unchanged by this feature |
+| `/resume [file]` | Load a saved session. This session moves to a NEW id, and the spend counter restarts |
+| `/session [copy\|pin]` | Report this session's id, file and branch parent; `copy` puts `aragon --resume <id>` on the clipboard; `pin` makes `sessions prune` skip the file forever |
 | `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
 | `/team [on\|off\|max <n>\|overseer on\|off\|model [main\|fast\|<profile-name>]]` | Team subagents: status and the live roster, the on/off switch, the fan-out width, the dispatch supervisor |
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
@@ -449,7 +526,8 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Esc` again after interruption | **Force-stop** a run that is still stopping, kill foreground shell commands and return to `idle`; background services remain running |
 | `Ctrl+C` | **Copy the selection** when a drag-selection is waiting (release no longer copies by itself). Otherwise: stop the background **services** the agent started, when there are any. It does not arm exit |
 | `Ctrl+C` ×2 | Exit (first press warns), once no services are running |
-| `Ctrl+L` | Redraw the frame |
+| `Ctrl+L` | **Branch this session into a new terminal**: opens a PowerShell (Windows) or bash (macOS/Linux) window at the current `/cwd` and runs `aragon --resume <id>` there, so the branch gets its own id and the session you branched from is untouched. Works while the agent is running - the child inherits the last settled turn. Same code path as `/branch` |
+| `Ctrl+R` | Redraw the frame (moved here from `Ctrl+L`, which is now the branch key) |
 | `Ctrl+T` | Show / hide thinking (**off by default**) for the entire session |
 | `Ctrl+O` | Expand / collapse the most recent tool, team, compaction or **service** card — including a diff or a service's log tail |
 | `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
@@ -1103,6 +1181,10 @@ all reap the tree on a best-effort basis; there is no daemon, no PID file and no
 reattach across launches. A `SIGKILL` of aragon itself is unrecoverable by
 construction, and if a stop cannot confirm the process is gone it says
 `may have left a detached child` rather than claiming success.
+**A branch window is the deliberate exception.** `Ctrl+L` (see [Branch into a
+new terminal](#branch-into-a-new-terminal---ctrll)) starts a process that is
+not registered with the supervisor, so it is not a service: it is another
+session the user opened, and it keeps running after this window exits.
 
 From your side there are two keys and one command: `Ctrl+C` stops every live
 service (and does *not* arm exit), `/bg` lists them, and `/bg logs s1` prints a
@@ -1720,6 +1802,70 @@ running, `Ctrl+I` warns instead of queueing. `/skill:project-indexer` and
 > is distinguishable and the binding works. On a terminal that implements
 > neither, `Ctrl+I` simply behaves as `Tab`.
 
+### Branch into a new terminal - `Ctrl+L`
+
+Handing a conversation to a second window used to mean reading six characters off
+the status bar, switching windows, opening a shell and typing the command - and
+copying the id by hand is the one step of that chain which reliably goes wrong.
+`Ctrl+L` replaces it with one keystroke:
+
+1. The session is **flushed to disk first**. A child process reads that file as its
+   first act, and the parent's checkpoint is debounced, so the write is forced
+   before anything is spawned (`--resume` reads the file, never the running process).
+2. A new terminal opens **in the current `/cwd`** - not in `$HOME` and not in the
+   directory aragon was launched from: `/cwd` can change during a session, and
+   `--resume` does not restore a working directory. Each platform carries the path
+   itself: `wt -d <cwd>` for a Windows Terminal tab, `cmd /c start` for a plain
+   console (which inherits it), and a script that begins with `cd '<cwd>' &&` for
+   macOS Terminal and the Linux emulators.
+3. It runs `aragon --resume <id>` there. The child derives its own id, prints
+   `Resumed <id> as a new branch: session <new-id>`, and writes only its own file.
+
+Both windows are independent from that point: closing either one does not touch the
+other, `Ctrl+C` in the parent does not stop the branch, and the two transcripts
+never meet. **A branch window is another session and does not close when this one
+exits** (the reverse of the rule for supervised services below).
+
+The platform ladder, in order:
+
+| Platform | What is tried | Window |
+| --- | --- | --- |
+| Windows, inside Windows Terminal (`WT_SESSION` is set) | `wt -w 0 nt -d <cwd> --title "aragon <id>" -- <shell> -NoExit -EncodedCommand <base64>` | a new tab |
+| Windows, anywhere else | `cmd /d /s /c start "aragon <id>" <shell> -NoExit -EncodedCommand <base64>` | a new console window |
+| macOS | `osascript` driving Terminal.app | a new Terminal window |
+| Linux / other POSIX | the first of `$TERMINAL`, `x-terminal-emulator`, `gnome-terminal`, `konsole`, `xfce4-terminal`, `kitty`, `wezterm`, `alacritty`, `xterm` that exists | a new window |
+
+The shell is `pwsh.exe` then `powershell.exe` on Windows, and `$SHELL` then `bash`
+then `/bin/sh` elsewhere. Windows receives the command as `-EncodedCommand` (base64
+of UTF-16LE), because that alphabet has no spaces, quotes or `cmd` metacharacters -
+it survives `cmd` -> `start` -> PowerShell without a quoting argument.
+
+When no terminal can be opened - an SSH session, a container, a machine with no
+graphical session - the command opens nothing and prints the fallback instead:
+
+```
+No terminal window could be opened here. Run this in another terminal:
+aragon --resume a4k2m9
+```
+
+Two environment variables exist because neither belongs in a config file:
+
+| Variable | Effect |
+| --- | --- |
+| `ARAGON_BRANCH_COMMAND` | What the new window executes, as **one executable path** (no arguments - wrap a script in a `.cmd` / `.sh` if you need some). Defaults to the running build: `node <dist/cli.js>`, or `aragon` from `PATH` |
+| `ARAGON_BRANCH_SHELL` | The shell the new window runs. `C:\Program Files\PowerShell\7\pwsh.exe`, `/usr/bin/fish`, ... |
+
+Notes worth knowing:
+
+- The key leaves **one** line in the transcript, `Command: /branch`, and it joins
+  the prompt history. That is the same behaviour as `Ctrl+I` and it is what makes
+  the gesture a real command: `Esc` never has to cancel it, `/help` lists it, and
+  `/branch` typed by hand is byte-for-byte the same path (cooldown included).
+- Repeated presses are throttled to one window every two seconds; a press that
+  **failed** does not start the cooldown, so the retry is immediate.
+- `/session copy` is still there for the case this key cannot cover: copying the
+  command for a machine that is not this one.
+
 ### Progressive disclosure
 
 This is the part that makes skills cheap enough to install a lot of:
@@ -2289,7 +2435,7 @@ Everything AragonAgent keeps for you lives under one directory in your home:
 ├── logs/
 │   ├── aragon-2026-07-27.log       today, JSON Lines
 │   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes
-├── sessions/                       /save and /resume
+├── sessions/                       session checkpoints, /save exports, exec sessions
 ├── skills/                         aragon skills install
 └── skill-usage.json
 ```
@@ -2519,6 +2665,12 @@ Queue 面板逐条显示待处理消息，数量在展开状态详情中按空
 费用是含子代理、快速模型及压缩的会话估算 USD，恢复会话沿用累计，缺价格按零计，零值不保证免费。
 本轮均速只累计主 Agent 已报告的 output tokens，再除以本轮总耗时（含工具与等待）；排除辅助调用，并非瞬时生成速度。结束后保留耗时，速度显示 --。
 `/context` 提供统计范围和完整值。
+Ctrl+L 把当前会话分支到一个新终端：先强制落盘，再在父 TUI 的 `/cwd` 下打开 PowerShell（Windows）
+或 bash（macOS/Linux）窗口，在其中执行 `aragon --resume <id>`，子会话派生自己的新 id，原会话的 id、
+历史与文件都不受影响；运行中同样可用，子会话继承到上一个已落定的轮次。重绘迁到 Ctrl+R，
+右上角常驻 `^L branch` 提示（窄终端先丢 `^I`、再只留 `^L`）。每次按键会在转录里留下一行
+`Command: /branch`，并进入提示历史，与 Ctrl+I 完全同构。没有可用终端时只打印一条可粘贴的
+`aragon --resume <id>`，不会静默失败。
 
 Windows Terminal：在设置 JSON **根级**添加 `"copyOnSelect": false`，把以下条目合并到已有数组：
 

package/dist/agent/reducer.d.ts

@@ -385,6 +385,14 @@ export interface ViewState {
      */
     droppedEntries: number;
 }
+/**
+ * The zero session total.
+ *
+ * ONE LITERAL FOR TWO SITES (`initialViewState` and `resetConversation`). They
+ * used to spell the object out twice, which is how `cacheReadTokens` would have
+ * been added to one of them and not the other.
+ */
+export declare const EMPTY_USAGE_TOTAL: UsageTotal;
 export interface ViewStateSeed {
     /** Start with thinking blocks expanded. Defaults to FALSE, the product default. */
     thinkingVisible?: boolean;
@@ -490,6 +498,20 @@ export type ViewAction = {
     type: 'clearTranscript';
 } | {
     type: 'resetConversation';
+}
+/**
+ * Zero the session's spend WITHOUT touching the conversation
+ * (tui-session-id-resume D-10 / R-9 / T-45).
+ *
+ * A separate action rather than `resetConversation`, because the two mean
+ * different things: `/clear` ends the conversation and the spend together,
+ * while an in-TUI `/resume` adopts another conversation and starts a NEW id -
+ * so the counter must restart, but the entries that were just restored must
+ * not be thrown away with it. `context` is left untouched for the reason
+ * `resetConversation` records: the meter, not the reducer, owns occupancy.
+ */
+ | {
+    type: 'resetUsage';
 } | {
     type: 'setOverlay';
     overlay: Overlay;

package/dist/agent/reducer.js

@@ -24,7 +24,7 @@ export const DEFAULT_TOAST_TTL_MS = 2500;
  * used to spell the object out twice, which is how `cacheReadTokens` would have
  * been added to one of them and not the other.
  */
-const EMPTY_USAGE_TOTAL = {
+export const EMPTY_USAGE_TOTAL = {
     inputTokens: 0,
     outputTokens: 0,
     cacheReadTokens: 0,
@@ -809,6 +809,9 @@ export function viewReducer(state, action) {
                 // still running. `/clear screen` clears the screen, not the session.
                 compactionEntryId: undefined,
             };
+        case 'resetUsage':
+            // The one field, for the one reason: a new id bills from zero (D-10).
+            return { ...state, usageTotal: EMPTY_USAGE_TOTAL };
         case 'resetConversation':
             return {
                 ...state,