@namzu/cli 26.3.0 → 28.0.0

package/CHANGELOG.md

@@ -1,5 +1,276 @@
 # @namzu/cli
 
+## 28.0.0
+
+### Major Changes
+
+- a75f5c2: **`namzu run` and `namzu run-stream` are removed. Use `namzu exec`.**
+
+  | Before                        | After                                             |
+  | ----------------------------- | ------------------------------------------------- |
+  | `namzu run "<prompt>"`        | `namzu exec "<prompt>"` (or `namzu e "<prompt>"`) |
+  | `namzu run-stream "<prompt>"` | `namzu exec --json "<prompt>"`                    |
+
+  `exec` takes every option the two old commands took, with the same meanings:
+  `--cwd`, `--provider`, `--model`, `--effort`, `--skills`, `--continue`/`-c`,
+  `--resume`, `--session`, `--gate`, `--gate-retries`, `--max-iterations`,
+  `--token-budget`, `--wait-for-provider`, `--permission-mode`, `--trust`,
+  `--yolo` and `--`. The default mode prints the reply exactly as `run` did and
+  keeps its exit codes (0, 1, 2, 64, 75, 77, and death by SIGTERM/SIGHUP/SIGINT).
+  `--json` writes the same NDJSON events, with the same kinds and fields, and
+  the same exit codes (0, 1, 75, 77) that `run-stream` did. Typing `run` or
+  `run-stream` now fails with commander's `unknown command` error, exit 64, and
+  a line naming the replacement. Update scripts, CI jobs and host UIs that spawn
+  either command.
+
+  **New: `--output-schema <file>` on `exec`.** It binds the final answer to a
+  JSON Schema through the provider's native structured output, in either mode.
+  Before, `--output-schema` was accepted only before the command, for the TUI,
+  and refused everywhere else; given before `exec` it is still refused, now with
+  a message that says to pass it after `exec`. A schema file that cannot be read
+  or represented exits 64 (in `--json` mode: an `error` event and exit 0).
+
+  **Also changed:**
+
+  - `namzu exec --session <id>` without `--json` is refused with exit 64. `run`
+    accepted `--session` and ignored it, answering against no history; the
+    default mode resumes with `--continue` or `--resume <id>`.
+  - `namzu resident` refuses `--json` and `--output-schema`, which it would
+    otherwise have accepted and ignored.
+  - The `--log-format` help and the TUI's `--output-schema` help name `exec`.
+
+### Minor Changes
+
+- ab9108b: Refresh the Zen and Zen Go model catalogue in the background on every launch. The interactive TUI, `resume`, `run`, `run-stream`, `acp`, `drain`, `resident run` and the background resident runner start one refresh that never delays startup, gives up after 30 seconds and is cancelled when the command ends. When it lands, the model picker and routing use it immediately, including for providers already built, and it is saved as a last-good copy at `cli/zen-catalogue.json` under `NAMZU_HOME`. When it fails, the session keeps the last-good copy, or otherwise the bundled catalogue, and logs one warning. A damaged copy on disk is ignored rather than read in part. A model the service serves with no known wire format is not offered in the picker, since the CLI has no setting that names a protocol for it.
+
+  This is on by default, and each of those launches now reads OpenCode's documentation pages, models.dev and the two Zen `/models` endpoints over the network. To keep the previous behaviour (bundled catalogue only, no network read), set `modelCatalogueRefresh: false` in `~/.namzu/config.yaml`, or `NAMZU_MODEL_CATALOGUE_REFRESH=0`.
+
+### Patch Changes
+
+- 128913f: The TUI says "turn" where it still said "run" for the unit of work that no
+  longer exists: `/cost`, `/status` and the status panel label spend as
+  "current or latest turn", a message held after a paused turn says so, the
+  `/config` notice names turn limits, and the headless trust refusal says a
+  headless turn approves tools without asking, and `namzu doctor`'s
+  remediation for an unusable fallback says turns will still start. Wording only; nothing a script
+  parses changed.
+- Updated dependencies [ab9108b]
+  - @namzu/zen@2.5.0
+
+## 27.0.0
+
+### Major Changes
+
+- 518b0d3: Every turn the CLI starts keeps its newest 10 checkpoints instead of all of
+  them. That covers interactive turns, `namzu run`, resumed and drained turns,
+  and delegated child sessions. A turn takes a checkpoint every iteration plus
+  one per tool review, and nothing set a limit, so a long session kept every
+  one. On one machine that came to 19,014 checkpoint files and 6.33 GB.
+
+  **What changes for you.** Only the newest 10 checkpoint documents of each turn
+  stay in `<session-id>/checkpoints/`, and `namzu drain` reports at most that
+  many per turn. A checkpoint whose decision is still outstanding is never
+  pruned. Resuming is unaffected, because every resume reads the checkpoint it
+  was handed or the newest one. If you inspect intermediate checkpoints by hand,
+  copy them out while the turn is still going.
+
+- b064cea: **The OS sandbox is now off by default.** Shell commands and file tools run
+  on the host under the permission system, the way other coding agents run
+  them: each shell command goes through your permission rules and mode, and a
+  file tool's path outside the working directory and the added directories is
+  shown to you as an approval request (`Outside the working directory: <path>`)
+  instead of being refused. It is asked every time — `auto`, `--yolo`, `plan`
+  (for a read) and an earlier "allow all tools for this session" included —
+  while `strict` and a `deny` rule still refuse it. **A headless turn refuses it**: pass the
+  directory with `--add-dir` (or `additionalDirectories`) when an unattended run
+  needs it. Each answer is an audit record.
+
+  **To keep the previous behaviour** (every command confined), write
+  `sandbox.enabled: true` in `namzu.config.json` or `~/.namzu/config.yaml`. The
+  sandbox is also on, without that line, when `sandbox.requireIsolation` names a
+  control or `sandbox.workspace` is `ephemeral`. `sandbox.enabled: false` keeps
+  working as before.
+
+  With the sandbox on, a `bash` call may set `dangerously_disable_sandbox: true`
+  to run one command on the host. It is asked about every time, `auto` and
+  `--yolo` included (`plan` and `strict` refuse it); it is refused when nobody can
+  be asked, unless `sandbox.allowUnattendedEscape: true`; `sandbox.allowEscape:
+false` refuses it always. Each approval or refusal is an audit record.
+
+  `/add-dir` of a directory outside the working directory now asks before adding
+  it, deciding after links are followed (a link inside that points outside is
+  asked about under the path it leads to, and that canonical path is what is
+  added). A directory inside the working directory is no longer added: the tools
+  already reach it. The system prompt states where tools run and how to reach past that, and
+  on WSL where the Windows drives are and how to start a Windows program.
+
+- 7cac6dc: `#note` and `/memory add` now save a typed memory file instead of appending a bullet to `<project>/.namzu/MEMORY.md`.
+
+  What changes for you:
+
+  - **Where a note goes.** `#note <text>` and `/memory add <text>` write `<name>.md` (type `project`; `/memory add --type user|feedback|project|reference <text>` picks another) into the project's stored memory — `<NAMZU_HOME>/projects/<slug>/memory/` by default — the same files the model's `save_memory`, `search_memory` and `read_memory` use. The terminal names the file. `/memory --user add <text>` is unchanged and still appends to `~/.namzu/MEMORY.md`. To keep writing a note into the curated project file, edit `<project>/.namzu/MEMORY.md` directly; it is still read into every turn.
+  - **Old notes are copied only when you ask, and your file is never changed.** The project's curated `MEMORY.md` is not rewritten, at launch or ever: nothing can tell a bullet `#note` appended from one you wrote. When it holds top-level bullets, the launch says how many, once per curated file, and `/memory import-notes` copies every top-level bullet (its first line) into a typed `project` memory, skipping any already stored — by an earlier import, a `#note` with the same text, or a copy you archived — so running it twice creates no duplicates. The bullets stay curated text in every turn until you delete them from the file yourself.
+  - **A one-time move of the JSON store on first launch.** An earlier JSON memory store (`index.json` + `content/`) in the same directory is imported with its ids and renamed `*.migrated`; the launch says so. A record too large for a memory file (over 256 KiB) is not imported and is named, with the retired file that still holds it.
+  - **The prompt.** Every turn carries a `## Stored memories (index)` section — one line per memory you or the model saved, at most 200, your `feedback` and `user` memories first. What the session memory promoter (or `compaction.consolidate`) writes after a turn is searchable but not listed, so a turn's record does not change the next turn's system prompt — and the curated sections are renamed `## Curated memory (all projects)` and `## Curated memory (this project)` (they were `## Durable memory` and `## Project memory`). Anything that matched those headings in a captured prompt must match the new ones.
+  - **`/memory show`** lists stored memories' index lines before the curated files, and what turns recorded on their own in a separate `Recorded by turns (N)` section, so those records are visible even though the prompt's index leaves them out.
+  - **Note names are short.** A note's file is named after its first words, at most 32 characters, so its index line keeps room for the note itself.
+
+  Nothing in the CLI's library exports changed.
+
+- 3e7a97b: The CLI moves to the SDK's session → turn → message model and to one state
+  layout under `NAMZU_HOME` (default `~/.namzu`). Conversations, checkpoints,
+  memory and resident state written by 26.x are **not read** by this version.
+
+  **Before you upgrade.**
+
+  - **Run `namzu drain` on 26.x** until it reports nothing parked. A turn still
+    parked on a decision or a provider wait when you upgrade cannot be resumed.
+  - **Export any conversation you want to keep** with
+    `namzu history --session <id> > conversation.json` on 26.x (with no
+    `--session`, the latest one in the folder); it prints the messages as JSON.
+    There is no migration: nothing is imported, so nothing is lost silently or
+    brought back half-read.
+
+  ## What changes for you
+
+  - **Where state lives.** Each working directory gets
+    `~/.namzu/projects/<slug>/`, where the slug is the directory's canonical
+    path with every character outside `[A-Za-z0-9]` replaced by `-`. A session is
+    `<session-id>.jsonl` there, with its child sessions, checkpoints, tasks,
+    feedback, goals, tool-result spills and file-history snapshots under
+    `<session-id>/`. Memory moves to `projects/<slug>/memory/`, resident state to
+    `projects/<slug>/residents/`, and git worktrees to
+    `projects/<slug>/worktrees/`. `~/.namzu/index.sqlite` is an index rebuilt
+    from the logs whenever it is missing or out of date; deleting it loses
+    nothing. The CLI still never writes into the working directory; `.namzu/`
+    there is read only, for the agents, skills, commands, plugins and
+    `MEMORY.md` you put in it.
+  - **Old state is left alone and reported.** `namzu state` now prints report
+    `version: 2` with a `legacy` category: the old top-level `state/`,
+    `sessions/`, `titles.json`, `desktop-sessions.json`, `delegation-history/`,
+    `checkpoints/`, `tenants/`, `goals/`, `feedback/`, `learning/`,
+    `residents/`, `worktrees/` and `memory/`, and every `projects/<uuid>/`
+    directory. It lists their paths and sizes and never opens, moves or deletes
+    them; remove them yourself once you have exported what you need. A new
+    `projects/<slug>/` is never reported as legacy.
+  - **One turn at a time per session.** A session has at most one active turn.
+    `namzu run` and `namzu run-stream` against a session whose turn is still
+    running, paused or interrupted now exit **75** (EX_TEMPFAIL) and name that
+    turn: on stderr for `run`, as an NDJSON
+    `{"kind":"error","code":"turn_in_progress",…}` event for `run-stream`. 75
+    keeps its existing meaning for a provider pause too; a wrapper that already
+    retries later on 75 needs no change. In the TUI the refusal offers
+    `/resume` or the new **`/abandon`**, which closes the paused turn so the next
+    prompt can start.
+  - **A rate limit on the first request pauses the turn.** A provider rate
+    limit or outage on a turn's first request used to fail it (`namzu run`
+    exit 1) with nothing to continue; it now pauses it at a checkpoint like the
+    same fault later in the turn: `namzu run` exits 75 naming the checkpoint,
+    `--wait-for-provider` waits and resumes it, and `/resume` or `namzu drain`
+    continues it.
+  - **`/agents runs` is now `/agents batches`**, with no alias. `/agents runs`
+    prints the unknown-subcommand usage.
+  - **NDJSON gains ids.** `run-stream`'s `done` and `usage` events carry
+    `sessionId` and `turnId`, and a `paused` event names its `turnId` instead
+    of a run id.
+  - **Hooks.** The events `run_start`, `run_end` and `run_interrupt` are
+    `turn_start`, `turn_end` and `turn_interrupt`; a config that names an old
+    event is refused at load with a message naming the new one. A hook's stdin
+    carries `turn_id` (not `run_id`) and, on `subagent_stop`,
+    `parent_session_id` and `parent_turn_id` (not `parent_run_id`); its
+    environment carries `NAMZU_TURN_ID` (not `NAMZU_RUN_ID`). `session_id` and
+    `NAMZU_SESSION_ID` are always set. `session_start` and `session_end` hooks
+    receive no turn id: the CLI no longer invents one for them.
+  - **`namzu drain`** keeps its flag names and exit codes (0, 1, 64, 77), but
+    `--store` means something else: it was the `runs/` directory a checkpoint
+    store wrote to, and it is now the namzu home (`NAMZU_HOME`, `~/.namzu` by
+    default) whose `projects/` hold the session logs. A `--store` without a
+    `projects/` directory is refused with 64, so a wrapper that still passes its
+    old `runs/` path must pass the home instead. A scope the store does not hold
+    (an unknown session, one under another project or tenant, a child session)
+    is also 64; state that cannot be read is 1. It finds parked turns through
+    the session index, takes each session's lease, and continues the same turn
+    from its checkpoint; a turn whose session lease another worker holds is
+    skipped and reported.
+  - **Delegation history is not carried over.** The history block and
+    `/agents` read finished child sessions from their logs; children recorded by
+    26.x do not appear.
+  - **Checkpoints.** A session keeps each turn's newest 10 checkpoints under
+    `<session-id>/checkpoints/`; one an open decision references is never
+    pruned. `/restore` snapshots are under `<session-id>/file-history/`.
+  - **Crash dumps are gone.** The session log and per-iteration checkpoints hold
+    everything an interrupted turn needs, so no `emergency/` dumps are written.
+    An interactive session that was interrupted closes that turn as interrupted
+    when you send the next prompt.
+  - **A stopped process gives its conversation back.** On SIGTERM, SIGHUP (a
+    closed terminal) or SIGINT, the TUI, `namzu run` and `namzu run-stream`
+    release the conversation's writer lease first, then stop the turn, close
+    the session (tool servers, background jobs, the `session_end` hook) and give
+    the terminal back, and then die of the signal they were sent: a wrapper
+    sees 143, 129 or 130 as before. The turn is left interrupted, so `/abandon`,
+    `/resume`, `namzu drain` or the TUI's next prompt take it at once; before,
+    they were refused as "leased by a live writer" for up to five minutes. A
+    second signal exits immediately. `run-stream` writes
+    `{"kind":"error","code":"terminated",…}` and a final `done` before it exits,
+    and `run` names the session on stderr. SIGKILL still leaves the lease to
+    expire. The message follows where the signal found the turn: a turn that
+    had already ended (the session still closing) is reported as recorded, not
+    interrupted, and `run-stream`'s one `done` is then the turn's own; a
+    `run --wait-for-provider` stopped during its wait says the turn is paused
+    at its checkpoint, and does not resume it.
+
+### Patch Changes
+
+- 96ac3ec: A session never writes generated state into its working directory, and a
+  session started in the home directory no longer reads the same memory file
+  twice.
+
+  Every entry point — `namzu`, `namzu run`, `namzu run-stream`, `namzu drain`
+  and resident runs — keeps its sessions, memory and task state under the
+  application home (`NAMZU_HOME`, else `~/.namzu`), in the working directory's
+  `projects/<slug>/`, and files them under that directory's one Project.
+  `<cwd>/.namzu` is only read, for the agents, skills, commands, plugins and
+  `MEMORY.md` you keep there.
+
+  Started in `$HOME` with no `NAMZU_HOME`, the project's `.namzu/MEMORY.md` and
+  the user's `~/.namzu/MEMORY.md` are one file. It was injected into every
+  prompt twice, under both headings. It is now read once, as the user memory.
+
+- 3641102: The turn-start repository snapshot (`git status` and recent commits, sent on a
+  send's first request) now reaches the model as request-only context after the
+  conversation, not as a system message. On Anthropic, each new send used to
+  change the system prompt and re-read the whole conversation uncached. Now the
+  cached conversation is kept and only the snapshot's own tokens are new.
+
+  What the model reads changes in two ways: the snapshot arrives in a user-role
+  message rather than a system message, and it follows the line
+  `Current step context (runtime-generated; not a new user request):`, which
+  every request-only context message opens with. The snapshot text itself is
+  unchanged.
+
+- Updated dependencies [8805360]
+- Updated dependencies [a729b17]
+- Updated dependencies [9355755]
+- Updated dependencies [755a81a]
+- Updated dependencies [cb1f00c]
+- Updated dependencies [3641102]
+- Updated dependencies [933ba6d]
+- Updated dependencies [3e7a97b]
+- Updated dependencies [a84dc1c]
+- Updated dependencies [b064cea]
+- Updated dependencies [9238347]
+- Updated dependencies [a14b013]
+- Updated dependencies [3641102]
+- Updated dependencies [3641102]
+- Updated dependencies [3e43fc2]
+  - @namzu/sdk@44.0.0
+  - @namzu/anthropic@6.0.1
+  - @namzu/openrouter@3.0.1
+  - @namzu/zen@2.4.0
+  - @namzu/computer-use@1.4.3
+  - @namzu/ollama@2.2.4
+  - @namzu/openai@4.0.0
+
 ## 26.3.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@ type: Reference
 title: "@namzu/cli"
 description: >-
   A terminal coding agent with interactive sessions, parallel agents, saved
-  conversations, headless runs that stream structured events,
+  conversations, headless one-shots that stream structured events,
   and a doctor that reports what the host can actually do.
 tags: [readme, package, cli, agent]
 status: stable
@@ -20,7 +20,7 @@ generated: { by: human:bahadirarda, at: 2026-09-01T00:00:00Z }
 [![build](https://github.com/cogitave/namzu/actions/workflows/ci.yml/badge.svg)](https://github.com/cogitave/namzu/actions/workflows/ci.yml)
 [![license](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](https://github.com/cogitave/namzu/blob/main/LICENSE.md)
 
-[Install](#install) · [Usage](#usage) · [Headless](#headless-runs) · [Documentation](#documentation)
+[Install](#install) · [Usage](#usage) · [Headless](#headless-use-namzu-exec) · [Documentation](#documentation)
 
 </div>
 
@@ -112,33 +112,36 @@ once in PowerShell or Git Bash using the Node installation that owns Namzu.
 For a custom global prefix, include `--prefix "<existing-prefix>"`. Restart
 Namzu afterward; the updated CLI includes the corrected npm launcher.
 
-Generated CLI state now lives below the application home: `~/.namzu` by
-default, or the existing real directory named by `NAMZU_HOME`. New directories
-inside the same checkout share one Project, keyed by its canonical root; a
-standalone directory is its own project. Worktrees and nested repositories
-remain separate. Existing central bindings for individual subdirectories keep
-their own histories. Bash, Write and Edit still use the selected working
-directory while transcripts, runs, memory and tasks live centrally. A local
-`.namzu` holds authored `commands`, `plugins`, `skills` and `MEMORY.md`.
-Older project-local runtime and global `cli.json` pointers are inventory data;
-the CLI does not automatically adopt or migrate them. See
-[Project and session state](../../docs/cli/project-state.md) for identity and
-compatibility details.
-
-`namzu state` inventories the current workspace's legacy `.namzu` tree and the
-resolved application-home tree without loading either config cascade or
-changing either tree. It reports authored/configuration/runtime/control bytes, canonical
-sessions and runs, raw checkpoint and emergency-save files, attachment pairs,
-privacy boundaries, and project binding health. JSON and YAML use the global
-`--format` flag. The snapshot is best-effort and unlocked: origin-only sessions
-are candidates for investigation, never an automatic deletion claim, and the
-command does not repair, move, chmod, or delete anything.
+Generated CLI state lives below the application home: `~/.namzu` by default,
+or the existing real directory named by `NAMZU_HOME`. Each working directory
+gets `projects/<slug>/`, where the slug is its canonical path with every
+character outside `[A-Za-z0-9]` replaced by `-`; a project id is minted once
+into `projects/<slug>/project.json`. A session is one append-only log,
+`projects/<slug>/<session-id>.jsonl`, with its child sessions, checkpoints,
+tasks and file-history snapshots under `<session-id>/`; memory, resident state
+and worktrees are under `projects/<slug>/` too. `~/.namzu/index.sqlite` is an
+index rebuilt from the logs, so deleting it loses nothing. Bash, Write and
+Edit still use the selected working directory, and nothing generated is
+written there: a local `.namzu` holds only the `agents`, `commands`,
+`plugins`, `skills` and `MEMORY.md` you author. See
+[Session storage](../../docs/cli/session-storage.md) for the layout and
+[Project and session state](../../docs/cli/project-state.md) for identity.
+
+`namzu state` inventories the application-home tree without loading a config
+cascade or changing anything. It reports authored/configuration/runtime/control
+bytes, sessions and turns, checkpoint files, attachment pairs, privacy
+boundaries and project health, and a `legacy` category (report `version: 2`)
+listing state an earlier CLI wrote — the old top-level `sessions/`, `state/`,
+`checkpoints/` and similar directories, and every `projects/<uuid>/` — which
+this version never reads. JSON and YAML use the global `--format` flag. The
+snapshot is best-effort and unlocked, and the command does not repair, move,
+chmod, or delete anything.
 
 Desktop control is separate from attaching a clipboard image. Ctrl+V/Alt+V
 adds an image to the current prompt; the TUI's `computer_use` tool lets the
 model take a fresh screenshot and, after the normal permission decision, drive
 pointer or keyboard input. Namzu mounts that tool only when the host adapter
-initializes. Unattended `run`, `run-stream` and `drain` do not mount it because
+initializes. Unattended `exec` (in either mode) and `drain` do not mount it because
 they have no interactive permission owner. Inside WSL the TUI targets the
 paired Windows desktop through `powershell.exe`, so WSLg display variables do
 not incorrectly select a Linux compositor adapter.
@@ -191,18 +194,18 @@ Public Zen is listed after existing accounts and reachable local providers
 and carries the label `free models · no API key`.
 
 ```bash
-namzu run --provider zen "Explain this project"
-namzu run --provider zen --model muse-spark-1.3-contributor-free "Explain this project"
-namzu run --provider zen-go --model glm-5.3-flash "Explain this project"
+namzu exec --provider zen "Explain this project"
+namzu exec --provider zen --model muse-spark-1.3-contributor-free "Explain this project"
+namzu exec --provider zen-go --model glm-5.3-flash "Explain this project"
 ```
 
 The Zen commands use public access when no key is available; Go requires its
 own credential. All use the existing folder-trust rules. The same
-provider/model flags work with `run-stream`.
+provider/model flags work with `exec --json`.
 The picker lists each service's supported models from the provider catalogue;
 an explicit model selection is saved using the existing preferences flow.
 Go requests carry the actual Namzu conversation ID in `x-opencode-session`,
-stable across turns and resumed runs. Delegated work shares its invoking
+stable across turns and resumed turns. Delegated work shares its invoking
 conversation's upstream session; switching conversations changes that ID.
 
 Bare `/help` opens the session's complete command vocabulary as a keyboard
@@ -324,16 +327,25 @@ session. In particular, `sandbox yes` describes the local runtime provider that
 will execute tools; it is independent of the optional-package installation row
 reported by `namzu doctor`.
 
-The coding session defaults that provider to the canonical working directory.
+Tools run on the host under the permission system by default: each shell
+command goes through the permission rules and mode, and a file tool's path
+outside the working directory is an approval request rather than a refusal —
+asked every time (`strict` refuses it, `plan` asks only for a read), and
+refused when nobody can be asked (add the directory with `--add-dir` instead). The OS sandbox is opt-in with `sandbox.enabled: true`; a sandboxed `bash` call
+may ask to run one command outside it, and that request is put to you every
+time (`plan` and `strict` refuse it), and refused when nobody can be asked. See
+`docs/cli/tool-boundary.md`.
+
+With the sandbox on, the provider defaults to the canonical working directory.
 Each turn owns and tears down a fresh sandbox handle, while the caller-owned
 project files survive and remain visible to later turns and delegated agents.
-Set `sandbox.workspace` to `ephemeral` only when a disposable per-run tree is
+Set `sandbox.workspace` to `ephemeral` only when a disposable per-turn tree is
 the intended behavior; `/status` reports which mode is active.
 
-The default sandbox exposes Bash as a foreground, serialized operation. It does
-not advertise the background-job tool or a `run_in_background` input that the
-sandbox cannot preserve. Use delegated agents for independent concurrent work;
-turning the sandbox off restores the host background-job capability.
+A sandbox that cannot start a detached process exposes Bash as a foreground,
+serialized operation and refuses `run_in_background`. Use delegated agents for
+independent concurrent work; host execution keeps the background-job
+capability.
 
 Ctrl+L clears only the rendered terminal transcript while idle. It preserves
 model context, durable conversation history and copy/export targets; an active
@@ -344,8 +356,8 @@ Bare `/export` opens a destination chooser for the complete verified Markdown
 conversation. Copy to clipboard sends one bounded terminal request and reports
 that the request may be ignored by terminal policy; Save to file opens a
 prefilled filename editor and never overwrites an existing file. `/export <path>`
-remains the direct file shortcut. Both routes read the durable turn/run
-evidence rather than reconstructing source from the painted transcript.
+remains the direct file shortcut. Both routes read the session log rather than
+reconstructing source from the painted transcript.
 
 Repository policy stays live for the whole session. The CLI starts with the
 applicable `AGENTS.md` chain, discovers nested instruction files after
@@ -360,25 +372,34 @@ both scopes. Project plugins are not read before the project trust gate, and
 plugin paths are canonicalized against the trusted project or user-home root;
 links that leave that scope and symlinked manifests are refused. Plugin
 settings cannot be activated by an environment-selected profile. The
-same plugin hooks and skills reach interactive turns, headless runs, durable
+same plugin hooks and skills reach interactive turns, headless turns, durable
 resumes, and ACP sessions; session shutdown settles live work before unloading
 them.
 
-## Headless runs
+## Headless use: `namzu exec`
 
 ```bash
-namzu run "fix the failing test" --format json
-namzu run-stream "refactor the parser" | jq -c 'select(.type == "tool_call")'
+namzu --format json exec "fix the failing test"
+namzu exec --json "refactor the parser" | jq -c 'select(.kind == "tool-start")'
+namzu exec --output-schema answer.schema.json "rate this diff from 1 to 5"
 ```
 
-`run` prints a result; `run-stream` emits one structured event per line as the
-run happens, so a script can act on a tool call before the run is over. Both
-take `--verbose`/`--quiet`, and both write logs to stderr so stdout stays a
-clean protocol stream.
+`namzu exec` (alias `namzu e`) prints a result; `namzu exec --json` emits one
+structured event per line as the turn happens, so a script can act on a tool
+call before the turn is over. `--output-schema <file>` binds the final answer
+to a JSON Schema through the provider's native structured output. Both modes
+take `--verbose`/`--quiet` (before `exec`), and both write logs to stderr so
+stdout stays a clean protocol stream. A session has one active turn at a time:
+either mode aimed at a session whose turn is still running or paused exits 75
+and names that turn. See [Exit codes](../../docs/cli/exec-exit-codes.md) and
+[`exec --json`](../../docs/cli/exec-json.md).
+
+`namzu run` and `namzu run-stream` were removed: use `namzu exec` and
+`namzu exec --json`, which take the same options.
 
 Recoverable provider stops are explicit `paused` events carrying their
 checkpoint and any structured retry guidance. The interactive transcript shows
-the same remedy and holds dependent queued input; `run` exits non-zero rather
+the same remedy and holds dependent queued input; `exec` exits non-zero rather
 than treating a paused or failed partial answer as complete.
 
 The interactive transcript also shows provider capability mismatches and

package/dist/bin.js

@@ -3,14 +3,21 @@ import { fileURLToPath } from 'node:url';
 import { runCli } from './cli.js';
 import { EXIT_INTERNAL_ERROR } from './exit-codes.js';
 import { resumeInvocation } from './resume-invocation.js';
+import { terminationInProgress } from './termination.js';
 // Preserve source loaders and alternate installations when the public command differs.
 const entrypoint = fileURLToPath(import.meta.url);
 runCli({
     argv: process.argv,
     resumeCommand: resumeInvocation(entrypoint),
 }).then((code) => {
+    // A command stopped by a signal can return while its handler is still
+    // giving the conversation back; the handler ends the process.
+    if (terminationInProgress() !== null)
+        return;
     process.exit(code);
 }, (err) => {
+    if (terminationInProgress() !== null)
+        return;
     process.stderr.write(`Fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
     process.exit(EXIT_INTERNAL_ERROR);
 });

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,uFAAuF;AACvF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,CAAC;IACN,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,aAAa,EAAE,gBAAgB,CAAC,UAAU,CAAC;CAC3C,CAAC,CAAC,IAAI,CACN,CAAC,IAAI,EAAE,EAAE;IACR,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACnB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;IACP,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAC7E,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;AAClC,CAAC,CACD,CAAA"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,uFAAuF;AACvF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,CAAC;IACN,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,aAAa,EAAE,gBAAgB,CAAC,UAAU,CAAC;CAC3C,CAAC,CAAC,IAAI,CACN,CAAC,IAAI,EAAE,EAAE;IACR,sEAAsE;IACtE,8DAA8D;IAC9D,IAAI,qBAAqB,EAAE,KAAK,IAAI;QAAE,OAAM;IAC5C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACnB,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;IACP,IAAI,qBAAqB,EAAE,KAAK,IAAI;QAAE,OAAM;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAC7E,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;AAClC,CAAC,CACD,CAAA"}

package/dist/checkpoints/store.d.ts

@@ -6,7 +6,7 @@
  * Not git. A checkpoint is taken by the tool wrapper immediately before an
  * `edit` or `write` runs, whatever the repository's state, and it records
  * absence too, so a file the model created is removed on restore. Kept per
- * session under the project's private state and dropped when the session
+ * session in its `<session-id>/file-history/` directory and dropped when the session
  * closes: a checkpoint outlives a turn, not a session — the conversation
  * can be forked and resumed, and its files are the working tree's.
  */
@@ -30,18 +30,31 @@ export interface RestoreReport {
 /** Files larger than this are not snapshotted; the transcript says so. */
 export declare const CHECKPOINT_MAX_BYTES: number;
 export declare class FileCheckpointStore {
-    /** Where blobs go, e.g. `<state>/checkpoints/<sessionId>`. */
+    /**
+     * Where blobs go: the session's `file-history/` (`SessionPaths.fileHistory`).
+     * A function is read at each turn's first snapshot, so a store that
+     * outlives a conversation switch (`/resume`, `/new`) writes into the
+     * conversation the turn belongs to, not the one the process started in.
+     */
     private readonly root;
     /** Only files under here are checkpointed. */
     private readonly cwd;
     private readonly turns;
     private current;
     private readonly skipped;
+    /** Every `file-history/` a blob was written under, so closing drops them all. */
+    private readonly roots;
     constructor(
-    /** Where blobs go, e.g. `<state>/checkpoints/<sessionId>`. */
-    root: string, 
+    /**
+     * Where blobs go: the session's `file-history/` (`SessionPaths.fileHistory`).
+     * A function is read at each turn's first snapshot, so a store that
+     * outlives a conversation switch (`/resume`, `/new`) writes into the
+     * conversation the turn belongs to, not the one the process started in.
+     */
+    root: string | (() => string), 
     /** Only files under here are checkpointed. */
     cwd: string);
+    private currentRoot;
     /** The next tool write belongs to this turn. Returns its index. */
     beginTurn(label: string): number;
     /** Whether a host path is one this store would checkpoint. */

package/dist/checkpoints/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/checkpoints/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAgD,GAAG,EAAE,MAAM,WAAW,CAAA;AAE7E,MAAM,WAAW,cAAc;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAeD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,QAAkB,CAAA;AAGnD,qBAAa,mBAAmB;IAM9B,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG;IARrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;;IAG3C,8DAA8D;IAC7C,IAAI,EAAE,MAAM;IAC7B,8CAA8C;IAC7B,GAAG,EAAE,MAAM;IAG7B,mEAAmE;IACnE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAYhC,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKjC;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IA2B3F,4CAA4C;IAC5C,IAAI,IAAI,SAAS,cAAc,EAAE;IAWjC,oFAAoF;IACpF,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCpD,4CAA4C;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;CAIzB;AAOD,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYvF;AAED,gCAAgC;AAChC,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED,OAAO,EAAE,GAAG,IAAI,cAAc,EAAE,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/checkpoints/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAgD,GAAG,EAAE,MAAM,WAAW,CAAA;AAE7E,MAAM,WAAW,cAAc;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAiBD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,QAAkB,CAAA;AAGnD,qBAAa,mBAAmB;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAhBrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;;IAGzC;;;;;OAKG;IACc,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC;IAC9C,8CAA8C;IAC7B,GAAG,EAAE,MAAM;IAG7B,OAAO,CAAC,WAAW;IAInB,mEAAmE;IACnE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAYhC,8DAA8D;IAC9D,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKjC;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IA6B3F,4CAA4C;IAC5C,IAAI,IAAI,SAAS,cAAc,EAAE;IAWjC,oFAAoF;IACpF,YAAY,IAAI,SAAS,MAAM,EAAE;IAIjC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCpD,4CAA4C;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;CAIzB;AAOD,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYvF;AAED,gCAAgC;AAChC,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED,OAAO,EAAE,GAAG,IAAI,cAAc,EAAE,CAAA"}

package/dist/checkpoints/store.js

@@ -6,7 +6,7 @@
  * Not git. A checkpoint is taken by the tool wrapper immediately before an
  * `edit` or `write` runs, whatever the repository's state, and it records
  * absence too, so a file the model created is removed on restore. Kept per
- * session under the project's private state and dropped when the session
+ * session in its `<session-id>/file-history/` directory and dropped when the session
  * closes: a checkpoint outlives a turn, not a session — the conversation
  * can be forked and resumed, and its files are the working tree's.
  */
@@ -21,14 +21,24 @@ export class FileCheckpointStore {
     turns = [];
     current;
     skipped = new Set();
+    /** Every `file-history/` a blob was written under, so closing drops them all. */
+    roots = new Set();
     constructor(
-    /** Where blobs go, e.g. `<state>/checkpoints/<sessionId>`. */
+    /**
+     * Where blobs go: the session's `file-history/` (`SessionPaths.fileHistory`).
+     * A function is read at each turn's first snapshot, so a store that
+     * outlives a conversation switch (`/resume`, `/new`) writes into the
+     * conversation the turn belongs to, not the one the process started in.
+     */
     root, 
     /** Only files under here are checkpointed. */
     cwd) {
         this.root = root;
         this.cwd = cwd;
     }
+    currentRoot() {
+        return typeof this.root === 'function' ? this.root() : this.root;
+    }
     /** The next tool write belongs to this turn. Returns its index. */
     beginTurn(label) {
         const index = this.turns.length + 1;
@@ -74,7 +84,9 @@ export class FileCheckpointStore {
         }
         let blob = null;
         if (content !== null) {
-            const dir = join(this.root, String(turn.index));
+            const dir = turn.dir ?? join(this.currentRoot(), String(turn.index));
+            turn.dir = dir;
+            this.roots.add(dirname(dir));
             await mkdir(dir, { recursive: true });
             blob = join(dir, `${turn.entries.length}.blob`);
             await writeFile(blob, content);
@@ -131,14 +143,17 @@ export class FileCheckpointStore {
         // tree no longer builds on.
         const dropped = this.turns.splice(this.turns.findIndex((t) => t.index === index));
         for (const turn of dropped) {
-            await rm(join(this.root, String(turn.index)), { recursive: true, force: true });
+            if (turn.dir)
+                await rm(turn.dir, { recursive: true, force: true });
         }
         this.current = undefined;
         return { turn: index, restored: [...restored], removed: [...removed] };
     }
     /** Drop every blob. The session is over. */
     async close() {
-        await rm(this.root, { recursive: true, force: true });
+        for (const root of new Set([...this.roots, this.currentRoot()])) {
+            await rm(root, { recursive: true, force: true });
+        }
     }
     /** A write outside any turn — a host command, say — gets a turn of its own. */
     turnForStrayWrite() {