fix(r1): round-trip reasoning_content on EVERY reasoner assistant turn (0.5.18)

0.5.15 scoped the fix too narrowly — only attached reasoning_content
when `tool_calls.length > 0`. DeepSeek's "thinking mode must be
passed back" rule applies to ANY R1-generated assistant message.

Symptom: plan approved → synthetic user message "implement it now" →
next API call 400s. The intermediate "plan submitted — awaiting
approval" plain-text R1 turn was persisted without its reasoning,
and R1 rejected the entire history the next time around.

Changes:
- assistantMessage() drops the tool_calls guard; reasoning attaches
  whenever the model emitted any (even on plain-text turns).
- Forced-summary path (no-tools fallback) now captures reasoning from
  the summary response.
- New syntheticAssistantMessage() stamps an empty-string
  reasoning_content on synthetic turns (Esc-abort notices) when the
  model is a reasoner, so R1's validator is satisfied even when no
  real reasoning exists. V3 stays clean.
- Test updated: plain-text reasoner turn now asserts reasoning
  DOES round-trip (reversed from 0.5.15's assumption).

985 tests.

CHANGELOG.md

@@ -3,6 +3,724 @@
 All notable changes to Reasonix. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.24] — 2026-04-22
+
+**Headline:** `reasonix stats` is now a cross-session cost dashboard.
+
+Every turn `reasonix chat|code|run` executes now appends one line to
+`~/.reasonix/usage.jsonl` carrying tokens + cost + the equivalent
+Claude Sonnet 4.6 cost. `reasonix stats` (no arg) rolls that log up
+into today / week / month / all-time windows:
+
+```
+Reasonix usage — /Users/you/.reasonix/usage.jsonl (2.3 KB)
+
+            turns  cache hit    cost (USD)      vs Claude     saved
+----------------------------------------------------------------------
+today           8      95.1%     $0.004821        $0.1348      96.4%
+week           34      93.8%     $0.023104        $0.6081      96.2%
+month         127      94.2%     $0.081530        $2.1452      96.2%
+all-time      342      94.0%     $0.210881        $5.8934      96.4%
+
+most used model:   deepseek-reasoner (84% of turns)
+top session:       default (214 turns)
+tracked since:     2026-04-20
+```
+
+Pillar 1's pitch (94–97% cost reduction vs Claude) turns from a
+blog number into a fact users can check on their own machine. The
+savings column is derived per turn (not synthesized) from the
+existing `claudeEquivalentCost()` helper in `src/telemetry.ts`.
+
+Back-compat: `reasonix stats <transcript>` still works — passing a
+path falls back to the old per-file summary (assistant turns + tool
+calls). No arg → dashboard.
+
+Privacy: the log contains tokens + costs + the user-chosen session
+name, nothing else. No prompts, no completions, no tool args.
+
+### Added
+
+- **`/stats` slash** — same dashboard, in-session. Reads
+  `~/.reasonix/usage.jsonl` and renders via the shared
+  `renderDashboard` pure function, so the shell command and the
+  slash stay in sync by construction.
+- **`src/usage.ts`** — `appendUsage` (best-effort JSONL write,
+  swallows disk failures so a read-only `~/` never breaks the
+  turn), `readUsageLog` (malformed-line tolerant), `aggregateUsage`
+  (rolling windows: 24h / 7d / 30d / all, plus model + session
+  histograms), `bucketCacheHitRatio`, `bucketSavingsFraction`,
+  `formatLogSize`.
+- **Wire-up** in `src/cli/ui/App.tsx` (assistant_final event) and
+  `src/cli/commands/run.ts` (CI / scripting turns land in the same
+  log as TUI turns).
+- **Upgraded `reasonix stats`**. No-arg → dashboard; transcript arg
+  → legacy per-file summary. `renderDashboard(agg, path)` is an
+  exported pure function so tests can assert the string output.
+
+### Tests (+15, suite 708 → 723)
+
+- `tests/usage.test.ts` covers: appendUsage round-trip, empty
+  log / malformed-line tolerance / parent-dir auto-creation / silent
+  write-failure (points path at a regular file), aggregateUsage
+  (empty, rolling-window bucketing, cross-record sums, byModel +
+  bySession sort + (ephemeral) grouping), bucket helpers with zero
+  denominators, renderDashboard (row labels + em-dash fallback).
+
+---
+
+## [0.4.23] — 2026-04-22
+
+**Headline:** Hooks — user-defined automation that fires at four
+well-known points in the loop. Same two-scope layout (project +
+global) as memory and skills.
+
+A hook is a shell command. Reasonix invokes it with stdin = a JSON
+envelope describing the event. The exit code drives the decision:
+`0` = pass, `2` = block (only on `PreToolUse` / `UserPromptSubmit`),
+anything else = warn (rendered inline as a yellow row, the loop
+keeps going). Block on a tool event swaps the dispatch for a
+synthetic tool result carrying the hook's stderr — the model sees
+a structured refusal instead of a silent omission, and can
+reason about what to do next.
+
+Settings file:
+
+```json
+// <project>/.reasonix/settings.json   ← committable
+// ~/.reasonix/settings.json           ← per-user
+{
+  "hooks": {
+    "PreToolUse":       [{ "match": "edit_file|write_file", "command": "bun scripts/guard.ts" }],
+    "PostToolUse":      [{ "match": "edit_file", "command": "biome format --write" }],
+    "UserPromptSubmit": [{ "command": "echo $(date +%s) >> ~/.reasonix/prompts.log" }],
+    "Stop":             [{ "command": "bun test --run", "timeout": 60000 }]
+  }
+}
+```
+
+Project hooks fire before global hooks. `match` is anchored regex
+on the tool name (`*` or omitted = match every tool); ignored for
+prompt / Stop events. Per-hook `timeout` overrides the defaults
+(5s for blocking events, 30s for logging events). The CLI loads
+both files at App mount; `/hooks` lists what's active and
+`/hooks reload` re-reads disk without tearing down the running
+loop (so the append-only log is preserved).
+
+Deliberate non-goals for v1: workflow DSL, conditional chaining,
+hook templates. Hooks are shell commands — the user already has
+a programming language, we don't need to invent one.
+
+### Added
+
+- **`src/hooks.ts`** — `loadHooks` (project + global merge),
+  `runHooks` (event filter + stdin JSON + spawn dispatch),
+  `decideOutcome` (pure exit-code → decision matrix), `matchesTool`
+  (anchored-regex name filter), `formatHookOutcomeMessage` (single
+  source of truth for the warning row text). Spawner is injectable
+  for tests; default uses `shell: true` so `&&`, pipes, env
+  expansion all behave the way they do in the user's terminal.
+- **`CacheFirstLoopOptions.hooks` + `hookCwd`**. Loop dispatches
+  `PreToolUse` (around line 866 in `src/loop.ts`) and `PostToolUse`
+  (immediately after dispatch). `loop.hooks` is mutable so
+  `/hooks reload` can swap the list without rebuilding the loop.
+- **App-level `UserPromptSubmit` + `Stop`**. `App.tsx` calls
+  `runHooks` before pushing the user message (block = drop the
+  prompt) and after `loop.step` resolves (warnings only, since the
+  turn already ended).
+- **`/hooks` slash command**. `list` (default) groups loaded hooks
+  by event with scope tags; `reload` re-reads settings.json from
+  disk via the App-provided `reloadHooks` callback.
+- **`/update` slash command**. Shows current vs the last-resolved
+  latest (piggybacks on App.tsx's mount-time background check) and
+  prints the exact shell command to upgrade. Deliberately does NOT
+  spawn `npm install` from inside the TUI — stdio:inherit into a
+  running Ink renderer corrupts the display, and on Windows the
+  currently-running binary can be locked. Users exit the session
+  and run `reasonix update` in a fresh shell.
+
+### Tests (+36, suite 672 → 708)
+
+- `tests/hooks.test.ts` — `loadHooks` (empty / project+global / array
+  order / ignore malformed entries / tolerate malformed JSON / no
+  project root → global only / path helpers), `matchesTool` (`*` /
+  anchored regex / substring rejected / malformed regex falls back
+  to no-match / non-tool events ignore match), `decideOutcome`
+  (exit 0 / exit 2 / non-zero / timeout / spawn error per event),
+  `runHooks` (filters by event+match before running, stops at first
+  block, doesn't stop on warn, stdin envelope shape, cwd routing,
+  default timeouts, per-hook timeout override), `formatHookOutcomeMessage`
+  (pass → empty / non-pass includes scope+command+detail / 60-char
+  truncation).
+- `tests/loop-hooks.test.ts` — `CacheFirstLoop` accepts a hook list,
+  default empty, `loop.hooks` is mutable, `hookCwd` defaults to
+  `process.cwd()` and honors override, no-tool turn doesn't fire
+  PreToolUse hooks.
+- `tests/slash.test.ts` — updated `suggestSlashCommands("h")` to
+  include the new `hooks` command; added 4 tests for `/update`
+  (pending / up-to-date / upgrade-available / suggest-surfaces-it).
+
+---
+
+## [0.4.22] — 2026-04-22
+
+**Headline:** Version display in the TUI header + `reasonix update`
+self-upgrade command.
+
+Two small quality-of-life additions. The stats panel now carries the
+running version (`Reasonix v0.4.22 · model …`) so users can tell at
+a glance whether they're on the latest build; a 24-hour background
+check against the npm registry quietly surfaces a yellow
+`update: X.Y.Z` nudge on the right side of the same row when a
+newer version has been published. The nudge never blocks startup —
+the fetch is bounded at 2s with a 24h on-disk cache, and any
+failure (offline, firewall, registry hiccup) is silent by design.
+
+`reasonix update` is the command form: detects whether you're
+running a global install vs an ephemeral `npx` spawn, and either
+spawns `npm install -g reasonix@latest` for the former or prints a
+cache-refresh hint for the latter. `--dry-run` prints the plan
+without executing.
+
+The `VERSION` constant now sources from `package.json` at runtime
+(walking up from `import.meta.url`) instead of a hand-maintained
+literal, so it can never drift again — it was stale at `0.4.20`
+before this release. Tests assert they stay in sync.
+
+### Added
+
+- **`src/version.ts`** — exports `VERSION`, `compareVersions`,
+  `getLatestVersion`, `isNpxInstall`, and the
+  `LATEST_CACHE_TTL_MS` / `LATEST_FETCH_TIMEOUT_MS` constants.
+  `getLatestVersion` caches to `~/.reasonix/version-cache.json`
+  (24h TTL) and returns `null` on any failure.
+- **`reasonix update`** subcommand (`src/cli/commands/update.ts`).
+  `planUpdate()` is the pure decision function, `updateCommand()`
+  is the CLI orchestrator with test seams (`fetchLatest`, `isNpx`,
+  `spawnInstall`, `write`, `exit`).
+- **StatsPanel header shows `v${VERSION}`** inline, plus an
+  `update: X` badge (yellow, bold) on the right when
+  `updateAvailable` is passed. App.tsx fires the registry check
+  in a background `useEffect` on mount; only a version strictly
+  newer than the running one flips the state.
+
+### Fixed
+
+- **Drifted `VERSION` constant.** `src/index.ts` hard-coded
+  `"0.4.20"` while `package.json` was on `0.4.21`. Replaced with a
+  re-export from `src/version.ts`, which reads the manifest on
+  first access. A regression test pins them together.
+
+### Tests (+19, suite 588 → 607)
+
+- `tests/version.test.ts` — `VERSION === package.json.version`,
+  `compareVersions` covers numeric + pre-release ordering,
+  `isNpxInstall` covers the three detection paths,
+  `getLatestVersion` covers cache hit / force-refresh / expired
+  entry / network failure / bad body / cache-write failure.
+- `tests/update-command.test.ts` — `planUpdate` returns the
+  correct action for all four decision quadrants; `updateCommand`
+  respects every seam: no-spawn on up-to-date, no-spawn on npx,
+  spawns on global-behind-latest, honors `--dry-run`, exits
+  non-zero on registry failure, surfaces npm's non-zero exit.
+
+---
+
+## [0.4.21] — 2026-04-22
+
+**Headline:** Skills — user-authored prompt packs, two-scope layout
+matching user-memory.
+
+Reasonix discovers skills under `<project>/.reasonix/skills/` (project
+scope) and `~/.reasonix/skills/` (global scope). Project wins on name
+collisions — per-repo overrides of a global skill work the way users
+expect. Deliberately NOT tied to any other tool's directory
+convention (`.claude/`, `.glm/`, etc.): Reasonix is model-agnostic at
+the conversation layer, so coupling the skill filesystem to one
+vendor would break anyone running a different backend.
+
+The pinned index (names + one-line descriptions) lives in the
+immutable system prefix; bodies stay lazy and enter the append-only
+log only when invoked — either by the model calling the new
+`run_skill` tool or by the user typing `/skill <name> [args]`. No
+DAG engine, no workflow DSL — the model reads the skill's prose and
+continues the normal tool-use loop from there. Pillar 1's cache
+invariants are preserved: adding skills grows the pinned index
+(under a 4k char cap, with a truncation marker) but never alters
+the rest of the prefix.
+
+### Added
+
+- **`src/skills.ts`** — `SkillStore` with `SkillScope` of `"project"`
+  or `"global"`, both layouts recognized (`{name}/SKILL.md` and flat
+  `{name}.md`). `applySkillsIndex` composer is pinned into
+  `applyMemoryStack` alongside REASONIX.md + user memory, receiving
+  the same `rootDir` so the project scope picks up
+  `<rootDir>/.reasonix/skills/`.
+- **`run_skill` tool** (`src/tools/skills.ts`) — read-only, returns
+  the full markdown body plus an optional forwarded `Arguments:` line.
+  Registered in `reasonix chat` (global only) and `reasonix code`
+  (project + global).
+- **`/skill` slash command** — `list` / `show <name>` / bare
+  `<name> [args]` form. The bare form injects the skill body as a
+  user turn via the same `resubmit` hook `/apply-plan` uses. Reads
+  project scope from `ctx.codeRoot`, mirroring how `/memory` behaves.
+
+### Notes
+
+- Each skill's `allowed-tools` frontmatter is parsed but **ignored**
+  in v1. Reasonix's tool namespace (`filesystem`, `shell`, `web`)
+  doesn't one-to-one map onto other clients' names; the model reads
+  the prose instructions and picks our equivalents. Will revisit
+  once the tradeoffs are clearer.
+- What we explicitly did **not** add: workflow DSL, DAG scheduler,
+  parallel branches, sub-agents. Skills are prose; the model does the
+  sequencing. This keeps single-loop + append-only + cache-first
+  intact — the architectural non-goal "no multi-agent orchestration"
+  stands.
+
+### Fixed
+
+- **`ShellConfirm` "always allow" did not take effect until relaunch.**
+  The `run_command` tool captured `extraAllowed` as a snapshot at
+  registration time, so a prefix the user approved mid-session was
+  written to `~/.reasonix/config.json` but the in-memory tool still
+  refused it — the next invocation re-triggered the confirmation
+  modal. `ShellToolsOptions.extraAllowed` now accepts a getter in
+  addition to a static array; `reasonix code` passes
+  `() => loadProjectShellAllowed(rootDir)` so the allowlist is
+  re-read from disk on every dispatch. Static-array callers keep
+  working unchanged.
+- **Windows cmd.exe built-ins (`dir`, `echo`, `type`, `ver`, …)
+  crashed with ENOENT.** These aren't standalone executables, so
+  `PATH × PATHEXT` lookup misses and `spawn dir` fails. `prepareSpawn`
+  now routes bare unresolved Windows commands through
+  `cmd.exe /d /s /c "<cmd> <args…>"` with verbatim-args + manual
+  metacharacter quoting — same wrapping strategy we already use for
+  `.cmd`/`.bat` files. Built-ins resolve correctly; genuinely unknown
+  commands get the standard "'foo' is not recognized as an internal
+  or external command" message instead of a raw spawn error.
+  Already-extensioned names (`node.exe`) and paths-with-separators
+  (`C:\tool.exe`) still pass through unwrapped so an explicit "I
+  know where this is" invocation fails loudly when it's missing.
+
+## [0.4.19] — 2026-04-22
+
+**Headline:** Windows shell hotfix + StormBreaker visibility.
+`reasonix code` now runs `npm`, `npx`, `tsc`, `yarn`, `pnpm`, `bun`,
+`pytest`, and every other `.cmd` / `.bat` wrapper on Windows — both
+under Node 18/20 (broken by missing PATHEXT resolution) and Node
+21.7.3+/24 (broken by CVE-2024-27980's prohibition on direct
+`.cmd`/`.bat` spawns with `shell: false`). Unix behavior unchanged.
+Plus: the StormBreaker anti-loop-detector no longer silently halts
+a turn — when it fires it emits a visible warning row explaining
+what was suppressed and what the user should do next, and its
+sliding window resets on each new user message so a new intent
+doesn't inherit the previous turn's repeat patterns.
+
+### Fixed
+
+- **`spawn npm ENOENT` on Windows** — `child_process.spawn` with
+  `shell: false` uses `CreateProcess`, which ignores PATHEXT. Bare
+  `npm` failed because no `npm.exe` exists — only `npm.cmd`. New
+  `resolveExecutable(cmd)` walks `PATH × PATHEXT` manually and
+  returns the full resolved path (`C:\Program Files\nodejs\npm.CMD`)
+  before handing to spawn. Keeps `shell: false` (no shell expansion
+  of piped / chained commands — the whole reason we avoided
+  `shell: true` to begin with).
+- **`spawn npm EINVAL` on Node ≥ 21.7.3 / 24** — even with the
+  resolved `.cmd` path, Node's post-CVE-2024-27980 patch refuses to
+  execute `.cmd` / `.bat` files via direct spawn. Second layer:
+  `prepareSpawn()` detects a `.cmd` / `.bat` target on Windows and
+  rewrites the invocation to `cmd.exe /d /s /c "<bin> <args…>"`
+  with `windowsVerbatimArguments: true`. Each arg is routed through
+  `quoteForCmdExe()`, which wraps in double quotes when the arg
+  contains whitespace or cmd.exe metacharacters
+  (`" & | < > ^ % ( ) , ; !`) and doubles embedded quotes per
+  cmd.exe's `""` escape rule. Arguments like `a&b` stay literal;
+  they don't become shell operators.
+
+### Added
+
+- **`resolveExecutable(cmd, opts?)`** — exported from `src/tools/shell.ts`.
+  Windows PATH × PATHEXT resolver. Opts lets tests inject `platform`,
+  `env`, and `isFile` so the Windows-specific path can be exercised
+  from a Linux CI runner without touching real fs.
+- **`prepareSpawn(argv, opts?)`** — exported. Returns the
+  `(bin, args, spawnOverrides)` tuple that runCommand should pass to
+  `child_process.spawn`. On non-Windows it's a passthrough; on
+  Windows it applies the PATHEXT lookup and the `cmd.exe` wrapping
+  when needed. Unit-tested without spawning real processes.
+- **`quoteForCmdExe(arg)`** — exported. The per-arg quoting
+  function. Round-trip tested against realistic argvs
+  (`npm install`, paths with spaces, args containing
+  `& | < > ^`, empty strings, embedded double quotes).
+
+- **Silent storm-break**. When `StormBreaker` caught a repeated
+  `(tool, args)` pattern it dropped the offending call but emitted
+  nothing user-visible beyond a small `[repair] broke 1 storm` note
+  on the assistant row. If the suppressed call was the only tool
+  call of the turn, the turn just ended — no explanation of why
+  nothing happened. Now the loop yields a dedicated `warning` event
+  (same channel as Esc-abort and budget warnings) with an
+  actionable message, distinguishing "all calls suppressed (stuck
+  retry)" from "some calls suppressed" cases.
+- **StormBreaker state bleeds across user turns**. The sliding
+  window of recent signatures persisted for the lifetime of the
+  loop, so a stuck pattern from an earlier intent could false-
+  positive against the user's legitimate new "try again with
+  different input" request. `CacheFirstLoop.step()` now calls
+  `repair.resetStorm()` on every new user turn — the window
+  repopulates naturally as the new turn's tool calls fire, and
+  genuine repeats still trip after the usual 3-in-a-row pattern.
+
+### Added
+
+- **`ToolCallRepair.resetStorm()`** — exposes StormBreaker.reset
+  through the repair facade. Called by the loop at each user turn;
+  library consumers that drive `repair.process` manually can use it
+  too if they wrap their own turn semantics.
+
+### Tests (+22, suite 566 → 588)
+
+- `tests/shell-tools.test.ts` (+21) — `resolveExecutable` on
+  non-Windows (passthrough), PATHEXT walk (first-hit ordering,
+  whitespace-tolerant PATHEXT entries), absolute-path / slash /
+  already-extensioned passthrough, empty input, missing PATH /
+  PATHEXT. `quoteForCmdExe` (simple identifiers unquoted, whitespace
+  + metachars quoted, embedded quotes doubled, empty string
+  → `""`). `prepareSpawn` (unix passthrough, `.cmd` wraps via
+  cmd.exe, `.bat` wraps too, `.exe` direct, metachar args quoted,
+  PATHEXT miss falls through).
+- `tests/repair/pipeline.test.ts` (+1) — `resetStorm` clears the
+  repeat-window so post-reset calls aren't suppressed.
+- `tests/loop.test.ts` — the iter-budget warning test refined to
+  filter by the iter-specific pattern, since identical fixture
+  calls now also trip the (correct) storm warning.
+
+### Internals
+
+- `runCommand` in `src/tools/shell.ts` now calls `prepareSpawn`
+  instead of spawning `argv[0]` directly. Every codepath that was
+  going through `spawn` still does; the `bin` / `args` /
+  `spawnOverrides` it receives are platform-normalized.
+- Existing allowlist + `readOnlyCheck` plan-mode gate + timeout /
+  output-cap / AbortSignal wiring is untouched.
+- `CacheFirstLoop.step()` now resets the StormBreaker at the top of
+  each turn AND emits a `warning` event after `repair.process()`
+  when `report.stormsBroken > 0`. The existing `repair` field on
+  `assistant_final` still carries the count for historical records
+  / transcripts.
+
+---
+
+## [0.4.18] — 2026-04-22
+
+**Headline:** Plan Mode — the model can propose a markdown plan
+autonomously for large tasks (multi-file refactors, architecture
+changes, ambiguous requests), and you can also force a read-only
+exploration phase via `/plan`. Picker shows Approve / Refine / Cancel.
+Approve pushes a synthetic "implement now" message; Refine keeps the
+model exploring; Cancel drops the plan. Designed around Pillar 1 —
+tool specs stay pinned, so the cache prefix doesn't break when plan
+mode toggles.
+
+### Added
+
+- **`submit_plan` tool** (`src/tools/plan.ts`) — registered by default
+  in `reasonix code`. Throws `PlanProposedError` carrying the plan
+  text via the new `toToolResult()` protocol on ToolRegistry. Fires
+  the picker whether or not plan mode is active — the model is
+  expected to propose plans on its own for large tasks; `/plan` is
+  the *stronger* constraint that forces the model into read-only.
+- **`/plan` slash** (code mode only) — toggles read-only plan mode.
+  `/plan on`, `/plan off`, or `/plan` to flip. While on, the registry
+  refuses non-read-only dispatch; while off, the model can still
+  propose plans autonomously via submit_plan. `/status` surfaces the
+  state; `StatsPanel` shows a red `PLAN` tag.
+- **`/apply-plan` slash** (code mode only) — force-approve fallback.
+  Clears plan mode, clears the pending-plan picker state, and
+  resubmits the implement-now synthetic via the existing `resubmit`
+  mechanism. Useful when the model wrote the plan in assistant text
+  instead of calling submit_plan, or when you want to keyboard-only
+  the approval without the picker.
+- **`ToolDefinition.readOnly` + `readOnlyCheck`** — declarative gate
+  used by `ToolRegistry.dispatch` when plan mode is on. Read tools
+  (`read_file`, `list_directory`, `search_files`, `directory_tree`,
+  `get_file_info`, `web_search`, `web_fetch`) run normally. Write
+  tools bounce with a refusal the model reads and learns from.
+  `run_command` uses a dynamic `readOnlyCheck` so allowlisted
+  invocations (`git status`, `cargo check`, `npm test`, `grep`, …)
+  still work during planning — exploration isn't gated. Non-allowlisted
+  commands refuse just like other writes.
+- **`ToolRegistry.setPlanMode(on)` / `.planMode`** — the enforcement
+  switch + accessor. Mirrored onto the UI's `planMode` React state so
+  the StatsPanel badge stays in sync.
+- **`toToolResult()` extension protocol** on Error subclasses —
+  `ToolRegistry.dispatch` calls it if present when an error is thrown,
+  serializing custom fields alongside `error`. Used by
+  `PlanProposedError` to ferry the plan text to the UI without
+  regex-scraping the error message. Falls back safely on serialization
+  failure.
+- **`PlanConfirm.tsx`** — 3-option Ink picker (Approve / Refine /
+  Cancel) with the plan rendered as **live Markdown** (via the
+  existing `Markdown` component — headings, lists, code, bold all
+  formatted, not raw text) in a cyan-bordered panel above. 2 400-char
+  rendered cap; longer plans get a "use /tool for full" truncation
+  marker. Live rows hidden while the picker is up, matching
+  `ShellConfirm`'s behavior. When the plan contains headings like
+  "Open questions", "Risks", "Assumptions", "待确认", "开放问题", "风险",
+  "未知", "假设", "不确定", the picker auto-selects the Refine option
+  by default and shows a yellow "▲ the plan has open questions —
+  pick Refine to answer them" hint above the options.
+- **`PlanRefineInput.tsx`** — inline text input that appears after
+  the user picks either **Approve** or **Refine**. Picking Approve
+  lets the user type last-minute instructions or answers to the
+  model's open questions (blank Enter = approve as-is). Picking
+  Refine requires specifics — the input collects them and includes
+  them verbatim in the synthetic sent to the model, so "refine"
+  actually means "revise with this feedback" instead of the generic
+  "try again" message the first cut sent. Esc returns to the picker
+  without resuming the loop.
+- **System-prompt guidance** (`CODE_SYSTEM_PROMPT`) — teaches the
+  model when to call submit_plan autonomously (big / risky / ambiguous
+  tasks) vs. just making the change (typos, obvious one-line fixes),
+  and how `/plan` mode adds the stronger dispatch gate on top.
+
+### Tests (+24, suite 542→566)
+
+- `tests/plan.test.ts` (+17) — ToolRegistry plan-mode gate
+  (default-off, toggle, block non-read-only, allow read-only, honor
+  `readOnlyCheck` per-args, precedence over `readOnly`, off-mode
+  noop); `toToolResult` protocol (serializes custom fields, falls
+  back on serializer failure); `PlanProposedError` carries plan +
+  STOP directive; `registerPlanTool` registers submit_plan as
+  read-only, fires picker both in and out of plan mode, rejects
+  empty plans, trims whitespace.
+- `tests/slash.test.ts` (+7) — `/plan` registry entries + required
+  commands check; `/plan` toggle / on / off / true / false / 0 / 1;
+  `/plan` info text explicit about the stronger-constraint
+  relationship; `/apply-plan` code-mode gating; `/apply-plan` flips
+  mode + clears pending + resubmits; works without optional
+  `clearPendingPlan` callback; `/status` plan-mode line appears
+  iff on.
+
+### Internals
+
+- `src/tools/filesystem.ts` — read_file / list_directory /
+  directory_tree / search_files / get_file_info tagged readOnly.
+- `src/tools/shell.ts` — run_command gets `readOnlyCheck` tied to
+  the existing `isAllowed` check + `allowAll` escape hatch.
+- `src/tools/web.ts` — web_search / web_fetch tagged readOnly.
+- `src/cli/commands/code.tsx` — `registerPlanTool(tools)` added after
+  the filesystem and shell registrations so the tool is always in
+  the pinned spec list (prefix cache stays stable across
+  plan-mode toggles).
+- `src/index.ts` — re-exports `PlanProposedError`, `registerPlanTool`,
+  `PlanToolOptions` for library consumers.
+
+---
+
+## [0.4.17] — 2026-04-22
+
+**Headline:** Project memory — drop a `REASONIX.md` in your project
+root and its contents are pinned into the immutable-prefix system
+prompt for every session in that directory. Persistent project
+context (house conventions, domain glossary, gotchas the model keeps
+forgetting) without eating per-turn context budget, and the prefix
+cache stays warm as long as the file is stable.
+
+### Added
+
+- **`src/project-memory.ts`** — `readProjectMemory(rootDir)`,
+  `applyProjectMemory(basePrompt, rootDir)`, `memoryEnabled()`. One
+  source, one mental model: `REASONIX.md` at the project root, read
+  once at session start, appended as a fenced "# Project memory"
+  block after the base system prompt. Truncates at 8 000 chars
+  (≈ 2k tokens) with a visible marker; `.gitignore` gets 2 000
+  because it's a constraint dump, memory gets more headroom because
+  it's deliberate instructions. Re-exported from `src/index.ts` for
+  library consumers.
+- **Auto-applied at every CLI entry** — top-level `reasonix`,
+  `reasonix chat`, `reasonix run`, and `reasonix code` all honor
+  the file. `code` resolves it against the rooted directory; the
+  others against `process.cwd()` at launch.
+- **`/memory` slash command** — prints the resolved file path +
+  full contents (or a how-to stub when absent), so you can verify
+  what the model is actually seeing without reading the system
+  prompt blob. Reminds you changes take effect on the next launch
+  or `/new`; the system prompt is hashed once per session to keep
+  the prefix cache warm.
+- **`REASONIX_MEMORY=off|false|0` env opt-out** — for CI or
+  intentional offline reproducibility. `rm REASONIX.md` is the
+  other opt-out.
+
+### Tests (+25, suite 517→542)
+
+- `tests/project-memory.test.ts` (+15) — absent / empty /
+  whitespace-only / normal / oversized file paths;
+  `memoryEnabled` env-value matrix; `applyProjectMemory` no-ops on
+  missing/disabled; determinism (identical input ⇒ identical
+  output, cache-prefix-safe); `codeSystemPrompt` stacks base →
+  memory → .gitignore in the right order when all three exist.
+- `tests/slash.test.ts` (+4) — `/memory` prints the how-to when no
+  file, contents when present, "disabled" when env-off, "no root"
+  when `memoryRoot` is absent from the SlashContext. Registry
+  check updated to require `/memory`.
+
+---
+
+## [0.4.16] — 2026-04-22
+
+**Headline:** Native `run_command` shell tool so the model can run
+its own tests and verify its work (Claude Code / Aider parity).
+3-choice picker for every unknown command — "run once", "always
+allow in this project" (persists to `~/.reasonix/config.json`), or
+"deny". Plus a session picker on startup so `reasonix code` stops
+silently resuming the last conversation, and a Windows backspace fix.
+
+### Added
+
+- **`src/tools/shell.ts`** — `run_command(command, timeoutSec?)`
+  registered by default in `reasonix code`. Read-only / testing
+  commands (`git status`, `ls`, `cat`, `grep`, `rg`, `npm test`,
+  `pytest`, `cargo test`, `cargo check`, `cargo clippy`, `go test`,
+  `deno test`, `bun test`, `ruff`, `mypy`, `npx tsc --noEmit`,
+  `npx biome check`, language `--version` probes) auto-run. Anything
+  else goes through the ShellConfirm picker. 60s default timeout,
+  32k-char output cap. `shell: false` in the child_process spawn
+  so the model can't pipe / redirect / chain its way past the
+  allowlist.
+- **`src/cli/ui/ShellConfirm.tsx`** — 3-option SingleSelect modal
+  that renders when the model asks to run a non-allowlisted
+  command. Borders + color so it's impossible to miss. Arrow-key
+  navigation; Enter confirms. No `y/n` hotkey — too easy to trigger
+  by accident mid-typing.
+- **`src/cli/ui/SessionPicker.tsx`** — on `reasonix chat` /
+  `reasonix code` startup, if the session has prior messages, show
+  a 3-option picker: **New** (default, safer), **Resume** (continue
+  where you left off), **Delete and start new**. Flags `--resume`
+  / `--new` bypass the picker for CI / muscle-memory.
+- **Per-project persistent allowlist** — `config.projects[<abs>].shellAllowed`
+  stores prefixes the user approved via "always allow". On next
+  `reasonix code` in that dir they auto-run. Helpers
+  `loadProjectShellAllowed` / `addProjectShellAllowed` exported.
+
+### Fixed
+
+- **Backspace dead on some Windows terminals.** Certain Git Bash /
+  winpty combos report plain Backspace with `key.delete=true` and
+  `key.backspace=false`; the 0.4.15 cursor reducer split the two
+  and treated `delete` as forward-delete, which is a no-op when the
+  cursor is at the end of the buffer — so pressing Backspace did
+  nothing and Ctrl+Backspace (reported differently) was the only
+  way to delete. Now both flags collapse to backward-delete, plus
+  raw DEL (0x7f) and BS (0x08) bytes in `key.input` are honored as
+  backspace too.
+
+### Tests (+43, suite 474→517)
+
+- `tests/shell-tools.test.ts` (+27) — tokenizer (quoting, escapes,
+  unclosed-quote rejection); allowlist matching (exact / prefix /
+  whitespace normalization / extras); `runCommand` against real
+  child processes (stdout, stderr, cwd, timeout kill, output cap,
+  empty-command rejection); registry dispatch (auto-run, refusal
+  via `NeedsConfirmationError`, `allowAll: true` bypass);
+  `formatCommandResult`; `NeedsConfirmationError` name/message
+  invariants (no stale `/apply-shell` reference).
+- `tests/shell-confirm.test.ts` (+4) — `derivePrefix` picks one or
+  two tokens based on known wrappers and normalizes whitespace.
+- `tests/config.test.ts` (+3) — `loadProjectShellAllowed` defaults
+  to `[]`; `addProjectShellAllowed` persists and dedups per-project;
+  ignores empty prefixes.
+- `tests/multiline-keys.test.ts` (+2) — raw DEL/BS bytes are
+  treated as backspace; `key.delete` unified with `key.backspace`.
+
+---
+
+## [0.4.15] — 2026-04-22
+
+**Headline:** Web search + fetch tools (on by default, zero
+configuration) plus real cursor editing in the prompt box (←/→,
+Backspace/Delete mid-string, multi-line ↑/↓ navigation).
+
+### Fixed
+
+- **PromptInput was append-only** — cursor was always pinned to
+  the end of the buffer, so the only way to fix a typo was
+  backspacing back through everything after it. Now:
+  - `←` / `→` move the cursor one column (clamped to buffer).
+  - `↑` / `↓` move across lines in a multi-line buffer, preserving
+    column when possible, clamping when the target line is shorter.
+  - `Ctrl+A` / `Ctrl+E` jump to start / end of the current line.
+  - `Backspace` deletes the char before the cursor; `Delete`
+    deletes the char under the cursor.
+  - Printable input inserts at the cursor (including multi-char
+    paste bursts).
+  - `Shift+Enter` / `Ctrl+J` insert a newline at the cursor.
+- **History recall no longer steals arrow keys from mid-edit.**
+  `↑` / `↓` only trigger prior-prompt recall when the buffer is
+  empty. A non-empty buffer keeps the arrows for cursor motion so
+  typed text isn't clobbered.
+
+### Added
+
+Web search + fetch tools are registered by default on `reasonix
+chat` and `reasonix code`. The model calls `web_search` /
+`web_fetch` on its own whenever a question needs fresher info than
+its training data. Backed by **Mojeek**'s public search page — no
+API key, no signup. Same Cache-First + repair + context-safety
+plumbing as every other tool.
+
+Implementation note: the first cut of this feature used DuckDuckGo,
+but a live probe from the dev machine confirmed DDG now serves
+HTTP 202 anti-bot pages for every unauthenticated POST regardless
+of UA. Mojeek is an independent-index engine that's been stable
+against the same probe (3/3 success on three queries spaced 3s
+apart). Real-browser `User-Agent` string avoids Mojeek's
+fast-path scraper filter.
+
+
+- **`src/tools/web.ts`** — two functions + one registration helper:
+  - `webSearch(query, opts?)` — fetches DDG's HTML endpoint, parses
+    ranked results (title + url + snippet). `topK` is clamped to
+    [1, 10]. Parser decodes DDG's `uddg=<url>` redirect wrapper and
+    common HTML entities.
+  - `webFetch(url, opts?)` — HTTP GET + HTML-to-text extraction
+    (scripts/styles/nav/footer/aside/svg stripped, paragraph breaks
+    preserved, entities decoded). 15s timeout, 32k-char cap (matches
+    tool-result budget), forwards caller's AbortSignal so Esc during
+    a long fetch is honored.
+  - `registerWebTools(registry, opts?)` — registers both as
+    ToolRegistry entries the model can invoke. Tool descriptions
+    guide the model to call search whenever training data might be
+    stale.
+- **`ReasonixConfig.search`** + **`searchEnabled()`** — a simple
+  boolean. Default on. Turn off with `search: false` in config or
+  `REASONIX_SEARCH=off|false|0` in env. No API keys, no provider
+  picker — one switch.
+- **Auto-registered in chat/code.** `reasonix chat` and
+  `reasonix code` register `web_search` + `web_fetch` by default.
+  Zero setup: after the normal wizard, the model can already reach
+  the web.
+
+### Tests (+18, suite 444→462)
+
+- `tests/web-tools.test.ts` (+13) — htmlToText strips
+  scripts/styles/nav/footer + decodes entities + collapses
+  whitespace; `parseDuckDuckGoResults` decodes redirect URLs + entities
+  + returns empty on unexpected markup; `webSearch` hits the DDG
+  endpoint with a browsery UA, respects topK, clamps to [1, 10],
+  throws on non-2xx; `formatSearchResults` renders the expected
+  layout; `registerWebTools` registers both verbs; `web_fetch` refuses
+  non-http(s) URLs; `webFetch` extracts title + body, truncates at
+  the cap with a visible marker, surfaces 404s.
+- `tests/config.test.ts` (+5) — `searchEnabled` defaults to true;
+  honors `search: false` in file; honors `REASONIX_SEARCH=off|false|0`;
+  stays true for unrelated env values; env off beats config true.
+
+---
+
 ## [0.4.14] — 2026-04-22
 
 **Headline:** Render-load reductions for Windows terminals where

README.md

@@ -1,3 +1,11 @@
+<p align="center">
+  <img src="docs/logo.svg" alt="Reasonix — DeepSeek-native agent framework" width="640"/>
+</p>
+
+<p align="center">
+  <em>Cache-first agent loop for DeepSeek V3 &amp; R1 — Ink TUI, MCP first-class, no LangChain.</em>
+</p>
+
 # Reasonix
 
 [![npm version](https://img.shields.io/npm/v/reasonix.svg)](https://www.npmjs.com/package/reasonix)
@@ -6,8 +14,9 @@
 [![downloads](https://img.shields.io/npm/dm/reasonix.svg)](https://www.npmjs.com/package/reasonix)
 [![node](https://img.shields.io/node/v/reasonix.svg)](./package.json)
 
-**A DeepSeek-native AI coding assistant in your terminal.** Ink TUI. MCP
-first-class. No LangChain.
+**A DeepSeek-native AI coding agent in your terminal.** Edits files as
+reviewable SEARCH/REPLACE blocks. Ink TUI. MCP first-class. No
+LangChain.
 
 ---
 
@@ -16,60 +25,27 @@ first-class. No LangChain.
 **1. Get a DeepSeek API key.** Free credit on signup:
 <https://platform.deepseek.com/api_keys>
 
-**2. Run it.** No install needed.
-
-```bash
-npx reasonix
-```
-
-First run walks you through a 30-second wizard:
-
-- paste your API key (saved to `~/.reasonix/config.json`)
-- pick a preset — `fast` (cheap chat, default), `smart` (+R1 reasoning), `max` (+self-consistency branching)
-- multi-select MCP servers from a catalog (filesystem, memory, github, puppeteer, …)
-
-Every run after that drops you straight into chat.
-
-**3. Inside the chat.** Type anything and hit Enter. Type `/help` to see
-every command. The status bar at the top shows cache hit %, cost so far,
-balance, and context usage. Press `Esc` to cancel whatever is running.
-
-```
-reasonix › explain what this project does
-assistant
-  …streams R1 reasoning into a dim preview, then writes the answer…
-status bar: cache hit 92% · cost $0.001 · ctx 8k/131k (6%) · balance 12.34 CNY
-```
-
-Requires Node ≥ 18. Works on macOS, Linux, Windows (Git Bash + PowerShell).
-
----
-
-## Using `reasonix code` — your terminal pair programmer
-
-Scoped to the directory you launch from. The model has native
-`read_file` / `write_file` / `edit_file` / `list_directory` /
-`search_files` / `directory_tree` / `get_file_info` /
-`create_directory` / `move_file` tools, all sandboxed — any path that
-resolves outside the launch root (including `..` and symlink escapes)
-is refused.
+**2. Point it at a project.** No install needed.
 
 ```bash
 cd my-project
 npx reasonix code
 ```
 
-### Walkthrough: fix a bug
+First run walks you through a 30-second wizard (paste API key → pick
+preset → multi-select MCP servers). Every run after that drops you
+straight in.
+
+**3. Ask it to edit.** The model proposes edits as SEARCH/REPLACE
+blocks — nothing hits disk until you `/apply`.
 
 ```
-reasonix code › users.ts 里 findByEmail 对大小写敏感导致登录失败，帮我改成大小写不敏感
+reasonix code › users.ts 里 findByEmail 对大小写敏感导致登录失败，帮我改
 
 assistant
-  ▸ R1 reasoning · 1243 chars of thought
   ▸ tool<search_files> → src/users.ts, src/users.test.ts
   ▸ tool<read_file>    → (src/users.ts, 412 chars)
-  ▸ tool<read_file>    → (src/users.test.ts, 820 chars)
-  ▸ 找到了。findByEmail 直接用 === 比对。我把查询和存储都规范化为小写，并补上一条测试。
+  ▸ 找到了。findByEmail 直接用 === 比对。改成小写规范化并补一条测试。
 
 src/users.ts
 <<<<<<< SEARCH
@@ -79,49 +55,34 @@ src/users.ts
   return users.find(u => u.email.toLowerCase() === needle);
 >>>>>>> REPLACE
 
-src/users.test.ts
-<<<<<<< SEARCH
-  it("finds by email", () => {
-    expect(findByEmail("[email protected]")).toBeDefined();
-  });
-=======
-  it("finds by email", () => {
-    expect(findByEmail("[email protected]")).toBeDefined();
-  });
+▸ 1 pending edit across 1 file — /apply to write · /discard to drop
 
-  it("is case-insensitive", () => {
-    expect(findByEmail("[email protected]")).toBeDefined();
-  });
->>>>>>> REPLACE
-
-▸ 2 pending edits across 2 files — /apply to write · /discard to drop
+reasonix code › /apply
+▸ ✓ applied src/users.ts
 ```
 
-**At this point nothing has been written to disk.** You have three
-options:
+Requires Node ≥ 20.10. macOS, Linux, Windows (PowerShell / Git Bash /
+Windows Terminal). Press `Esc` anytime to abort; `/help` for the full
+command list.
 
-- `/apply` — commit the pending blocks. You'll see `✓ applied
-  src/users.ts` and `✓ applied src/users.test.ts`. A snapshot of the
-  pre-edit file is kept so `/undo` can roll back.
-- `/discard` — throw the blocks away without writing.
-- Keep chatting — ask for adjustments. Say "also cover the empty
-  string case" and the model proposes another block set.
+---
 
-After applying:
+## `reasonix code` — pair programmer in your terminal
 
-```
-reasonix code › /commit "fix: findByEmail case-insensitive"
-▸ git add -A && git commit -m "fix: findByEmail case-insensitive"
-  [main a1b2c3d] fix: findByEmail case-insensitive
-```
-
-`/commit` runs `git add -A && git commit -m ...` from the sandbox root.
+Scoped to the directory you launch from. The model has native
+`read_file` / `write_file` / `edit_file` / `list_directory` /
+`search_files` / `directory_tree` / `get_file_info` /
+`create_directory` / `move_file` tools, all sandboxed — any path that
+resolves outside the launch root (including `..` and symlink escapes)
+is refused. Plus `run_command` with a read-only allowlist; anything
+state-mutating (`npm install`, `git commit`, …) is gated behind a
+confirmation picker.
 
 ### Walkthrough: explore before editing
 
 For "what does this code do?" questions the model uses the read-side
-tools and replies in prose — no SEARCH/REPLACE blocks, no file writes.
-Ask to change something only when you mean it:
+tools and replies in prose — no SEARCH/REPLACE blocks, no file
+writes. Ask to change something only when you mean it:
 
 ```
 reasonix code › 这个项目的路由是怎么组织的？
@@ -132,10 +93,53 @@ assistant
     nested routes 写子路径，最后 …
 ```
 
-If the SEARCH text doesn't match the file byte-for-byte, `edit_file`
-refuses the edit loudly rather than fuzzy-matching. The model sees the
-error and retries with the correct search text — silent wrong edits are
-worse than visible rejections.
+If an `edit_file` SEARCH block doesn't match the file byte-for-byte,
+the edit is refused loudly rather than fuzzy-matched. The model sees
+the error and retries — silent wrong edits are worse than visible
+rejections.
+
+### Plan mode — review before executing
+
+For anything bigger than a typo, the model is encouraged to propose a
+markdown plan first. You'll see a picker with **Approve / Refine /
+Cancel**:
+
+```
+reasonix code › 把 auth 从 JWT 迁移到 session cookies
+
+▸ plan submitted — awaiting your review
+────────────────────────────────────────
+## Summary
+Swap JWT middleware for session cookies, keep user table intact.
+
+## Files
+- src/auth/middleware.ts — replace `verifyJwt` with `readSession`
+- src/auth/session.ts — new file, in-memory store + signed cookie
+- src/routes/login.ts — return Set-Cookie instead of a token
+- tests/auth/*.test.ts — update fixtures
+
+## Risks
+- Existing logged-in users get logged out (no migration).
+- Session store is in-memory; restart clears sessions.
+────────────────────────────────────────
+  ▸ Approve and implement
+    Refine — explore more
+    Cancel
+```
+
+**Force it** with `/plan` — enters an explicit read-only phase where
+the model *must* submit a plan before any edit or non-allowlisted
+shell call will execute. Use for high-stakes changes you want to
+audit before the model touches disk. `/plan off` or picker
+Approve/Cancel exits.
+
+### `/commit` — stage + commit in one step
+
+```
+reasonix code › /commit "fix: findByEmail case-insensitive"
+▸ git add -A && git commit -m "fix: findByEmail case-insensitive"
+  [main a1b2c3d] fix: findByEmail case-insensitive
+```
 
 ### Things to try
 
@@ -146,17 +150,215 @@ worse than visible rejections.
 - `/undo` — roll back the last applied edit batch.
 - `/new` — start fresh in the same directory without losing the
   session file.
-- Drop `--no-session` for an ephemeral session that doesn't persist.
+- `npx reasonix code --preset max` — R1 + 3-way self-consistency
+  branching for gnarly refactors.
+- `npx reasonix code src/` — narrower sandbox (only `src/` is
+  writable).
+- `npx reasonix code --no-session` — ephemeral; nothing saved.
+
+### `reasonix stats` — how much did you actually save?
+
+Every turn `reasonix chat|code|run` runs appends a compact record
+(tokens + cost + what Claude Sonnet 4.6 would have charged) to
+`~/.reasonix/usage.jsonl`. `reasonix stats` with no args rolls that
+log into today / week / month / all-time windows:
+
+```
+Reasonix usage — /Users/you/.reasonix/usage.jsonl
+
+            turns  cache hit    cost (USD)      vs Claude     saved
+----------------------------------------------------------------------
+today           8      95.1%     $0.004821        $0.1348      96.4%
+week           34      93.8%     $0.023104        $0.6081      96.2%
+month         127      94.2%     $0.081530        $2.1452      96.2%
+all-time      342      94.0%     $0.210881        $5.8934      96.4%
+```
+
+Privacy: only tokens, costs, and the session name you chose land
+in the file. No prompts, no completions, no tool arguments.
+`reasonix stats <transcript>` keeps the old per-file summary
+(assistant turns + tool calls) for scripts that already use it.
+
+### Staying current
+
+The panel header shows the running version next to `Reasonix` (e.g.
+`Reasonix v0.4.22 · model …`). A quiet 24-hour background check against
+the npm registry surfaces a yellow `update: X.Y.Z` on the right side
+of the same row when a newer version has been published. No blocking,
+no nagging — the check runs once per day max and is silent on failure
+(offline, firewall, etc.).
 
 ```bash
-npx reasonix code src/           # narrower sandbox (only src/ is writable)
-npx reasonix code --no-session   # ephemeral — nothing saved to disk
-npx reasonix code --preset max   # R1 reasoning + 3-way self-consistency
+reasonix update             # print current vs latest, run `npm i -g reasonix@latest`
+reasonix update --dry-run   # print the plan without running anything
 ```
 
+Running via `npx`? The command detects that and prints a
+cache-refresh hint instead — npx picks up the newest version on
+its next invocation automatically.
+
+### Project conventions — `REASONIX.md`
+
+Drop a `REASONIX.md` in the project root and its contents are pinned
+into the system prompt every launch. Committable team memory — house
+conventions, domain glossary, things the model keeps forgetting:
+
+```bash
+cat > REASONIX.md <<'EOF'
+# Notes for Reasonix
+- Use snake_case for new Python modules; legacy camelCase modules keep their style.
+- `cargo check` is in the auto-run allowlist; full `cargo test` needs confirmation.
+- The `api/` dir mirrors `backend/` — keep schemas in sync.
+EOF
+```
+
+Re-launch (or `/new`) to pick it up; the prefix is hashed once per
+session to keep the DeepSeek cache warm. `/memory` prints what's
+currently pinned. `REASONIX_MEMORY=off` disables every memory source
+for CI / offline repro.
+
+### User memory — `~/.reasonix/memory/`
+
+A second, **private per-user** memory layer lives under your home
+directory. Unlike `REASONIX.md` it's never committed, and the model
+can write to it itself via the `remember` tool. Two scopes:
+
+- `~/.reasonix/memory/global/` — cross-project (your preferences,
+  tooling).
+- `~/.reasonix/memory/<project-hash>/` — scoped to one sandbox root
+  in `reasonix code` (decisions, local facts, per-repo shortcuts).
+
+Each scope keeps an always-loaded `MEMORY.md` index of one-liners
+plus zero or more `<name>.md` detail files (loaded on demand via
+`recall_memory`). Writes land immediately; pinning into the system
+prompt takes effect on next `/new` or launch so the cache prefix
+stays stable for the current session.
+
+```
+reasonix code › 我用 bun 而不是 npm，请以后都用 bun 跑构建
+
+assistant
+  ▸ tool<remember> → project/bun_build saved
+    "Build command on this machine is `bun run build`"
+```
+
+**Slash**: `/memory` · `/memory list` · `/memory show <name>` ·
+`/memory forget <name>` · `/memory clear <scope> confirm`.
+**Model tools**: `remember(type, scope, name, description, content)` ·
+`forget(scope, name)` · `recall_memory(scope, name)`.
+
+Project scope is only available inside `reasonix code` (needs a real
+sandbox root to hash); plain `reasonix` gets the global scope only.
+
+### Skills — user-authored prompt packs
+
+Skills are prose instruction blocks you drop on disk. Reasonix pins
+their names + one-line descriptions into the system prompt; the
+model can call `run_skill({name: "..."})` on its own when a match
+fits, or you can type `/skill <name> [args]` to run one manually.
+
+Two scopes, same layout as user memory:
+
+- `<project>/.reasonix/skills/` — per-project skills (commit them to
+  share with your team, or add to `.gitignore` for personal drafts).
+- `~/.reasonix/skills/` — global skills available everywhere.
+
+Either layout works: `<name>/SKILL.md` (preferred — can bundle
+additional assets alongside) or flat `<name>.md`.
+
+```markdown
+---
+name: review
+description: Review uncommitted changes and flag risks
+---
+
+Run `git diff` on staged and unstaged changes. Summarize what each
+hunk does, call out potential regressions, and list files that might
+need additional tests. Don't propose edits unless I ask.
+```
+
+Use it:
+
+```
+reasonix code › /skill review
+▸ running skill: review
+assistant
+  ▸ tool<run_command> → git diff --cached
+  ▸ 3 改动，1 个需要回归测试 …
+```
+
+Or let the model pick autonomously — because the skill's name +
+description are pinned in the prefix, asking "帮我看下未提交的改动有没
+有风险" triggers `run_skill({name: "review"})` without you typing the
+slash command.
+
+**Slash**: `/skill` (list) · `/skill show <name>` · `/skill <name>
+[args]` (inject body as user turn).
+
+**Deliberately not tied** to any other client's directory convention
+(`.claude/skills`, etc.) — Reasonix is model-agnostic at the
+conversation layer. Any SKILL.md you author works; the body is
+prose, so skills authored for other tools usually port over unchanged
+(Reasonix's tool names differ — `filesystem` / `shell` / `web` — but
+the model reads the instructions and picks our equivalents).
+
+### Hooks — automate around tool calls and turns
+
+Drop a `settings.json` under `.reasonix/` (project or `~/`) and
+Reasonix will fire shell commands at four well-known points in
+the loop: before a tool runs, after a tool returns, before your
+prompt reaches the model, and after the turn ends.
+
+```json
+// <project>/.reasonix/settings.json   ← committable
+// ~/.reasonix/settings.json           ← per-user
+{
+  "hooks": {
+    "PreToolUse":       [{ "match": "edit_file|write_file", "command": "bun scripts/guard.ts" }],
+    "PostToolUse":      [{ "match": "edit_file", "command": "biome format --write" }],
+    "UserPromptSubmit": [{ "command": "echo $(date +%s) >> ~/.reasonix/prompts.log" }],
+    "Stop":             [{ "command": "bun test --run", "timeout": 60000 }]
+  }
+}
+```
+
+Each hook is a shell command. Reasonix invokes it with stdin = a
+JSON envelope describing the event:
+
+```json
+{ "event": "PreToolUse", "cwd": "/path/to/project",
+  "toolName": "edit_file", "toolArgs": { "path": "src/x.ts", "..." } }
+```
+
+Exit code drives the decision:
+
+- **0** — pass; loop continues normally
+- **2** — block (only on `PreToolUse` / `UserPromptSubmit`); the
+  hook's stderr becomes the synthetic tool result the model sees,
+  or the prompt is dropped entirely
+- **anything else** — warn; loop continues, stderr renders as a
+  yellow row inline
+
+`match` is anchored regex on the tool name; `*` or omitted matches
+every tool. Project hooks fire before global hooks. Default
+timeouts: 5s for blocking events, 30s for logging events; per-hook
+`timeout` overrides.
+
+**Slash**: `/hooks` (list active hooks) · `/hooks reload` (re-read
+`settings.json` from disk without losing your session).
+
+### Staying current from inside the TUI
+
+`/update` inside a running session shows your current version, the
+last-resolved latest version (from the quiet 24h background check),
+and the shell command to run. The slash does *not* spawn
+`npm install` — stdio:inherit into a running Ink renderer corrupts
+the display. Exit the session and run `reasonix update` in a
+fresh shell when you actually want to install.
+
 ---
 
-## Using `reasonix` — general chat
+## `reasonix` — also works as general chat
 
 Same TUI, no filesystem tools unless you opt in via MCP. Good for
 drafting, Q&A, schema design, architecture discussions, or driving
@@ -165,102 +367,74 @@ your own MCP servers. Sessions persist per name under
 
 ```bash
 npx reasonix                             # uses saved config + wizard-selected MCP
-npx reasonix --preset smart              # one-shot override
-npx reasonix --session design            # named session
-npx reasonix --session design            # resume it later — history intact
+npx reasonix --preset smart              # reasoner + R1 harvest for this run
+npx reasonix --session design            # named session — resume later with --session design
 ```
 
-### Walkthrough: a multi-turn session with R1 reasoning
-
-```
-reasonix › /preset smart
-▸ switched to smart · model deepseek-reasoner · harvest on · branch off
-
-reasonix › 我要给一个 Flutter 应用设计限时折扣的弹窗展示规则。目标：
-      每天首次打开时弹一次，连续弹 3 天后休眠 7 天。怎么实现？
-
-assistant
-  ▸ R1 reasoning · 2410 chars of thought
-  ‹ subgoals (3): 持久化展示计数 · 判断是否过了 24h · 休眠窗口判断
-  ‹ hypotheses (2): SharedPreferences 存计数 · lastShownAt 时间戳
-  ‹ uncertainties (1): 用户换设备后重置的策略
-
-  建议数据模型：
-    lastShownAt: DateTime
-    consecutiveShows: int (0..3)
-    sleepUntil: DateTime?
-  …
-```
-
-`/think` dumps the full R1 thought trace; `/status` shows the current
-model / flags / context use; `/retry` re-samples the same prompt with
-a fresh random seed (useful when the first answer missed something).
-
-### Walkthrough: attach MCP tools on the fly
+Bridge your own MCP servers on the fly:
 
 ```bash
-# Attach the official filesystem server sandboxed to /tmp/scratch,
-# plus a remote knowledge-base over SSE.
 npx reasonix \
-  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/scratch" \
+  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
   --mcp "kb=https://mcp.example.com/sse"
 ```
 
-Inside the chat:
-
-```
-reasonix › /mcp
-▸ fs (stdio, 11 tools)   fs_read_file · fs_list_directory · fs_write_file · …
-▸ kb (sse,   4 tools)    kb_search · kb_get · kb_list_collections · kb_stat
-
-reasonix › 在 /tmp/scratch 下把所有 .log 文件里含 "ERROR" 的行收集到 errors.txt
-assistant
-  ▸ tool<fs_search_files> → 4 matches
-  ▸ tool<fs_read_file>    → …
-  ▸ tool<fs_write_file>   → wrote 2.4 KB to errors.txt
-  ▸ 已写入 errors.txt — 共 38 行，分布在 4 个源文件中。
-```
-
 MCP tools go through the same Cache-First + repair + context-safety
-plumbing as native tools, including the 32k result cap and live
-progress-notification rendering.
-
-### When to use `reasonix` vs `reasonix code`
-
-| situation | command |
-|---|---|
-| Editing files in the current project | `reasonix code` |
-| Exploring a project without writing files | `reasonix code` (it only writes on `/apply`) |
-| Design / architecture / research chat | `reasonix` |
-| Driving your own MCP servers | `reasonix --mcp "..."` |
-| One-shot question, no TUI | `reasonix run "..."` |
-| Reproducing a prior session / benchmark | `reasonix replay path.jsonl` |
+plumbing as native tools — 32k result cap, live progress-notification
+rendering, retries.
 
 ---
 
 ## Commands inside the session
 
+**Core**
+
 | command | what it does |
 |---|---|
-| `/help` | full command reference with hints |
+| `/help` · `/?` | full command reference with hints |
 | `/status` | current model · flags · context · session |
+| `/new` · `/reset` | fresh conversation in the same session |
+| `/clear` | clear visible scrollback only (log kept) |
+| `/retry` | truncate and resend your last message (fresh sample) |
+| `/exit` · `/quit` | quit |
+
+**Model**
+
+| command | what it does |
+|---|---|
 | `/preset <fast\|smart\|max>` | one-tap bundle (model + harvest + branch) |
 | `/model <id>` | switch DeepSeek model (`deepseek-chat`, `deepseek-reasoner`) |
 | `/harvest [on\|off]` | toggle R1 plan-state extraction |
 | `/branch <N\|off>` | run N parallel samples per turn, pick best (N ≥ 2) |
+| `/think` | dump the last turn's full R1 reasoning |
+
+**Context & tools**
+
+| command | what it does |
+|---|---|
 | `/mcp` | list attached MCP servers and their tools |
 | `/tool [N]` | dump the Nth tool call's full output (1 = latest) |
-| `/think` | dump the last turn's full R1 reasoning |
-| `/retry` | truncate and resend your last message (fresh sample) |
 | `/compact [cap]` | shrink oversized tool results in the log |
+
+**Memory & skills**
+
+| command | what it does |
+|---|---|
+| `/memory` | show pinned memory (REASONIX.md + ~/.reasonix/memory) |
+| `/memory list` · `show <name>` · `forget <name>` · `clear <scope> confirm` | manage the store |
+| `/skill` · `/skill list` | list discovered skills (project + global) |
+| `/skill show <name>` | dump one skill's body |
+| `/skill <name> [args]` | run a skill (inject body as user turn) |
+
+**Sessions**
+
+| command | what it does |
+|---|---|
 | `/sessions` | list saved sessions (current marked with `▸`) |
 | `/forget` | delete the current session from disk |
-| `/new` (alias `/reset`) | start a fresh conversation in the same session |
-| `/clear` | clear visible scrollback only (log kept) |
 | `/setup` | reconfigure (exit and run `reasonix setup`) |
-| `/exit` | quit |
 
-Additional commands in `reasonix code`:
+**Code mode only** (`reasonix code`)
 
 | command | what it does |
 |---|---|
@@ -268,32 +442,36 @@ Additional commands in `reasonix code`:
 | `/discard` | drop the pending edit blocks without writing |
 | `/undo` | roll back the last applied edit batch |
 | `/commit "msg"` | `git add -A && git commit -m "msg"` |
+| `/plan [on\|off]` | toggle read-only plan mode |
+| `/apply-plan` | force-approve a pending plan |
 
-**Keyboard:**
+**Keyboard**
 
 - `Enter` — submit
-- `Shift+Enter` / `Ctrl+J` — newline (multi-line paste also supported; `\` + Enter as a portable fallback)
-- `↑ / ↓` — walk prompt history while idle; navigate slash-autocomplete matches
+- `Shift+Enter` / `Ctrl+J` — newline (multi-line paste also supported;
+  `\` + Enter as a portable fallback)
+- `↑` / `↓` — walk prompt history while idle; navigate slash-autocomplete
 - `Tab` / `Enter` on a `/foo` prefix — accept the highlighted suggestion
-- `Esc` — abort the current turn (stops the API call, cancels any in-flight tool, rejects pending MCP requests)
+- `Esc` — abort the current turn (stops the API call, cancels any
+  in-flight tool, rejects pending MCP requests)
 - `y` / `n` on confirm prompts — hotkey accept / reject
 
 ---
 
 ## Sessions and safety nets
 
-- Sessions live as JSONL under `~/.reasonix/sessions/<name>.jsonl` (per
-  directory for `reasonix code`). Every message appended atomically; `Ctrl+C`
-  never loses context.
+- Sessions live as JSONL under `~/.reasonix/sessions/<name>.jsonl`
+  (per directory for `reasonix code`). Every message appended
+  atomically; `Ctrl+C` never loses context.
 - Tool results are capped at 32k chars per call. Oversized sessions
   self-heal on load (shrinks + rewrites the file).
 - Malformed `assistant.tool_calls` / `tool` pairing is validated on
   every outgoing API call so a corrupted session can't keep 400ing.
-- Context gauge turns yellow at 50%, red at 80% with a `/compact` nudge.
-  Approaching the 131k window triggers an automatic compaction attempt
-  before falling back to a forced summary.
-- The model's sandbox in `reasonix code` refuses any path that resolves
-  outside the launch directory, including symlink escape and `..` traversal.
+- Context gauge turns yellow at 50%, red at 80% with a `/compact`
+  nudge. Approaching the 131k window triggers an automatic
+  compaction attempt before falling back to a forced summary.
+- The `reasonix code` sandbox refuses any path that resolves outside
+  the launch directory, including symlink escape and `..` traversal.
 
 ### Troubleshooting: duplicate rows / ghost rendering
 
@@ -307,31 +485,57 @@ If you hit this, run with plain mode:
 
 ```bash
 REASONIX_UI=plain npx reasonix code
-# or
-REASONIX_UI=plain npx reasonix
 ```
 
-Plain mode suppresses every live/animated row and disables the
-internal tick timer. You lose the streaming preview and spinners
-but gain stable scrollback. Committed events (your prompts, tool
-results, the model's final responses) still render normally via
-Ink's `<Static>` append path.
+Plain mode suppresses live/animated rows and disables the internal
+tick timer. You lose the streaming preview and spinners but gain
+stable scrollback. Windows Terminal, PowerShell 7 in Windows
+Terminal, and WezTerm don't need this opt-out.
 
-Windows Terminal, PowerShell 7 in Windows Terminal, and WezTerm
-don't need this opt-out.
+---
+
+## Web search — on by default
+
+The model has two web tools the moment you launch: `web_search` and
+`web_fetch`. No flag, no API key, no signup. When you ask about
+something the model wasn't trained on (new releases, current events,
+obscure APIs), it decides to call `web_search` on its own; if a
+snippet isn't enough it follows up with `web_fetch`.
+
+Backed by **Mojeek**'s public search page — an independent web
+index, bot-friendly, no cookies/sessions. Coverage on niche or very
+recent queries can be thinner than Google/Bing, but it's reliable
+from scripts. (DDG was the original backend but started serving
+anti-bot pages in 2026.)
+
+**Turn it off** (offline mode / privacy / CI):
+
+```json
+// ~/.reasonix/config.json
+{ "apiKey": "sk-…", "search": false }
+```
+
+```bash
+REASONIX_SEARCH=off npx reasonix code
+```
+
+**Bring your own** (Kagi, SearXNG, internal caches): implement the
+`WebSearchProvider` interface and call
+`registerWebTools(registry, { provider })` yourself, or bridge an
+existing MCP search server via `--mcp`.
 
 ---
 
 ## MCP — bring your own tools
 
-Any [MCP](https://spec.modelcontextprotocol.io/) server works. Wizard
-lets you pick from a catalog, or drive it by flag:
+Any [MCP](https://spec.modelcontextprotocol.io/) server works. The
+wizard lets you pick from a catalog, or drive it by flag:
 
 ```bash
 # stdio (local subprocess)
 npx reasonix --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe"
 
-# multiple servers at once
+# multiple at once
 npx reasonix \
   --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
   --mcp "demo=npx tsx examples/mcp-server-demo.ts"
@@ -340,21 +544,22 @@ npx reasonix \
 npx reasonix --mcp "kb=https://mcp.example.com/sse"
 ```
 
-`reasonix mcp list` shows the curated catalog. `reasonix mcp inspect <spec>`
-connects once and dumps the server's tools / resources / prompts without
-starting a chat. Progress notifications from long-running tools (2025-03-26
-spec) render live as a progress bar in the spinner.
+`reasonix mcp list` shows the curated catalog. `reasonix mcp inspect
+<spec>` connects once and dumps the server's tools / resources /
+prompts without starting a chat. Progress notifications from
+long-running tools (2025-03-26 spec) render live as a progress bar
+in the spinner.
 
-Supported transports: **stdio** (local command) and **HTTP+SSE** (remote,
-MCP 2024-11-05 spec).
+Supported transports: **stdio** (local command) and **HTTP+SSE**
+(remote, MCP 2024-11-05 spec).
 
 ---
 
 ## CLI reference
 
 ```bash
-npx reasonix                             # chat (uses saved config)
 npx reasonix code [path]                 # coding mode scoped to path (default: cwd)
+npx reasonix                             # chat (uses saved config)
 npx reasonix setup                       # reconfigure the wizard
 npx reasonix chat --session work         # named session
 npx reasonix chat --no-session           # ephemeral
@@ -386,6 +591,9 @@ Env vars (win over config):
 ```bash
 export DEEPSEEK_API_KEY=sk-...
 export DEEPSEEK_BASE_URL=https://...   # optional alternate endpoint
+export REASONIX_MEMORY=off              # disable REASONIX.md + user memory
+export REASONIX_SEARCH=off              # disable web_search / web_fetch
+export REASONIX_UI=plain                # disable live rows (ghosting workaround)
 ```
 
 ---
@@ -431,13 +639,14 @@ for await (const ev of loop.step("What is 17 + 25?")) {
 console.log(loop.stats.summary());
 ```
 
-`ChatOptions.seedTools` accepts a pre-built `ToolRegistry` for callers
-who want the `reasonix code` loop wiring without the CLI wrapper.
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for internals.
+`ChatOptions.seedTools` accepts a pre-built `ToolRegistry` for
+callers who want the `reasonix code` loop wiring without the CLI
+wrapper. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for
+internals.
 
 ---
 
-## Why Reasonix (not LangChain)
+## Benchmarks — verify the cache-hit claim yourself
 
 Every abstraction here earns its weight against a DeepSeek-specific
 property — dirt-cheap tokens, R1 reasoning traces, automatic prefix
@@ -451,11 +660,10 @@ caching, JSON mode. Generic wrappers leave these on the table.
 | Scavenge tool calls leaked into `<think>` | yes | no |
 | Call-storm breaker on identical-arg repeats | yes | no |
 | Live cache-hit / cost / vs-Claude panel | yes | no |
-| First-run config prompt + Markdown TUI | yes | no |
 
 On the same τ-bench-lite workload — 8 multi-turn tool-use tasks × 3
-repeats = 48 runs per side, live DeepSeek `deepseek-chat`, sole variable
-prefix stability:
+repeats = 48 runs per side, live DeepSeek `deepseek-chat`, sole
+variable prefix stability:
 
 | metric | baseline (cache-hostile) | Reasonix | delta |
 |---|---:|---:|---:|
@@ -463,7 +671,7 @@ prefix stability:
 | cost / task | $0.002599 | $0.001579 | **−39%** |
 | pass rate | 96% (23/24) | **100% (24/24)** | — |
 
-**Verify it yourself — no API key, zero cost:**
+**Reproduce without spending an API credit:**
 
 ```bash
 git clone https://github.com/esengine/reasonix.git && cd reasonix && npm install
@@ -479,8 +687,10 @@ model call; baseline's churns on every turn. The cache delta is
 *mechanically* attributable to log stability, not to a different
 system prompt.
 
-Full 48-run report: [`benchmarks/tau-bench/report.md`](./benchmarks/tau-bench/report.md).
-Reproduce with your own API key: `npx tsx benchmarks/tau-bench/runner.ts --repeats 3`.
+Full 48-run report:
+[`benchmarks/tau-bench/report.md`](./benchmarks/tau-bench/report.md).
+Reproduce with your own API key: `npx tsx
+benchmarks/tau-bench/runner.ts --repeats 3`.
 
 MCP reference runs (one single prefix hash across all 5 turns even
 with two concurrent MCP subprocesses):
@@ -495,10 +705,16 @@ with two concurrent MCP subprocesses):
 
 ## Non-goals
 
-- Multi-agent orchestration (use LangGraph).
-- RAG / vector stores (use LlamaIndex).
-- Multi-provider abstraction (use LiteLLM).
-- Web UI / SaaS.
+- **Multi-agent orchestration / sub-agents** (use LangGraph).
+- **Workflow DSL / DAG scheduler / parallel-branch engine** — skills
+  are prose; the model sequences via the normal tool-use loop.
+  Keeps single-loop + append-only + cache-first invariants intact.
+- **Multi-provider abstraction** (use LiteLLM). Reasonix is
+  DeepSeek-only on purpose — every pillar (cache-first loop, R1
+  harvesting, tool-call repair) is tuned against DeepSeek-specific
+  behavior and economics. Coupling to one backend is the feature.
+- **RAG / vector stores** (use LlamaIndex).
+- **Web UI / SaaS.**
 
 Reasonix does DeepSeek, deeply.
 
@@ -510,9 +726,9 @@ Reasonix does DeepSeek, deeply.
 git clone https://github.com/esengine/reasonix.git
 cd reasonix
 npm install
-npm run dev chat        # run CLI from source via tsx
+npm run dev code        # run CLI from source via tsx
 npm run build           # tsup to dist/
-npm test                # vitest (444 tests)
+npm test                # vitest (648 tests)
 npm run lint            # biome
 npm run typecheck       # tsc --noEmit
 ```

docs/logo.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="170" viewBox="0 0 760 170" role="img" aria-label="Reasonix — DeepSeek-native agent framework">
+  <title>Reasonix</title>
+  <defs>
+    <!-- Signature cyan → violet → fuchsia gradient used across the TUI wordmark
+         and the brand mark. Renders well on both GitHub dark and light bg. -->
+    <linearGradient id="rx-grad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#5eead4"/>
+      <stop offset="15%" stop-color="#67e8f9"/>
+      <stop offset="30%" stop-color="#7dd3fc"/>
+      <stop offset="45%" stop-color="#93c5fd"/>
+      <stop offset="60%" stop-color="#a5b4fc"/>
+      <stop offset="75%" stop-color="#c4b5fd"/>
+      <stop offset="90%" stop-color="#d8b4fe"/>
+      <stop offset="100%" stop-color="#f0abfc"/>
+    </linearGradient>
+    <linearGradient id="rx-grad-mark" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#5eead4"/>
+      <stop offset="50%" stop-color="#93c5fd"/>
+      <stop offset="100%" stop-color="#c4b5fd"/>
+    </linearGradient>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- ◈ brand mark: concentric diamonds. Outer stroke pulses,
+       inner fill breathes, whole group rotates slowly. The rotation
+       is subtle (12s / full turn) so it feels like a heartbeat, not a
+       spinner. -->
+  <g transform="translate(90, 85)" filter="url(#glow)">
+    <g>
+      <animateTransform attributeName="transform" type="rotate"
+                        from="0" to="360" dur="18s" repeatCount="indefinite"/>
+      <!-- Outer hollow diamond -->
+      <path d="M 0,-46 L 46,0 L 0,46 L -46,0 Z"
+            fill="none"
+            stroke="url(#rx-grad-mark)"
+            stroke-width="3.5"
+            stroke-linejoin="round">
+        <animate attributeName="stroke-width"
+                 values="3.5;5.5;3.5"
+                 dur="2.4s"
+                 repeatCount="indefinite"/>
+      </path>
+      <!-- Middle hollow diamond -->
+      <path d="M 0,-26 L 26,0 L 0,26 L -26,0 Z"
+            fill="none"
+            stroke="url(#rx-grad-mark)"
+            stroke-width="2"
+            stroke-linejoin="round"
+            opacity="0.7">
+        <animate attributeName="opacity"
+                 values="0.4;0.9;0.4"
+                 dur="2.4s"
+                 begin="0.8s"
+                 repeatCount="indefinite"/>
+      </path>
+      <!-- Inner solid diamond -->
+      <path d="M 0,-11 L 11,0 L 0,11 L -11,0 Z"
+            fill="url(#rx-grad-mark)">
+        <animate attributeName="opacity"
+                 values="0.75;1;0.75"
+                 dur="2.4s"
+                 repeatCount="indefinite"/>
+      </path>
+    </g>
+  </g>
+
+  <!-- REASONIX wordmark with shifting gradient. The x1 offset animates
+       so the gradient crawls left-to-right across the letters — a
+       slow rainbow sweep that gives the logo life without being noisy. -->
+  <text x="170" y="102"
+        font-family="ui-monospace, SFMono-Regular, 'Cascadia Code', Menlo, Consolas, 'DejaVu Sans Mono', monospace"
+        font-size="68"
+        font-weight="800"
+        fill="url(#rx-grad)"
+        letter-spacing="6">REASONIX
+    <animate attributeName="opacity"
+             values="0.9;1;0.9"
+             dur="3.2s"
+             repeatCount="indefinite"/>
+  </text>
+
+  <!-- Tagline sits just below the wordmark. Slate-500 reads well on
+       both GitHub dark and light themes (~4.5:1 contrast either way). -->
+  <text x="172" y="136"
+        font-family="ui-monospace, SFMono-Regular, 'Cascadia Code', Menlo, Consolas, 'DejaVu Sans Mono', monospace"
+        font-size="15"
+        fill="#64748b"
+        letter-spacing="0.5">DeepSeek-native agent framework  ·  cache-first loop  ·  Ink TUI</text>
+</svg>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "reasonix",
-  "version": "0.4.14",
+  "version": "0.5.18",
   "description": "DeepSeek-native agent framework: cache-first loop, R1 thought harvesting, tool-call repair.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "data/deepseek-tokenizer.json.gz",
     "README.md",
     "LICENSE"
   ],

scripts/prepare-tokenizer.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Regenerate `data/deepseek-tokenizer.json.gz` from an upstream
+ * `tokenizer.json` (as shipped in DeepSeek's deepseek_v3_tokenizer.zip).
+ *
+ * Why slim+gz: the full tokenizer.json is 7.5MB; we only need four
+ * fields (vocab, merges, pre_tokenizer, added_tokens). Strip + gzip
+ * drops the committed artifact to ~1.7MB with no loss of fidelity
+ * for encode-side token counting.
+ *
+ * Usage: `node --experimental-strip-types scripts/prepare-tokenizer.ts <path/to/tokenizer.json>`
+ * (or via `tsx` / `ts-node`.)
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+
+const src = process.argv[2];
+if (!src) {
+  process.stderr.write("usage: prepare-tokenizer.ts <tokenizer.json>\n");
+  process.exit(2);
+}
+
+const raw = JSON.parse(readFileSync(src, "utf8"));
+const slim = {
+  added_tokens: raw.added_tokens,
+  pre_tokenizer: raw.pre_tokenizer,
+  model: { type: raw.model.type, vocab: raw.model.vocab, merges: raw.model.merges },
+};
+const gz = gzipSync(Buffer.from(JSON.stringify(slim)), { level: 9 });
+const outPath = join(process.cwd(), "data", "deepseek-tokenizer.json.gz");
+writeFileSync(outPath, gz);
+process.stdout.write(`wrote ${outPath} (${(gz.length / 1024).toFixed(1)} KB)\n`);

scripts/smoke-memory.mts

@@ -0,0 +1,192 @@
+/**
+ * End-to-end smoke test for the memory layer. Runs against a temp
+ * homeDir so the developer's real ~/.reasonix/memory/ is never touched.
+ * Exercises: write → index regeneration → prefix assembly →
+ * recall → delete → REASONIX_MEMORY=off short-circuit.
+ *
+ * Run: npx tsx scripts/smoke-memory.mts
+ * Exit code 0 on success, 1 on any assertion failure.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ToolRegistry } from "../src/tools.js";
+import { registerMemoryTools } from "../src/tools/memory.js";
+import {
+  MemoryStore,
+  applyMemoryStack,
+  applyUserMemory,
+  projectHash,
+} from "../src/user-memory.js";
+
+let failures = 0;
+function check(label: string, cond: unknown, detail?: string) {
+  if (cond) {
+    process.stdout.write(`  ✓ ${label}\n`);
+  } else {
+    failures++;
+    process.stdout.write(`  ✗ ${label}${detail ? `  — ${detail}` : ""}\n`);
+  }
+}
+
+async function main() {
+  const home = mkdtempSync(join(tmpdir(), "reasonix-smoke-home-"));
+  const projectRoot = mkdtempSync(join(tmpdir(), "reasonix-smoke-proj-"));
+  process.stdout.write(`home:    ${home}\nproject: ${projectRoot}\n\n`);
+
+  try {
+    // ── 1. MemoryStore write + index regeneration ────────────────────
+    process.stdout.write("1. MemoryStore write → index regen\n");
+    const store = new MemoryStore({ homeDir: home, projectRoot });
+    store.write({
+      name: "bun_build",
+      type: "project",
+      scope: "project",
+      description: "Build command on this machine is `bun run build`",
+      body: "On this machine, no npm — always `bun run build` / `bun run test`.",
+    });
+    store.write({
+      name: "tabs_not_spaces",
+      type: "user",
+      scope: "global",
+      description: "Use tabs for indentation across all projects",
+      body: "Rule.\n\n**Why:** muscle memory, editor config across machines.\n\n**How to apply:** always tabs.",
+    });
+
+    const hash = projectHash(projectRoot);
+    const projectFile = join(home, "memory", hash, "bun_build.md");
+    const globalFile = join(home, "memory", "global", "tabs_not_spaces.md");
+    check("project-scoped file landed in <hash>/ dir", existsSync(projectFile));
+    check("global-scoped file landed in global/ dir", existsSync(globalFile));
+    check("no cross-contamination project ⇒ global", !existsSync(join(home, "memory", "global", "bun_build.md")));
+
+    const projectIndex = readFileSync(join(home, "memory", hash, "MEMORY.md"), "utf8");
+    check("project MEMORY.md points at bun_build.md", projectIndex.includes("[bun_build](bun_build.md)"));
+    const globalIndex = readFileSync(join(home, "memory", "global", "MEMORY.md"), "utf8");
+    check("global MEMORY.md points at tabs_not_spaces.md", globalIndex.includes("[tabs_not_spaces](tabs_not_spaces.md)"));
+
+    const raw = readFileSync(projectFile, "utf8");
+    check("frontmatter has name/type/scope/created", /^---\nname: bun_build\n/.test(raw) && /type: project/.test(raw) && /scope: project/.test(raw) && /created: \d{4}-\d{2}-\d{2}/.test(raw));
+
+    // ── 2. Prefix assembly via applyMemoryStack (+ REASONIX.md) ────────
+    process.stdout.write("\n2. Prefix assembly (REASONIX.md + user memory)\n");
+    writeFileSync(join(projectRoot, "REASONIX.md"), "# Project notes\nPrefer explicit types over inference.\n", "utf8");
+    const BASE = "You are a test assistant.";
+    const withProjOnly = applyUserMemory(BASE, { homeDir: home, projectRoot });
+    check("applyUserMemory contains global block", withProjOnly.includes("# User memory — global"));
+    check("applyUserMemory contains project block", withProjOnly.includes("# User memory — this project"));
+    check("bun_build description present in prefix", withProjOnly.includes("bun run build"));
+    check("tabs_not_spaces description present in prefix", withProjOnly.includes("Use tabs for indentation"));
+
+    // Order: base → (REASONIX.md would go first via applyMemoryStack) → global → project
+    const ordered = applyUserMemory(BASE, { homeDir: home, projectRoot });
+    const iGlobalBlock = ordered.indexOf("# User memory — global");
+    const iProjBlock = ordered.indexOf("# User memory — this project");
+    check("global block precedes project block (stable for cache)", iGlobalBlock > 0 && iGlobalBlock < iProjBlock);
+
+    // Determinism — two calls with same state produce byte-identical prompts.
+    const a = applyUserMemory(BASE, { homeDir: home, projectRoot });
+    const b = applyUserMemory(BASE, { homeDir: home, projectRoot });
+    check("applyUserMemory is deterministic (byte-stable)", a === b);
+
+    // ── 3. The `remember` / `recall_memory` / `forget` tools ───────────
+    process.stdout.write("\n3. Tool dispatch (remember / recall / forget)\n");
+    const reg = new ToolRegistry();
+    registerMemoryTools(reg, { homeDir: home, projectRoot });
+    check("remember tool registered", reg.has("remember"));
+    check("forget tool registered", reg.has("forget"));
+    check("recall_memory tool registered", reg.has("recall_memory"));
+    check("recall_memory is readOnly (plan-mode safe)", reg.get("recall_memory")?.readOnly === true);
+    check("remember is NOT readOnly (plan-mode blocked)", reg.get("remember")?.readOnly !== true);
+
+    const remOut = await reg.dispatch("remember", {
+      type: "feedback",
+      scope: "global",
+      name: "prefers_short_replies",
+      description: "User wants terse answers, no trailing summaries",
+      content: "Default to terse. If the user wants detail they'll ask.",
+    });
+    check("remember returns a confirmation (not an error)", remOut.includes("REMEMBERED (global/prefers_short_replies)"), remOut);
+
+    const recallOut = await reg.dispatch("recall_memory", {
+      scope: "global",
+      name: "prefers_short_replies",
+    });
+    check("recall_memory returns the body", recallOut.includes("Default to terse"));
+
+    const forgetOut = await reg.dispatch("forget", {
+      scope: "global",
+      name: "prefers_short_replies",
+    });
+    check("forget returns a confirmation", forgetOut.includes("forgot (global/prefers_short_replies)"));
+    check("recall_memory after forget returns an error", (await reg.dispatch("recall_memory", { scope: "global", name: "prefers_short_replies" })).includes("error"));
+
+    // ── 4. Project scope refused when projectRoot is absent ────────────
+    process.stdout.write("\n4. Chat-mode (no projectRoot) refuses project scope\n");
+    const chatReg = new ToolRegistry();
+    registerMemoryTools(chatReg, { homeDir: home });
+    const projInChat = await chatReg.dispatch("remember", {
+      type: "project",
+      scope: "project",
+      name: "should_fail",
+      description: "d",
+      content: "c",
+    });
+    check("scope='project' in chat mode → error payload", projInChat.includes("error") && projInChat.includes("project"));
+    const globalInChat = await chatReg.dispatch("remember", {
+      type: "user",
+      scope: "global",
+      name: "global_from_chat",
+      description: "works across projects",
+      content: "body",
+    });
+    check("scope='global' in chat mode → writes successfully", globalInChat.includes("REMEMBERED (global/"));
+
+    // ── 5. REASONIX_MEMORY=off short-circuit ───────────────────────────
+    process.stdout.write("\n5. REASONIX_MEMORY=off opt-out\n");
+    process.env.REASONIX_MEMORY = "off";
+    try {
+      const silenced = applyUserMemory(BASE, { homeDir: home, projectRoot });
+      check("applyUserMemory returns BASE unchanged when off", silenced === BASE);
+      const fullStack = applyMemoryStack(BASE, projectRoot);
+      check("applyMemoryStack returns BASE unchanged when off (REASONIX.md also skipped)", fullStack === BASE);
+    } finally {
+      delete process.env.REASONIX_MEMORY;
+    }
+
+    // ── 6. Delete regeneration: MEMORY.md matches current file set ─────
+    process.stdout.write("\n6. Delete + index regeneration\n");
+    store.delete("global", "tabs_not_spaces");
+    store.delete("global", "global_from_chat");
+    const globalIdxAfter = join(home, "memory", "global", "MEMORY.md");
+    check("global MEMORY.md removed when last file deleted", !existsSync(globalIdxAfter));
+    const projectIdxStill = readFileSync(join(home, "memory", hash, "MEMORY.md"), "utf8");
+    check("project MEMORY.md untouched (different scope)", projectIdxStill.includes("bun_build"));
+
+    // ── 7. Name-sanitization boundary ──────────────────────────────────
+    process.stdout.write("\n7. Name sanitization (path-traversal refused)\n");
+    const badOut = await reg.dispatch("remember", {
+      type: "user",
+      scope: "global",
+      name: "../../etc/passwd",
+      description: "d",
+      content: "c",
+    });
+    check("remember refuses path-traversal name", badOut.includes("invalid memory name"));
+    const outsideFile = join(home, "etc", "passwd.md");
+    check("no file written outside the memory dir", !existsSync(outsideFile));
+
+    process.stdout.write(`\n${failures === 0 ? "✅ all smoke checks passed" : `❌ ${failures} failure(s)`}\n`);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

src/at-mentions.ts

@@ -0,0 +1,397 @@
+/**
+ * Expand `@path/to/file` mentions in a user prompt to inline file
+ * content.
+ *
+ * Why: most interactive coding sessions start with "look at X, then
+ * change Y". Typing `@src/loop.ts` reads faster and cheaper than
+ * "look at src/loop.ts (and the model fires read_file, and we pay for
+ * the round trip)" — the model sees the file content from turn 1
+ * instead of round-tripping a tool call for it.
+ *
+ * Shape: the user's text is kept verbatim. Expanded file contents are
+ * appended in a "Referenced files" block at the end, each wrapped in
+ * `<file path="...">...</file>` so the model can cite them back
+ * unambiguously.
+ *
+ * Safety: paths must resolve inside `rootDir` (no `..` escape, no
+ * absolute paths), must exist as a regular file, and must be under
+ * `maxBytes`. Missing / too-large / escaping paths get a short note
+ * appended instead of content so the user sees why it was skipped.
+ */
+
+import { type Dirent, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+/** Caps match tool-result dispatch truncation (0.5.2). */
+export const DEFAULT_AT_MENTION_MAX_BYTES = 64 * 1024;
+
+/**
+ * Default directory names skipped when listing files for the picker.
+ * Matches what most repos gitignore AND keeps the picker off the
+ * hottest bloat — `node_modules` alone can be 100k+ entries.
+ */
+export const DEFAULT_PICKER_IGNORE_DIRS: readonly string[] = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "out",
+  "coverage",
+  ".cache",
+  ".vscode",
+  ".idea",
+  "target",
+  ".venv",
+  "venv",
+  "__pycache__",
+];
+
+export interface ListFilesOptions {
+  /** Cap the walk once we've collected this many entries. Default 500. */
+  maxResults?: number;
+  /** Directory names to skip entirely. Defaults to {@link DEFAULT_PICKER_IGNORE_DIRS}. */
+  ignoreDirs?: readonly string[];
+}
+
+/**
+ * Walk `root` recursively and return relative file paths (forward-slash
+ * separator, regardless of platform) for the `@` picker.
+ *
+ * Synchronous on purpose: this runs once at App mount (and on each turn
+ * so newly-created files show up) and blocks the render thread for a
+ * predictable ~10-50ms on a moderate repo. An async variant would need
+ * to coordinate with the Ink render loop; sync fits the rest of the
+ * TUI's single-turn-per-tick model cleanly.
+ *
+ * Skips:
+ *   - directories in `ignoreDirs` (default: DEFAULT_PICKER_IGNORE_DIRS)
+ *   - any directory whose name starts with `.` (covers `.git`,
+ *     `.vscode`, dotfile vendors). Dotfile REGULAR FILES (`.env`,
+ *     `.gitignore`, `.prettierrc`) are kept — users reference them.
+ *   - entries the walker can't read (permission errors, broken links).
+ */
+export function listFilesSync(root: string, opts: ListFilesOptions = {}): string[] {
+  return listFilesWithStatsSync(root, opts).map((e) => e.path);
+}
+
+export interface FileWithStats {
+  /** Relative path with forward-slash separator. */
+  path: string;
+  /** Modification time (Date.getTime() / ms since epoch). 0 when stat failed. */
+  mtimeMs: number;
+}
+
+/**
+ * Same walk as {@link listFilesSync} but also statS each file for
+ * modification time. Used by the `@` picker to surface recently-
+ * edited files first — matches VS Code Quick Open / similar UX.
+ *
+ * Stat failures don't throw: the entry is kept with `mtimeMs: 0` so
+ * it still appears in the picker (just sinks to the bottom of the
+ * recency sort).
+ */
+export function listFilesWithStatsSync(root: string, opts: ListFilesOptions = {}): FileWithStats[] {
+  const maxResults = Math.max(1, opts.maxResults ?? 500);
+  const ignore = new Set(opts.ignoreDirs ?? DEFAULT_PICKER_IGNORE_DIRS);
+  const rootAbs = resolve(root);
+  const out: FileWithStats[] = [];
+
+  const walk = (dirAbs: string, dirRel: string) => {
+    if (out.length >= maxResults) return;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const ent of entries) {
+      if (out.length >= maxResults) return;
+      const relPath = dirRel ? `${dirRel}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        if (ent.name.startsWith(".") || ignore.has(ent.name)) continue;
+        walk(join(dirAbs, ent.name), relPath);
+      } else if (ent.isFile()) {
+        let mtimeMs = 0;
+        try {
+          mtimeMs = statSync(join(dirAbs, ent.name)).mtimeMs;
+        } catch {
+          /* stat failed (permission / EAGAIN) — keep the entry with mtime=0 */
+        }
+        out.push({ path: relPath, mtimeMs });
+      }
+    }
+  };
+
+  walk(rootAbs, "");
+  return out;
+}
+
+/**
+ * Prefix pattern used by the `@` picker to detect an IN-PROGRESS
+ * mention at the END of the input buffer. Captures the partial path
+ * (which may be empty — just `@`) so the picker can use it as a
+ * substring filter.
+ *
+ * Distinct from {@link AT_MENTION_PATTERN} (which finds completed
+ * mentions anywhere in the text for expansion-at-submit). This one
+ * fires on the trailing token only, anchored at end-of-input.
+ */
+export const AT_PICKER_PREFIX = /(?:^|\s)@([a-zA-Z0-9_./\\-]*)$/;
+
+/**
+ * Return the picker state for a given input buffer: the partial query
+ * (may be empty string — just `@`) and the buffer offset of the `@`
+ * character. `null` when the buffer doesn't end in a mention-in-
+ * progress.
+ */
+export function detectAtPicker(input: string): { query: string; atOffset: number } | null {
+  const m = AT_PICKER_PREFIX.exec(input);
+  if (!m) return null;
+  const query = m[1] ?? "";
+  // `m.index` is the offset of the capture group's SURROUNDING match —
+  // which starts at either ^ or the preceding whitespace. The `@`
+  // itself is at `end-of-input - query.length - 1`.
+  const atOffset = input.length - query.length - 1;
+  return { query, atOffset };
+}
+
+/** A candidate accepted by the picker ranker — either a bare path or a path with mtime. */
+export type PickerCandidate = string | FileWithStats;
+
+export interface RankPickerOptions {
+  /** Upper bound on returned entries. Default 40. */
+  limit?: number;
+  /**
+   * Paths the user or model has touched recently (via tool calls like
+   * `read_file` / `edit_file`). Matching paths get a recency boost so
+   * the picker surfaces "stuff I just looked at" near the top.
+   */
+  recentlyUsed?: readonly string[];
+}
+
+/**
+ * Filter and rank candidate files against the picker's partial query.
+ *
+ * Empty query:
+ *   - Sort by "recently used" bucket first (if provided), then mtime
+ *     descending (newer first), then path alpha.
+ *   - Pure-string input (no mtime data) falls back to alpha since
+ *     recency info isn't available.
+ *
+ * Non-empty query:
+ *   - Case-insensitive substring match, with a basename-prefix boost
+ *     so `lo` floats `loop.ts`-shaped paths to the top.
+ *   - Ties broken first by recently-used membership, then mtime.
+ *
+ * Back-compat: passes `string[]` through the same logic (mtime = 0,
+ * recently-used still honored).
+ */
+export function rankPickerCandidates(
+  files: readonly PickerCandidate[],
+  query: string,
+  limitOrOpts?: number | RankPickerOptions,
+): string[] {
+  const opts: RankPickerOptions =
+    typeof limitOrOpts === "number" ? { limit: limitOrOpts } : (limitOrOpts ?? {});
+  const limit = opts.limit ?? 40;
+  const recent = new Set(opts.recentlyUsed ?? []);
+
+  const entries: FileWithStats[] = files.map((f) =>
+    typeof f === "string" ? { path: f, mtimeMs: 0 } : f,
+  );
+
+  if (!query) {
+    // Only re-sort when we actually have signal to sort by. If input
+    // is bare strings (mtime = 0 everywhere) AND there's no recent-
+    // used list, preserve input order so callers keep their existing
+    // layout. Passing FileWithStats or a non-empty recentlyUsed opts
+    // you into mtime+recency ranking.
+    const anyMtime = entries.some((e) => e.mtimeMs > 0);
+    if (!anyMtime && recent.size === 0) {
+      return entries.slice(0, limit).map((e) => e.path);
+    }
+    const sorted = [...entries].sort((a, b) => {
+      const aRecent = recent.has(a.path) ? 1 : 0;
+      const bRecent = recent.has(b.path) ? 1 : 0;
+      if (aRecent !== bRecent) return bRecent - aRecent;
+      if (a.mtimeMs !== b.mtimeMs) return b.mtimeMs - a.mtimeMs;
+      return a.path.localeCompare(b.path);
+    });
+    return sorted.slice(0, limit).map((e) => e.path);
+  }
+
+  const needle = query.toLowerCase();
+  const scored: Array<{ path: string; score: number; mtimeMs: number; recent: boolean }> = [];
+  for (const e of entries) {
+    const lower = e.path.toLowerCase();
+    const hit = lower.indexOf(needle);
+    if (hit < 0) continue;
+    const slash = lower.lastIndexOf("/");
+    const base = slash >= 0 ? lower.slice(slash + 1) : lower;
+    let score = 2;
+    if (base.startsWith(needle)) score = 0;
+    else if (lower.startsWith(needle)) score = 1;
+    scored.push({
+      path: e.path,
+      score: score * 10_000 + hit,
+      mtimeMs: e.mtimeMs,
+      recent: recent.has(e.path),
+    });
+  }
+  scored.sort((a, b) => {
+    if (a.score !== b.score) return a.score - b.score;
+    // Tie-break: recently-used, then mtime (newer first).
+    if (a.recent !== b.recent) return a.recent ? -1 : 1;
+    return b.mtimeMs - a.mtimeMs;
+  });
+  return scored.slice(0, limit).map((s) => s.path);
+}
+
+/**
+ * Matches `@` at a word boundary (start-of-string or preceded by
+ * whitespace) followed by a path-like token. Deliberately rejects `@`
+ * embedded in longer words (email addresses, mentions on social sites)
+ * by requiring the word boundary.
+ *
+ * Path charset keeps it to the characters that appear in real repo
+ * paths — letters, digits, `_` `-` `.` `/` `\`. Trailing `.` (e.g.
+ * `@foo.ts.`) is stripped before lookup so a sentence-terminating
+ * period doesn't break the mention.
+ */
+export const AT_MENTION_PATTERN = /(?<=^|\s)@([a-zA-Z0-9_./\\-]+)/g;
+
+export interface AtMentionExpansion {
+  /** The raw `@path` token as it appeared in the text. */
+  token: string;
+  /** The relative path, as resolved against rootDir. */
+  path: string;
+  /** True if the content was inlined. False = skipped (reason in `skip`). */
+  ok: boolean;
+  /** Bytes read (only for ok=true). */
+  bytes?: number;
+  /** Why the mention was skipped. Set when ok=false. */
+  skip?: "missing" | "not-file" | "too-large" | "escape" | "read-error";
+}
+
+export interface AtMentionOptions {
+  /** Max file size in bytes before a mention is skipped. */
+  maxBytes?: number;
+  /**
+   * Optional file-system overrides for tests. Real callers omit these;
+   * the helper falls through to `node:fs`.
+   */
+  fs?: {
+    exists: (path: string) => boolean;
+    isFile: (path: string) => boolean;
+    size: (path: string) => number;
+    read: (path: string) => string;
+  };
+}
+
+/**
+ * Expand `@path` mentions in `text`. Returns the (possibly augmented)
+ * text plus a per-mention report so the caller can surface expansions
+ * in the UI.
+ */
+export function expandAtMentions(
+  text: string,
+  rootDir: string,
+  opts: AtMentionOptions = {},
+): { text: string; expansions: AtMentionExpansion[] } {
+  const maxBytes = opts.maxBytes ?? DEFAULT_AT_MENTION_MAX_BYTES;
+  const fs = opts.fs ?? defaultFs;
+  const root = resolve(rootDir);
+  // De-dupe by token so `@file.ts` referenced twice inlines once.
+  const seen = new Map<string, AtMentionExpansion>();
+  const expansions: AtMentionExpansion[] = [];
+
+  for (const match of text.matchAll(AT_MENTION_PATTERN)) {
+    const rawPath = match[1] ?? "";
+    // Strip trailing dot (sentence terminator): `@foo.ts.` → `@foo.ts`.
+    // Keep internal dots intact.
+    const cleaned = rawPath.replace(/\.+$/, "");
+    if (!cleaned) continue;
+    const token = `@${cleaned}`;
+    if (seen.has(token)) continue;
+
+    const expansion = resolveMention(cleaned, root, maxBytes, fs);
+    seen.set(token, expansion);
+    expansions.push(expansion);
+  }
+
+  if (expansions.length === 0) return { text, expansions };
+
+  // Build the trailing "Referenced files" block. Keep successful
+  // inlines and skipped ones (with their reason) so the model sees
+  // both what's here and what's missing.
+  const blocks: string[] = [];
+  for (const ex of expansions) {
+    if (ex.ok) {
+      const content = readSafe(root, ex.path, fs);
+      blocks.push(`<file path="${ex.path}">\n${content}\n</file>`);
+    } else {
+      blocks.push(`<file path="${ex.path}" skipped="${ex.skip}" />`);
+    }
+  }
+  const augmented = `${text}\n\n[Referenced files]\n${blocks.join("\n\n")}`;
+  return { text: augmented, expansions };
+}
+
+function resolveMention(
+  rawPath: string,
+  root: string,
+  maxBytes: number,
+  fs: NonNullable<AtMentionOptions["fs"]>,
+): AtMentionExpansion {
+  // Reject absolute paths — `@/etc/passwd` should not inline.
+  if (isAbsolute(rawPath)) {
+    return { token: `@${rawPath}`, path: rawPath, ok: false, skip: "escape" };
+  }
+  const resolved = resolve(root, rawPath);
+  // Sandbox escape: after resolution the path must still be inside root.
+  const rel = relative(root, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { token: `@${rawPath}`, path: rawPath, ok: false, skip: "escape" };
+  }
+  if (!fs.exists(resolved)) {
+    return { token: `@${rawPath}`, path: rawPath, ok: false, skip: "missing" };
+  }
+  if (!fs.isFile(resolved)) {
+    return { token: `@${rawPath}`, path: rawPath, ok: false, skip: "not-file" };
+  }
+  const size = fs.size(resolved);
+  if (size > maxBytes) {
+    return { token: `@${rawPath}`, path: rawPath, ok: false, skip: "too-large", bytes: size };
+  }
+  return { token: `@${rawPath}`, path: rawPath, ok: true, bytes: size };
+}
+
+function readSafe(root: string, rawPath: string, fs: NonNullable<AtMentionOptions["fs"]>): string {
+  const resolved = resolve(root, rawPath);
+  try {
+    return fs.read(resolved);
+  } catch {
+    return "(read failed)";
+  }
+}
+
+const defaultFs: NonNullable<AtMentionOptions["fs"]> = {
+  exists: (p) => existsSync(p),
+  isFile: (p) => {
+    try {
+      return statSync(p).isFile();
+    } catch {
+      return false;
+    }
+  },
+  size: (p) => {
+    try {
+      return statSync(p).size;
+    } catch {
+      return 0;
+    }
+  },
+  read: (p) => readFileSync(p, "utf8"),
+};

src/cli/commands/chat.tsx

@@ -1,6 +1,7 @@
+import { existsSync, statSync } from "node:fs";
 import { render } from "ink";
 import React, { useState } from "react";
-import { loadApiKey } from "../../config.js";
+import { loadApiKey, searchEnabled } from "../../config.js";
 import { loadDotenv } from "../../env.js";
 import { McpClient } from "../../mcp/client.js";
 import { type InspectionReport, inspectMcpServer } from "../../mcp/inspect.js";
@@ -8,8 +9,16 @@ import { bridgeMcpTools } from "../../mcp/registry.js";
 import { parseMcpSpec } from "../../mcp/spec.js";
 import { SseTransport } from "../../mcp/sse.js";
 import { type McpTransport, StdioTransport } from "../../mcp/stdio.js";
+import {
+  loadSessionMessages,
+  rewriteSession,
+  sessionPath as sessionPathOf,
+} from "../../session.js";
 import { ToolRegistry } from "../../tools.js";
+import { registerMemoryTools } from "../../tools/memory.js";
+import { registerWebTools } from "../../tools/web.js";
 import { App } from "../ui/App.js";
+import { SessionPicker } from "../ui/SessionPicker.js";
 import { Setup } from "../ui/Setup.js";
 import type { McpServerSummary } from "../ui/slash.js";
 
@@ -43,6 +52,10 @@ export interface ChatOptions {
    * Set by `reasonix code`; plain `reasonix chat` leaves this off.
    */
   codeMode?: { rootDir: string };
+  /** Skip the session picker — assume "Resume" (backwards-compatible auto-continue). */
+  forceResume?: boolean;
+  /** Skip the session picker — assume "New" (wipe the session file and start fresh). */
+  forceNew?: boolean;
 }
 
 interface RootProps extends ChatOptions {
@@ -58,10 +71,24 @@ interface RootProps extends ChatOptions {
    * React reconciliation (no effect-timing surprises).
    */
   progressSink: { current: ((info: ProgressInfo) => void) | null };
+  /** Present when the session has prior messages; drives the picker. */
+  sessionPreview?: { messageCount: number; lastActive: Date };
 }
 
-function Root({ initialKey, tools, mcpSpecs, mcpServers, progressSink, ...appProps }: RootProps) {
+function Root({
+  initialKey,
+  tools,
+  mcpSpecs,
+  mcpServers,
+  progressSink,
+  sessionPreview,
+  ...appProps
+}: RootProps) {
   const [key, setKey] = useState<string | undefined>(initialKey);
+  // `null` once the picker is resolved (or was never needed). Starts as
+  // the preview so we can render the picker once before mounting App.
+  const [pending, setPending] = useState<typeof sessionPreview>(sessionPreview);
+
   if (!key) {
     return (
       <Setup
@@ -73,6 +100,26 @@ function Root({ initialKey, tools, mcpSpecs, mcpServers, progressSink, ...appPro
     );
   }
   process.env.DEEPSEEK_API_KEY = key;
+
+  if (pending && appProps.session) {
+    return (
+      <SessionPicker
+        sessionName={appProps.session}
+        messageCount={pending.messageCount}
+        lastActive={pending.lastActive}
+        onChoose={(choice) => {
+          if (choice === "new" || choice === "delete") {
+            // Wipe the session file. "new" and "delete" do the same thing
+            // at this step — the distinction is only in the picker's
+            // wording. A future enhancement could archive on "new".
+            rewriteSession(appProps.session!, []);
+          }
+          setPending(undefined);
+        }}
+      />
+    );
+  }
+
   return (
     <App
       model={appProps.model}
@@ -164,6 +211,7 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
           spec: raw,
           toolCount: bridge.registeredNames.length,
           report,
+          client: mcp,
         });
       } catch (err) {
         // Per-server failure is non-fatal: one broken server shouldn't
@@ -189,6 +237,43 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
   }
   const mcpSpecs = successfulSpecs;
 
+  // Register web search/fetch tools unless explicitly disabled. DDG
+  // backs them with no key required; the model invokes them whenever
+  // a question needs info fresher than its training data.
+  if (searchEnabled()) {
+    if (!tools) tools = new ToolRegistry();
+    registerWebTools(tools);
+  }
+
+  // Memory tools — available in every session, not just code mode.
+  // Chat-mode callers get global scope only; project scope requires
+  // the seedTools path from `reasonix code` (which registers its own
+  // MemoryStore bound to rootDir before chatCommand runs).
+  // `run_skill` is registered later in App.tsx (where the client
+  // exists) so it can wire the subagent runner for runAs:subagent
+  // skills.
+  if (!opts.seedTools) {
+    if (!tools) tools = new ToolRegistry();
+    registerMemoryTools(tools, {});
+  }
+
+  // Decide whether to show the session picker. It's gated on: session
+  // persistence is on, the session file already has prior messages, and
+  // the caller didn't pre-commit to one of the choices via --resume /
+  // --new flags. `--new` wipes the file now (before the loop opens),
+  // so the App mounts against a fresh log.
+  let sessionPreview: { messageCount: number; lastActive: Date } | undefined;
+  if (opts.session && !opts.forceResume && !opts.forceNew) {
+    const prior = loadSessionMessages(opts.session);
+    if (prior.length > 0) {
+      const p = sessionPathOf(opts.session);
+      const mtime = existsSync(p) ? statSync(p).mtime : new Date();
+      sessionPreview = { messageCount: prior.length, lastActive: mtime };
+    }
+  } else if (opts.session && opts.forceNew) {
+    rewriteSession(opts.session, []);
+  }
+
   const { waitUntilExit } = render(
     <Root
       initialKey={initialKey}
@@ -196,6 +281,7 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
       mcpSpecs={mcpSpecs}
       mcpServers={mcpServers}
       progressSink={progressSink}
+      sessionPreview={sessionPreview}
       {...opts}
     />,
     // patchConsole:false — we never log to console during the TUI, and the

src/cli/commands/code.tsx

@@ -19,9 +19,13 @@
  */
 
 import { basename, resolve } from "node:path";
+import { loadProjectShellAllowed } from "../../config.js";
 import { sanitizeName } from "../../session.js";
 import { ToolRegistry } from "../../tools.js";
 import { registerFilesystemTools } from "../../tools/filesystem.js";
+import { registerMemoryTools } from "../../tools/memory.js";
+import { registerPlanTool } from "../../tools/plan.js";
+import { registerShellTools } from "../../tools/shell.js";
 import { chatCommand } from "./chat.js";
 
 export interface CodeOptions {
@@ -33,6 +37,19 @@ export interface CodeOptions {
   noSession?: boolean;
   /** Transcript file for replay/diff. */
   transcript?: string;
+  /** Skip the session picker — always resume prior messages. */
+  forceResume?: boolean;
+  /** Skip the session picker — always wipe prior messages and start fresh. */
+  forceNew?: boolean;
+  /**
+   * Opt into Pillar 2 harvesting (extracts a typed plan state from R1
+   * reasoning via an extra V3 call). Default OFF in code mode — the
+   * displayed subgoals/hypotheses/rejectedPaths have no programmatic
+   * consumer, only `uncertainties.length` feeds branching, and the
+   * extra V3 call adds ~10-15% per-turn cost. Users who want the
+   * reasoning surfaced explicitly can pass `--harvest`.
+   */
+  harvest?: boolean;
 }
 
 export async function codeCommand(opts: CodeOptions = {}): Promise<void> {
@@ -49,18 +66,43 @@ export async function codeCommand(opts: CodeOptions = {}): Promise<void> {
   // triggered R1's DSML hallucinations all through 0.4.x.
   const tools = new ToolRegistry();
   registerFilesystemTools(tools, { rootDir });
+  registerShellTools(tools, {
+    rootDir,
+    // Per-project "always allow" list persisted from prior ShellConfirm
+    // choices; merged on top of the built-in allowlist in shell.ts.
+    // GETTER form — re-read every dispatch so a prefix the user adds
+    // via ShellConfirm mid-session takes effect on the next shell call
+    // instead of waiting for `/new` or a relaunch.
+    extraAllowed: () => loadProjectShellAllowed(rootDir),
+  });
+  // `submit_plan` is always in the spec list so the prefix cache stays
+  // stable across plan-mode toggles (Pillar 1). The tool itself is a
+  // no-op outside plan mode and throws `PlanProposedError` when the
+  // user has `/plan`-enabled the session.
+  registerPlanTool(tools);
+  // `remember` / `forget` / `recall_memory` — cross-session user memory.
+  // Project scope hashes off rootDir so switching projects gets a fresh
+  // per-project memory store; the global scope is shared across runs.
+  registerMemoryTools(tools, { projectRoot: rootDir });
+  // `run_skill` is intentionally NOT registered here — App.tsx wires it
+  // up with the subagent runner attached, so `runAs: subagent` skills
+  // can spawn isolated child loops. Doing it here would mean the App's
+  // re-registration would shadow the no-runner version, which works
+  // (last write wins) but obscures the wiring.
 
   process.stderr.write(
-    `▸ reasonix code: rooted at ${rootDir}, session "${session ?? "(ephemeral)"}" · ${tools.size} native fs tool(s)\n`,
+    `▸ reasonix code: rooted at ${rootDir}, session "${session ?? "(ephemeral)"}" · ${tools.size} native tool(s)\n`,
   );
 
   await chatCommand({
     model: opts.model ?? "deepseek-reasoner",
-    harvest: true, // smart preset's harvest setting, always on for code
+    harvest: opts.harvest ?? false,
     system: codeSystemPrompt(rootDir),
     transcript: opts.transcript,
     session,
     seedTools: tools,
     codeMode: { rootDir },
+    forceResume: opts.forceResume,
+    forceNew: opts.forceNew,
   });
 }

src/cli/commands/run.ts

@@ -11,6 +11,7 @@ import { SseTransport } from "../../mcp/sse.js";
 import { type McpTransport, StdioTransport } from "../../mcp/stdio.js";
 import { ToolRegistry } from "../../tools.js";
 import { openTranscriptFile, recordFromLoopEvent, writeRecord } from "../../transcript.js";
+import { appendUsage } from "../../usage.js";
 
 export interface RunOptions {
   task: string;
@@ -148,6 +149,12 @@ export async function runCommand(opts: RunOptions): Promise<void> {
       if (ev.role === "tool") process.stdout.write(`\n[tool ${ev.toolName}] ${ev.content}\n`);
       if (ev.role === "error") process.stderr.write(`\n[error] ${ev.error}\n`);
       if (ev.role === "done") process.stdout.write("\n");
+      if (ev.role === "assistant_final" && ev.stats?.usage) {
+        // `reasonix run` is often used in CI / scripting — we want
+        // those turns to show up in `reasonix stats` too so the
+        // dashboard reflects all DeepSeek spend, not just TUI sessions.
+        appendUsage({ session: null, model: ev.stats.model, usage: ev.stats.usage });
+      }
       // Persist every non-streaming event — deltas would flood the file and
       // aren't useful for replay (replay renders final content, not keystrokes).
       if (transcriptStream && ev.role !== "assistant_delta") {

src/cli/commands/stats.ts

@@ -1,15 +1,60 @@
+/**
+ * `reasonix stats` — two modes, decided by whether the user passed
+ * a transcript path.
+ *
+ *   - `reasonix stats`          → cross-session usage dashboard
+ *                                  (reads `~/.reasonix/usage.jsonl`)
+ *   - `reasonix stats <path>`   → summary of a single JSONL transcript
+ *                                  (original v0.1 behavior, kept so
+ *                                   existing scripts don't break)
+ *
+ * The dashboard is the new story: for every turn `reasonix chat|code|run`
+ * has ever executed on this machine, we aggregate tokens + cost + the
+ * equivalent Claude spend, and print rolling-window totals (today /
+ * week / month / all-time). The savings column is the Pillar 1 pitch
+ * made concrete — "you paid $X; Claude would have charged $Y, a N%
+ * reduction."
+ */
+
 import { existsSync, readFileSync } from "node:fs";
+import {
+  type UsageAggregate,
+  type UsageBucket,
+  aggregateUsage,
+  bucketCacheHitRatio,
+  bucketSavingsFraction,
+  defaultUsageLogPath,
+  formatLogSize,
+  readUsageLog,
+} from "../../usage.js";
 
 export interface StatsOptions {
-  transcript: string;
+  /** Optional transcript path. Absent → dashboard mode. */
+  transcript?: string;
+  /** Override usage log location (tests). */
+  logPath?: string;
+  /** Inject a fixed timestamp (tests) so rolling windows are deterministic. */
+  now?: number;
 }
 
 export function statsCommand(opts: StatsOptions): void {
-  if (!existsSync(opts.transcript)) {
-    console.error(`no such transcript: ${opts.transcript}`);
+  if (opts.transcript) {
+    transcriptSummary(opts.transcript);
+    return;
+  }
+  dashboard(opts);
+}
+
+// ---------------------------------------------------------------------
+// Transcript summary — legacy v0.1 behavior, preserved verbatim.
+// ---------------------------------------------------------------------
+
+function transcriptSummary(path: string): void {
+  if (!existsSync(path)) {
+    console.error(`no such transcript: ${path}`);
     process.exit(1);
   }
-  const lines = readFileSync(opts.transcript, "utf8").split(/\r?\n/).filter(Boolean);
+  const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean);
   let assistantTurns = 0;
   let toolCalls = 0;
   let lastTurn = 0;
@@ -23,8 +68,121 @@ export function statsCommand(opts: StatsOptions): void {
       /* skip */
     }
   }
-  console.log(`transcript:       ${opts.transcript}`);
+  console.log(`transcript:       ${path}`);
   console.log(`assistant turns:  ${assistantTurns}`);
   console.log(`tool invocations: ${toolCalls}`);
   console.log(`last turn index:  ${lastTurn}`);
 }
+
+// ---------------------------------------------------------------------
+// Dashboard — aggregates ~/.reasonix/usage.jsonl.
+// ---------------------------------------------------------------------
+
+function dashboard(opts: StatsOptions): void {
+  const path = opts.logPath ?? defaultUsageLogPath();
+  const records = readUsageLog(path);
+  if (records.length === 0) {
+    console.log("no usage data yet.");
+    console.log("");
+    console.log(`  ${path}`);
+    console.log("");
+    console.log("run `reasonix chat`, `reasonix code`, or `reasonix run <task>` — every turn");
+    console.log("appends one line to the log and `reasonix stats` will roll it up.");
+    return;
+  }
+
+  const agg = aggregateUsage(records, { now: opts.now });
+  console.log(renderDashboard(agg, path));
+}
+
+/** Pure renderer — pulled out so tests can assert on the string directly. */
+export function renderDashboard(agg: UsageAggregate, logPath: string): string {
+  const lines: string[] = [];
+  const size = formatLogSize(logPath);
+  lines.push(`Reasonix usage — ${logPath}${size ? ` (${size})` : ""}`);
+  lines.push("");
+  lines.push(header());
+  lines.push(divider());
+  for (const b of agg.buckets) {
+    lines.push(bucketRow(b));
+  }
+  lines.push("");
+
+  // Model + session breakdown — both trim to top 3 so a user with 20
+  // sessions doesn't drown the table.
+  if (agg.byModel.length > 0) {
+    const totalTurns = agg.buckets[agg.buckets.length - 1]?.turns ?? 0;
+    const top = agg.byModel[0];
+    if (top && totalTurns > 0) {
+      const pct = ((top.turns / totalTurns) * 100).toFixed(0);
+      lines.push(`most used model:   ${top.model} (${pct}% of turns)`);
+    }
+  }
+  if (agg.bySession.length > 0) {
+    const top = agg.bySession[0];
+    if (top) lines.push(`top session:       ${top.session} (${top.turns} turns)`);
+  }
+  if (agg.firstSeen) {
+    lines.push(`tracked since:     ${new Date(agg.firstSeen).toISOString().slice(0, 10)}`);
+  }
+  if (agg.subagents) {
+    lines.push("");
+    lines.push(renderSubagentSection(agg.subagents));
+  }
+  return lines.join("\n");
+}
+
+function renderSubagentSection(sub: NonNullable<UsageAggregate["subagents"]>): string {
+  const lines: string[] = [];
+  const seconds = (sub.totalDurationMs / 1000).toFixed(1);
+  lines.push(
+    `subagent activity: ${sub.total} run(s) · $${sub.costUsd.toFixed(6)} · ${seconds}s total`,
+  );
+  // Show at most 5 skills so the section never dwarfs the main table.
+  const top = sub.bySkill.slice(0, 5);
+  for (const s of top) {
+    const sec = (s.durationMs / 1000).toFixed(1);
+    lines.push(
+      `  ${pad(s.skillName, 18)} ${pad(`${s.count}`, 4, "right")}  $${s.costUsd.toFixed(6)}  ${sec}s`,
+    );
+  }
+  if (sub.bySkill.length > top.length) {
+    lines.push(`  (+${sub.bySkill.length - top.length} more)`);
+  }
+  return lines.join("\n");
+}
+
+function header(): string {
+  // Fixed column widths so alignment works in any TTY.
+  return [
+    pad("", 10),
+    pad("turns", 8, "right"),
+    pad("cache hit", 10, "right"),
+    pad("cost (USD)", 14, "right"),
+    pad("vs Claude", 14, "right"),
+    pad("saved", 10, "right"),
+  ].join("  ");
+}
+
+function divider(): string {
+  return "-".repeat(70);
+}
+
+function bucketRow(b: UsageBucket): string {
+  const hit = bucketCacheHitRatio(b);
+  const savings = bucketSavingsFraction(b);
+  return [
+    pad(b.label, 10),
+    pad(b.turns.toString(), 8, "right"),
+    pad(b.turns > 0 ? `${(hit * 100).toFixed(1)}%` : "—", 10, "right"),
+    pad(b.turns > 0 ? `$${b.costUsd.toFixed(6)}` : "—", 14, "right"),
+    pad(b.turns > 0 ? `$${b.claudeEquivUsd.toFixed(4)}` : "—", 14, "right"),
+    pad(b.turns > 0 && savings > 0 ? `${(savings * 100).toFixed(1)}%` : "—", 10, "right"),
+  ].join("  ");
+}
+
+function pad(s: string, width: number, align: "left" | "right" = "left"): string {
+  if (s.length >= width) return s;
+  const fill = " ".repeat(width - s.length);
+  return align === "right" ? `${fill}${s}` : `${s}${fill}`;
+}

src/cli/commands/update.ts

@@ -0,0 +1,143 @@
+/**
+ * `reasonix update` — self-upgrade command.
+ *
+ * Talks to the npm registry, compares against the running version,
+ * and either runs `npm install -g reasonix@latest` (global install)
+ * or advises how to refresh the npx cache (ephemeral install).
+ *
+ * The decision logic is factored into `planUpdate()` so it can be
+ * unit-tested without spawning child processes or hitting the
+ * network. `updateCommand()` is the thin CLI wrapper that calls
+ * `getLatestVersion`, passes the result into `planUpdate`, and
+ * executes any suggested command.
+ */
+
+import { spawn } from "node:child_process";
+import { VERSION, compareVersions, getLatestVersion, isNpxInstall } from "../../version.js";
+
+export type UpdateAction = "up-to-date" | "newer-local" | "npx-hint" | "run-npm-install";
+
+export interface UpdatePlan {
+  action: UpdateAction;
+  /** Human-readable summary; the CLI prints this verbatim. */
+  message: string;
+  /**
+   * Argv for the install command when `action === "run-npm-install"`.
+   * Absent otherwise. Kept as array so the CLI can pass it straight
+   * to `spawn` without re-parsing shell syntax.
+   */
+  command?: string[];
+}
+
+export interface PlanUpdateInput {
+  current: string;
+  latest: string;
+  /** Overrides `isNpxInstall()` (tests). */
+  npx?: boolean;
+}
+
+/**
+ * Pure decision function: given current + latest + install kind,
+ * decide what the CLI should do. No I/O.
+ *
+ *   newer-local     — current > latest (dev build, local publish)
+ *   up-to-date      — current === latest
+ *   npx-hint        — current < latest AND running under npx
+ *   run-npm-install — current < latest AND running as a real install
+ */
+export function planUpdate(input: PlanUpdateInput): UpdatePlan {
+  const diff = compareVersions(input.current, input.latest);
+  if (diff > 0) {
+    return {
+      action: "newer-local",
+      message: `current (${input.current}) is newer than the published ${input.latest} — nothing to do.`,
+    };
+  }
+  if (diff === 0) {
+    return { action: "up-to-date", message: `reasonix ${input.current} is up to date.` };
+  }
+  if (input.npx) {
+    return {
+      action: "npx-hint",
+      message: [
+        `reasonix ${input.latest} is available.`,
+        "you're running via npx — the next `npx reasonix ...` launch will auto-fetch",
+        "the latest (npx caches packages for a short window). to force a refresh",
+        "sooner, clear the cache: `npm cache clean --force`.",
+      ].join("\n"),
+    };
+  }
+  return {
+    action: "run-npm-install",
+    message: `upgrading reasonix ${input.current} → ${input.latest}`,
+    command: ["npm", "install", "-g", "reasonix@latest"],
+  };
+}
+
+export interface UpdateCommandOptions {
+  /** Skip spawning npm; print the decision only. */
+  dryRun?: boolean;
+  /** Test seam: override the registry lookup. Returns null = offline. */
+  fetchLatest?: () => Promise<string | null>;
+  /** Test seam: override the npx detector. */
+  isNpx?: () => boolean;
+  /** Test seam: override the spawner. Must return exit code. */
+  spawnInstall?: (argv: string[]) => Promise<number>;
+  /** Test seam: stdout writer. */
+  write?: (msg: string) => void;
+  /** Test seam: process exit — tests don't want to tear down vitest. */
+  exit?: (code: number) => void;
+}
+
+function defaultSpawn(argv: string[]): Promise<number> {
+  return new Promise((resolve, reject) => {
+    // `shell: true` on Windows is what lets `npm` resolve to `npm.cmd`
+    // without routing through our `prepareSpawn` helper. The args here
+    // are literal strings under our control — no user input flows in,
+    // so injection is not a concern. Avoiding `prepareSpawn` keeps
+    // this command free of a dep on the shell tools module.
+    const child = spawn(argv[0]!, argv.slice(1), {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => resolve(code ?? 1));
+  });
+}
+
+/**
+ * Run the update command. Prints a banner, resolves the latest
+ * version, prints the plan, and (unless `--dry-run`) executes the
+ * install when applicable.
+ */
+export async function updateCommand(opts: UpdateCommandOptions = {}): Promise<void> {
+  const write = opts.write ?? ((m: string) => process.stdout.write(m));
+  const exit = opts.exit ?? ((c: number) => process.exit(c));
+  const fetchLatest = opts.fetchLatest ?? (() => getLatestVersion({ force: true }));
+  const isNpx = opts.isNpx ?? isNpxInstall;
+  const doSpawn = opts.spawnInstall ?? defaultSpawn;
+
+  write(`current: reasonix ${VERSION}\n`);
+  const latest = await fetchLatest();
+  if (!latest) {
+    write("could not reach registry.npmjs.org — check your network.\n");
+    exit(1);
+    return;
+  }
+  write(`latest:  reasonix ${latest}\n`);
+
+  const plan = planUpdate({ current: VERSION, latest, npx: isNpx() });
+  write(`\n${plan.message}\n`);
+
+  if (plan.action !== "run-npm-install" || !plan.command) return;
+  if (opts.dryRun) {
+    write(`(dry run) would run: ${plan.command.join(" ")}\n`);
+    return;
+  }
+  write(`\nrunning: ${plan.command.join(" ")}\n`);
+  const code = await doSpawn(plan.command);
+  if (code !== 0) {
+    write(`\nnpm exited with code ${code}. upgrade did not complete.\n`);
+    exit(code);
+  }
+}

src/cli/index.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { readConfig } from "../config.js";
 import { VERSION } from "../index.js";
+import { applyMemoryStack } from "../user-memory.js";
 import { chatCommand } from "./commands/chat.js";
 import { codeCommand } from "./commands/code.js";
 import { diffCommand } from "./commands/diff.js";
@@ -11,11 +12,23 @@ import { runCommand } from "./commands/run.js";
 import { sessionsCommand } from "./commands/sessions.js";
 import { setupCommand } from "./commands/setup.js";
 import { statsCommand } from "./commands/stats.js";
+import { updateCommand } from "./commands/update.js";
 import { versionCommand } from "./commands/version.js";
 import { resolveDefaults } from "./resolve.js";
 
-const DEFAULT_SYSTEM =
-  "You are Reasonix, a helpful DeepSeek-powered assistant. Be concise and accurate. Use tools when available.";
+const DEFAULT_SYSTEM = `You are Reasonix, a helpful DeepSeek-powered assistant. Be concise and accurate. Use tools when available.
+
+# Cite or shut up — non-negotiable
+
+Every factual claim about a codebase must be backed by evidence. Reasonix VALIDATES your citations — broken paths render in **red strikethrough with ❌** in front of the user.
+
+**Positive claims** — append a markdown link:
+- ✅ \`The MCP client supports listResources [listResources](src/mcp/client.ts:142).\`
+- ❌ \`The MCP client supports listResources.\` ← unverifiable, do not write.
+
+**Negative claims** ("X is missing", "Y isn't implemented", "lacks Z") are the #1 hallucination shape. STOP before writing them. If you have a search tool, call it first; if the search returns nothing, cite the search itself as evidence (\`No matches for "foo" in src/\`). If you have no tool, qualify hard: "I haven't verified — this is a guess."
+
+Asserting absence without checking is how evaluative answers go wrong. Treat the urge to write "missing" as a red flag in your own reasoning.`;
 
 const program = new Command();
 program
@@ -37,7 +50,7 @@ program.action(async () => {
   const defaults = resolveDefaults({});
   await chatCommand({
     model: defaults.model,
-    system: DEFAULT_SYSTEM,
+    system: applyMemoryStack(DEFAULT_SYSTEM, process.cwd()),
     harvest: defaults.harvest,
     branch: defaults.branch,
     session: defaults.session,
@@ -55,17 +68,26 @@ program
 program
   .command("code [dir]")
   .description(
-    "Code-editing chat — filesystem MCP auto-bridged at <dir> (default: cwd), coding system prompt, smart preset. Model proposes SEARCH/REPLACE blocks; Reasonix applies them to disk.",
+    "Code-editing chat — filesystem tools rooted at <dir> (default: cwd), coding system prompt, deepseek-reasoner. Model proposes SEARCH/REPLACE blocks; Reasonix applies them to disk.",
   )
   .option("-m, --model <id>", "Override default reasoner model")
   .option("--no-session", "Disable session persistence for this run")
+  .option("-r, --resume", "Skip the session picker — always continue prior messages")
+  .option("-n, --new", "Skip the session picker — always wipe prior messages and start fresh")
   .option("--transcript <path>", "Write a JSONL transcript to this path")
+  .option(
+    "--harvest",
+    "Extract typed plan state from R1 reasoning (Pillar 2). Adds ~10-15% cost per turn. Off by default in code mode.",
+  )
   .action(async (dir: string | undefined, opts) => {
     await codeCommand({
       dir,
       model: opts.model,
       noSession: opts.session === false,
       transcript: opts.transcript,
+      forceResume: !!opts.resume,
+      forceNew: !!opts.new,
+      harvest: !!opts.harvest,
     });
   });
 
@@ -90,6 +112,8 @@ program
   )
   .option("--session <name>", "Use a named session (default: from config, usually 'default').")
   .option("--no-session", "Disable session persistence for this run (ephemeral chat)")
+  .option("-r, --resume", "Skip the session picker — always continue prior messages")
+  .option("-n, --new", "Skip the session picker — always wipe prior messages and start fresh")
   .option(
     "--mcp <spec>",
     'MCP server spec; repeatable. "name=cmd args...", "cmd args...", or a URL (http/https → SSE transport). Overrides config.mcp when provided.',
@@ -113,13 +137,15 @@ program
     });
     await chatCommand({
       model: defaults.model,
-      system: opts.system,
+      system: applyMemoryStack(opts.system, process.cwd()),
       transcript: opts.transcript,
       harvest: defaults.harvest,
       branch: defaults.branch,
       session: defaults.session,
       mcp: defaults.mcp,
       mcpPrefix: opts.mcpPrefix,
+      forceResume: !!opts.resume,
+      forceNew: !!opts.new,
     });
   });
 
@@ -159,7 +185,7 @@ program
     await runCommand({
       task,
       model: defaults.model,
-      system: opts.system,
+      system: applyMemoryStack(opts.system, process.cwd()),
       harvest: defaults.harvest,
       branch: defaults.branch,
       transcript: opts.transcript,
@@ -169,9 +195,12 @@ program
   });
 
 program
-  .command("stats <transcript>")
-  .description("Summarize a JSONL transcript produced by `reasonix chat --transcript`.")
-  .action((transcript: string) => {
+  .command("stats [transcript]")
+  .description(
+    "Show usage dashboard (today / week / month / all-time · turns · cache hit · cost · savings vs Claude). " +
+      "Pass a transcript path to fall back to the per-file summary (assistant turns + tool calls).",
+  )
+  .action((transcript: string | undefined) => {
     statsCommand({ transcript });
   });
 
@@ -251,6 +280,16 @@ mcp
 
 program.command("version").description("Print Reasonix version.").action(versionCommand);
 
+program
+  .command("update")
+  .description(
+    "Check the npm registry for a newer Reasonix and install it. Detects npx vs global install; for npx users, prints a cache-refresh hint instead of running `npm i -g`.",
+  )
+  .option("--dry-run", "Print the plan without executing the install")
+  .action(async (opts: { dryRun?: boolean }) => {
+    await updateCommand({ dryRun: !!opts.dryRun });
+  });
+
 program.parseAsync(process.argv).catch((err) => {
   console.error(err);
   process.exit(1);

src/cli/ui/AtMentionSuggestions.tsx

@@ -0,0 +1,86 @@
+import { Box, Text } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig.jsx = "react" needs React in value scope for JSX compilation
+import React from "react";
+
+export interface AtMentionSuggestionsProps {
+  /**
+   * Current matching file paths, ranked by the picker. `null` means
+   * "not in @-prefix mode" — render nothing. Empty array means "in @
+   * mode but no files match that partial" — render a hint.
+   */
+  matches: readonly string[] | null;
+  /** Index (within `matches`) of the currently highlighted row. */
+  selectedIndex: number;
+  /** The partial query the user typed after `@`. Shown in the hint row. */
+  query: string;
+}
+
+/**
+ * Floating `@`-mention picker. Rendered below the input box when the
+ * user is typing an `@…` prefix in code mode. Navigation state lives
+ * in the parent (App.tsx owns `atSelected`) — this component is pure
+ * display. Mirrors {@link SlashSuggestions} shape so the keybindings
+ * and layout feel identical across the two pickers.
+ */
+export function AtMentionSuggestions({
+  matches,
+  selectedIndex,
+  query,
+}: AtMentionSuggestionsProps): React.ReactElement | null {
+  if (matches === null) return null;
+  if (matches.length === 0) {
+    return (
+      <Box paddingX={1}>
+        <Text color="yellow">no files match "@{query}"</Text>
+        <Text dimColor>
+          {" "}
+          — keep typing, or Backspace to edit. Paths resolve from the code root.
+        </Text>
+      </Box>
+    );
+  }
+  const MAX = 8;
+  const total = matches.length;
+  const windowStart =
+    total <= MAX ? 0 : Math.max(0, Math.min(selectedIndex - Math.floor(MAX / 2), total - MAX));
+  const shown = matches.slice(windowStart, windowStart + MAX);
+  const hiddenAbove = windowStart;
+  const hiddenBelow = total - windowStart - shown.length;
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      {hiddenAbove > 0 ? <Text dimColor> ↑ {hiddenAbove} more above</Text> : null}
+      {shown.map((path, i) => (
+        <FileRow key={path} path={path} isSelected={windowStart + i === selectedIndex} />
+      ))}
+      {hiddenBelow > 0 ? <Text dimColor> ↓ {hiddenBelow} more below</Text> : null}
+      <Text dimColor> [↑↓] navigate · [Tab]/[Enter] pick · file content inlined on send</Text>
+    </Box>
+  );
+}
+
+function FileRow({ path, isSelected }: { path: string; isSelected: boolean }) {
+  const marker = isSelected ? "▸" : " ";
+  // Split the path so the basename visually pops — same dropdown
+  // affordance as VS Code's Quick Open.
+  const slash = path.lastIndexOf("/");
+  const dir = slash >= 0 ? `${path.slice(0, slash)}/` : "";
+  const base = slash >= 0 ? path.slice(slash + 1) : path;
+  if (isSelected) {
+    return (
+      <Box>
+        <Text bold color="cyan">
+          {marker} {base}
+        </Text>
+        <Text color="cyan">{dir ? `  ${dir}` : ""}</Text>
+      </Box>
+    );
+  }
+  return (
+    <Box>
+      <Text dimColor>
+        {marker} {base}
+        {dir ? `  ${dir}` : ""}
+      </Text>
+    </Box>
+  );
+}

src/cli/ui/EventLog.tsx

@@ -1,4 +1,4 @@
-import { Box, Text } from "ink";
+import { Box, Text, useStdout } from "ink";
 import React from "react";
 import { type TypedPlanState, isPlanStateEmpty } from "../../harvest.js";
 import type { BranchProgress, BranchSummary } from "../../loop.js";
@@ -22,16 +22,62 @@ export interface DisplayEvent {
   repair?: string;
   streaming?: boolean;
   toolCallBuild?: { name: string; chars: number };
+  /**
+   * Render a thin horizontal rule above this event. Used to mark
+   * "start of a new user turn" so long scrollbacks get visual
+   * pacing — without it, five-turn sessions read as one wall of
+   * text. Only the *first* user message in a session should leave
+   * this off; App.tsx sets it based on whether history is empty.
+   */
+  leadSeparator?: boolean;
 }
 
-export const EventRow = React.memo(function EventRow({ event }: { event: DisplayEvent }) {
+/**
+ * Reasonix visual language: every event is anchored by a geometric
+ * glyph in its role color. Together they form a consistent alphabet
+ * (◇ ◆ ▣ ▥ ▲ ✦) the eye learns fast — no text labels needed after
+ * the first couple of turns. `◈` is the brand mark, reserved for
+ * the app header.
+ */
+const ROLE_GLYPH = {
+  user: "◇",
+  assistant: "◆",
+  assistantPulse: "◇", // pulse alternate for streaming state
+  toolOk: "▣",
+  toolErr: "▥",
+  warning: "▲",
+  error: "✦",
+} as const;
+
+function RoleGlyph({
+  glyph,
+  color,
+}: {
+  glyph: string;
+  color: "cyan" | "green" | "yellow" | "red" | "magenta" | "blue";
+}) {
+  return (
+    <Text color={color} bold>
+      {glyph}
+    </Text>
+  );
+}
+
+export const EventRow = React.memo(function EventRow({
+  event,
+  projectRoot,
+}: {
+  event: DisplayEvent;
+  projectRoot?: string;
+}) {
   if (event.role === "user") {
     return (
-      <Box>
-        <Text bold color="cyan">
-          you ›{" "}
+      <Box marginTop={event.leadSeparator ? 1 : 0}>
+        <RoleGlyph glyph={ROLE_GLYPH.user} color="cyan" />
+        <Text>
+          {"  "}
+          {event.text}
         </Text>
-        <Text>{event.text}</Text>
       </Box>
     );
   }
@@ -40,29 +86,34 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
     return (
       <Box flexDirection="column" marginTop={1}>
         <Box>
-          <Text bold color="green">
-            assistant
-          </Text>
+          <RoleGlyph glyph={ROLE_GLYPH.assistant} color="green" />
+          {event.stats ? <Text dimColor>{`  ${event.stats.model}`}</Text> : null}
+        </Box>
+        <Box flexDirection="column" paddingLeft={2} marginTop={1}>
+          {event.branch ? <BranchBlock branch={event.branch} /> : null}
+          {event.reasoning ? <ReasoningBlock reasoning={event.reasoning} /> : null}
+          {!isPlanStateEmpty(event.planState) ? (
+            <PlanStateBlock planState={event.planState!} />
+          ) : null}
+          {event.text ? (
+            <Markdown text={event.text} projectRoot={projectRoot} />
+          ) : (
+            <Text dimColor>(no content)</Text>
+          )}
+          {event.stats ? <StatsLine stats={event.stats} /> : null}
+          {event.repair ? <Text color="magenta">{event.repair}</Text> : null}
         </Box>
-        {event.branch ? <BranchBlock branch={event.branch} /> : null}
-        {event.reasoning ? <ReasoningBlock reasoning={event.reasoning} /> : null}
-        {!isPlanStateEmpty(event.planState) ? (
-          <PlanStateBlock planState={event.planState!} />
-        ) : null}
-        {event.text ? <Markdown text={event.text} /> : <Text dimColor>(no content)</Text>}
-        {event.stats ? <StatsLine stats={event.stats} /> : null}
-        {event.repair ? <Text color="magenta">{event.repair}</Text> : null}
       </Box>
     );
   }
   if (event.role === "tool") {
     // `flattenMcpResult` prefixes server-side errors with "ERROR: ".
-    // Render those in red with a ✗ marker so they don't blend into
-    // successful tool output (yellow) — the failure mode is what the
-    // model most likely needs to act on next, and the user needs to
-    // see at a glance.
+    // Render the tool glyph in red with a ✗ direction marker so the
+    // failure mode is unmissable — it's the signal the model needs
+    // most for its next decision.
     const isError = event.text.startsWith("ERROR:");
     const color = isError ? "red" : "yellow";
+    const glyph = isError ? ROLE_GLYPH.toolErr : ROLE_GLYPH.toolOk;
     const marker = isError ? "✗" : "→";
     // `edit_file` results get a dedicated diff renderer — colored
     // line-by-line so `-` removals show red, `+` additions show
@@ -73,25 +124,31 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
       (event.toolName === "edit_file" || event.toolName?.endsWith("_edit_file")) && !isError;
     return (
       <Box flexDirection="column" marginTop={1}>
-        <Text color={color}>{`tool<${event.toolName ?? "?"}>  ${marker}`}</Text>
-        {isEditFile ? (
-          <EditFileDiff text={event.text} />
-        ) : (
-          <Text color={isError ? "red" : undefined} dimColor={!isError}>
-            {" "}
-            {truncate(event.text, 400)}
-          </Text>
-        )}
+        <Box>
+          <RoleGlyph glyph={glyph} color={color} />
+          <Text color={color} bold>{`  ${event.toolName ?? "?"}`}</Text>
+          <Text color={color} dimColor>{`  ${marker}`}</Text>
+        </Box>
+        <Box flexDirection="column" paddingLeft={2} marginTop={1}>
+          {isEditFile ? (
+            <EditFileDiff text={event.text} />
+          ) : (
+            <Text color={isError ? "red" : undefined} dimColor={!isError}>
+              {truncate(event.text, 400)}
+            </Text>
+          )}
+        </Box>
       </Box>
     );
   }
   if (event.role === "error") {
     return (
       <Box marginTop={1}>
-        <Text color="red" bold>
-          error{" "}
+        <RoleGlyph glyph={ROLE_GLYPH.error} color="red" />
+        <Text color="red">
+          {"  "}
+          {event.text}
         </Text>
-        <Text color="red">{event.text}</Text>
       </Box>
     );
   }
@@ -105,8 +162,11 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
   if (event.role === "warning") {
     return (
       <Box>
-        <Text color="yellow">▸ </Text>
-        <Text color="yellow">{event.text}</Text>
+        <RoleGlyph glyph={ROLE_GLYPH.warning} color="yellow" />
+        <Text color="yellow">
+          {"  "}
+          {event.text}
+        </Text>
       </Box>
     );
   }
@@ -117,6 +177,32 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
   );
 });
 
+/**
+ * Thin horizontal rule between turns with a cyan ◆ centered as the
+ * Reasonix mark. Past-turn separators live inside `<Static>` (Ink's
+ * render-once optimization), so animation here would freeze at
+ * tick=0 on every past turn — we keep it static by design. The
+ * animated heartbeat lives in PulsingAssistantGlyph (current turn)
+ * and the Wordmark (StatsPanel) where rerender is free.
+ */
+function TurnSeparator() {
+  const { stdout } = useStdout();
+  const cols = stdout?.columns ?? 80;
+  const width = Math.max(16, cols - 2);
+  const half = Math.floor((width - 3) / 2);
+  const left = "─".repeat(half);
+  const right = "─".repeat(width - half - 3);
+  return (
+    <Box marginTop={1} marginBottom={1}>
+      <Text dimColor>{left}</Text>
+      <Text color="cyan" bold>
+        {" ◆ "}
+      </Text>
+      <Text dimColor>{right}</Text>
+    </Box>
+  );
+}
+
 /**
  * Render the payload of an `edit_file` tool result with proper
  * diff coloring: first line is the header ("edited X (A→B chars)"),
@@ -183,7 +269,7 @@ function BranchBlock({ branch }: { branch: BranchSummary }) {
   return (
     <Box>
       <Text color="blue">
-        {"🔀 branched "}
+        {"⎇ branched "}
         <Text bold>{branch.budget}</Text>
         {` samples → picked #${branch.chosenIndex}   `}
         <Text dimColor>{per}</Text>
@@ -202,11 +288,15 @@ function ReasoningBlock({ reasoning }: { reasoning: string }) {
   // Users can dump the full reasoning with `/think` if needed.
   const preview =
     flat.length <= max ? flat : `… (+${flat.length - max} earlier chars) ${flat.slice(-max)}`;
+  // ▏ (LEFT ONE EIGHTH BLOCK) renders as a thin vertical rule at the
+  // cell edge — subtler than the role-level ▎ above, giving a
+  // visual hierarchy: thick bar = role, thin bar = nested detail
+  // under that role (thinking, stats, citations, etc).
   return (
     <Box marginBottom={1}>
+      <Text dimColor>▏ </Text>
       <Text dimColor italic>
-        {"↳ thinking: "}
-        {preview}
+        thinking {preview}
       </Text>
     </Box>
   );
@@ -224,6 +314,22 @@ function Elapsed() {
   return <Text dimColor>{`${mm}:${ss}`}</Text>;
 }
 
+/**
+ * Animated role glyph for the actively-streaming assistant. Alternates
+ * ◆ ↔ ◇ every ~480ms so the user can see the model is alive even
+ * during R1's long pre-first-byte silence. Settles back to a static
+ * ◆ once the turn ends (StreamingAssistant is unmounted).
+ */
+function PulsingAssistantGlyph() {
+  const tick = useTick();
+  const on = Math.floor(tick / 4) % 2 === 0;
+  return (
+    <Text color="green" bold>
+      {on ? ROLE_GLYPH.assistant : ROLE_GLYPH.assistantPulse}
+    </Text>
+  );
+}
+
 function StreamingAssistant({ event }: { event: DisplayEvent }) {
   if (event.branchProgress) {
     const p = event.branchProgress;
@@ -232,15 +338,17 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {
       return (
         <Box flexDirection="column" marginTop={1}>
           <Box>
-            <Text bold color="green">
-              assistant{" "}
-            </Text>
+            <PulsingAssistantGlyph />
             <Text color="blue">
-              🔀 launching {p.total} parallel samples (R1 thinking in parallel)…{" "}
+              {"  ⎇ launching "}
+              {p.total}
+              {" parallel samples (R1 thinking in parallel)…  "}
             </Text>
             <Elapsed />
           </Box>
-          <Text dimColor>{"  "}spread across T=0.0/0.5/1.0 · typical wait 30-90s for reasoner</Text>
+          <Text color="yellow">
+            {"  "}spread across T=0.0/0.5/1.0 · reasoner typically takes 30-90s — this is normal
+          </Text>
         </Box>
       );
     }
@@ -248,11 +356,13 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {
     return (
       <Box flexDirection="column" marginTop={1}>
         <Box>
-          <Text bold color="green">
-            assistant{" "}
-          </Text>
+          <PulsingAssistantGlyph />
           <Text color="blue">
-            🔀 branching {p.completed}/{p.total} ({pct}%){" "}
+            {"  ⎇ branching "}
+            {p.completed}/{p.total}
+            {" ("}
+            {pct}
+            {"%)  "}
           </Text>
           <Elapsed />
         </Box>
@@ -309,9 +419,8 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {
   return (
     <Box flexDirection="column" marginTop={1}>
       <Box>
-        <Text bold color="green">
-          assistant{" "}
-        </Text>
+        <PulsingAssistantGlyph />
+        <Text>{"  "}</Text>
         <Pulse />
         <Text color={labelColor}>{` ${label} `}</Text>
         <Elapsed />
@@ -323,17 +432,27 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {
       ) : null}
       {tail ? (
         <Text dimColor>▸ {tail}</Text>
+      ) : preFirstByte ? (
+        // Non-dim yellow: first-time users misread the dim version as
+        // "app frozen". The reassurance has to be VISIBLE to do its job.
+        <Text color="yellow" italic>
+          {"  waiting for first byte — this is normal, typically 5-60s depending on model + load"}
+        </Text>
       ) : reasoningOnly ? (
-        <Text color="yellow" dimColor>
+        <Text color="yellow" italic>
           {
-            "  R1 is thinking before it speaks — body text starts when reasoning completes (typically 20-90s)."
+            "  R1 is thinking before it speaks — body text arrives when reasoning finishes (typically 20-90s, this is normal)"
           }
         </Text>
-      ) : (
-        <Text dimColor italic>
-          {"  connection open, first byte typically in 5-60s depending on model + load"}
+      ) : toolCallOnly ? (
+        <Text color="magenta" italic>
+          {"  tool-call arguments streaming — the model is about to dispatch a tool"}
         </Text>
-      )}
+      ) : event.reasoning ? (
+        <Text color="yellow" italic>
+          {"  R1 still reasoning — body text or tool call arrives when thinking finishes"}
+        </Text>
+      ) : null}
     </Box>
   );
 }
@@ -359,19 +478,47 @@ function lastLine(s: string, maxChars: number): string {
 function StatsLine({ stats }: { stats: TurnStats }) {
   const hit = (stats.cacheHitRatio * 100).toFixed(1);
   return (
-    <Text dimColor>
-      {"  ↳ cache "}
-      {hit}
-      {"% · tokens "}
-      {stats.usage.promptTokens}
-      {"→"}
-      {stats.usage.completionTokens}
-      {" · $"}
-      {stats.cost.toFixed(6)}
-    </Text>
+    <Box>
+      <Text dimColor>▏ </Text>
+      <Text dimColor>
+        {"cache "}
+        {hit}
+        {"% · tokens "}
+        {stats.usage.promptTokens}
+        {" → "}
+        {stats.usage.completionTokens}
+        {" · $"}
+        {stats.cost.toFixed(6)}
+      </Text>
+    </Box>
   );
 }
 
+/**
+ * Show the *tail* of a long tool result by default — the useful signal
+ * (return value, summary, error line) usually lives at the end, not the
+ * top-of-file boilerplate. For `ERROR:`-prefixed results, keep the
+ * first line intact (that's the actual error message) AND include the
+ * tail, so stack-trace endings stay visible too.
+ *
+ * Rendered like: `(+N earlier chars) …<tail>` so users can tell at a
+ * glance that something was elided. `/tool N` still dumps the full
+ * content for cases where the middle matters.
+ */
 function truncate(s: string, max: number): string {
-  return s.length <= max ? s : `${s.slice(0, max)}… (+${s.length - max} chars)`;
+  if (s.length <= max) return s;
+  if (s.startsWith("ERROR:")) {
+    const firstNl = s.indexOf("\n");
+    const firstLine = firstNl === -1 ? s : s.slice(0, firstNl);
+    // If the first line alone is bigger than max, just show it truncated.
+    if (firstLine.length >= max) {
+      return `${firstLine.slice(0, max)}… (+${s.length - max} chars — /tool N for full)`;
+    }
+    const budget = max - firstLine.length - 10; // reserve space for separator + ellipsis
+    const tail = s.slice(-budget);
+    const skipped = s.length - firstLine.length - tail.length;
+    return `${firstLine}\n… (+${skipped} chars) …\n${tail}`;
+  }
+  const skipped = s.length - max;
+  return `… (+${skipped} earlier chars — /tool N for full) …\n${s.slice(-max)}`;
 }

src/cli/ui/PlanConfirm.tsx

@@ -0,0 +1,170 @@
+/**
+ * Modal-style approval for a `submit_plan` proposal.
+ *
+ * Three choices:
+ *   1. Approve + implement — exits plan mode, pushes a synthetic user
+ *      message telling the model to implement the plan now.
+ *   2. Refine — stays in plan mode; tells the model to explore more
+ *      and submit an improved plan.
+ *   3. Cancel — exits plan mode, drops the plan, tells the model the
+ *      user didn't want any of it.
+ *
+ * Mirrors ShellConfirm in structure (border, SingleSelect, three
+ * options, no y/n hotkey — mid-typing triggers would be painful).
+ * The plan body is rendered verbatim above the picker so the user can
+ * actually read what they're approving.
+ */
+
+import { Box, Text } from "ink";
+import React from "react";
+import { SingleSelect } from "./Select.js";
+import { Markdown } from "./markdown.js";
+
+export type PlanConfirmChoice = "approve" | "refine" | "cancel";
+
+export interface PlanConfirmProps {
+  plan: string;
+  onChoose: (choice: PlanConfirmChoice) => void;
+  /**
+   * Cap on rendered plan length. A pathological 20-KB plan would push
+   * the picker off the bottom of the terminal; we show the head +
+   * "(…N chars truncated — /tool for full output)" instead. The picker
+   * itself gets the full plan (it's already been committed to the
+   * transcript via the tool result).
+   */
+  maxRenderedChars?: number;
+  projectRoot?: string;
+  /**
+   * Override the terminal-row count used for vertical clamping. Tests
+   * pass this to avoid depending on `process.stdout.rows`; runtime
+   * callers leave it unset and we read the real TTY size.
+   */
+  terminalRows?: number;
+}
+
+const DEFAULT_MAX_RENDERED = 2400;
+/**
+ * Reserved terminal rows for the picker chrome (border + header +
+ * divider + open-questions hint + SingleSelect with three options +
+ * footer + the assistant-turn block Ink already printed above).
+ * Empirically ~16; we round up to 18 for safety.
+ */
+const PICKER_CHROME_ROWS = 18;
+/**
+ * Rough markdown expansion factor. One source line commonly renders
+ * as 1–3 terminal rows: wrap on narrow terminals doubles long lines,
+ * code fences add top/bottom rules, list items get bullet indent,
+ * headings sometimes pick up blank rows. A factor of 2 is the
+ * conservative bet that lets us keep `bodyRowBudget` > 0 on a 24-row
+ * terminal while still guaranteeing the picker stays on-screen. If
+ * this is wrong in practice it's wrong in the "trim too aggressively"
+ * direction, which shows a truncation marker rather than flickering.
+ */
+const MARKDOWN_EXPANSION = 2;
+const MIN_BODY_ROWS = 4;
+
+/**
+ * Trim `text` to the first `maxLines` source lines, appending a
+ * truncation marker when it was cut. Source lines, NOT rendered rows
+ * — callers must divide their row budget by the expected markdown
+ * expansion factor before passing it here.
+ */
+export function clampBodyByLines(text: string, maxLines: number): string {
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) return text;
+  const kept = lines.slice(0, maxLines).join("\n");
+  const dropped = lines.length - maxLines;
+  return `${kept}\n\n… (${dropped} more lines truncated — resize the terminal to see more, or /tool for the full proposal)`;
+}
+
+function PlanConfirmInner({
+  plan,
+  onChoose,
+  maxRenderedChars,
+  projectRoot,
+  terminalRows,
+}: PlanConfirmProps) {
+  const cap = maxRenderedChars ?? DEFAULT_MAX_RENDERED;
+  const charTrunc = plan.length > cap;
+  const charCapped = charTrunc
+    ? `${plan.slice(0, cap)}\n\n… (${plan.length - cap} chars truncated — use /tool to view the full proposal)`
+    : plan;
+  // Vertical clamp. Flicker root-cause: when rendered content exceeds
+  // the TTY row count Ink falls back to "clear + full redraw" each
+  // frame, and every parent re-render redraws the big Markdown subtree.
+  // Capping the body to (rows - picker chrome) keeps the whole modal
+  // inside the terminal so Ink uses incremental diffs and the picker
+  // stops thrashing. See Bug A in 0.5.14.
+  const rows = terminalRows ?? process.stdout?.rows ?? 24;
+  const renderedBudget = Math.max(MIN_BODY_ROWS * MARKDOWN_EXPANSION, rows - PICKER_CHROME_ROWS);
+  // Divide by the expansion factor so source-line clamp produces a
+  // rendered height that actually fits the terminal. Without this the
+  // rendered body overflows → Ink clears + redraws each frame → flicker.
+  const sourceLineBudget = Math.max(MIN_BODY_ROWS, Math.floor(renderedBudget / MARKDOWN_EXPANSION));
+  const visible = clampBodyByLines(charCapped, sourceLineBudget);
+  // Crude signal for "the model left questions or risks for me" — the
+  // typical section headings. Triggers an extra hint toward the Refine
+  // option so users know where to answer them.
+  const hasOpenQuestions =
+    /^#{1,6}\s*(open[-\s]?questions?|risks?|unknowns?|assumptions?|unclear)/im.test(plan) ||
+    /^#{1,6}\s*(待确认|开放问题|风险|未知|假设|不确定)/im.test(plan);
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingX={1} marginY={1}>
+      <Box>
+        <Text bold color="cyan">
+          ▸ plan submitted — awaiting your review
+        </Text>
+      </Box>
+      <Box>
+        <Text color="cyan" dimColor>
+          {"──────────────────────────────────────────"}
+        </Text>
+      </Box>
+      <Box marginTop={1} flexDirection="column">
+        <Markdown text={visible} projectRoot={projectRoot} />
+      </Box>
+      {hasOpenQuestions ? (
+        <Box marginTop={1}>
+          <Text color="yellow">
+            ▲ the plan has open questions or flagged risks — pick{" "}
+            <Text bold>Refine / answer questions</Text> to write concrete answers before the model
+            moves on.
+          </Text>
+        </Box>
+      ) : null}
+      <Box marginTop={1}>
+        <SingleSelect
+          initialValue={hasOpenQuestions ? "refine" : "approve"}
+          items={[
+            {
+              value: "approve",
+              label: "Approve and implement",
+              hint: "Exit plan mode. The model starts executing. You'll get a text input to add any last instructions (or just press Enter to skip).",
+            },
+            {
+              value: "refine",
+              label: "Refine / answer questions",
+              hint: "Stay in plan mode. Write answers, modifications, or critiques; the model revises and re-submits.",
+            },
+            {
+              value: "cancel",
+              label: "Cancel",
+              hint: "Exit plan mode. Drop the plan; the model won't implement it.",
+            },
+          ]}
+          onSubmit={(v) => onChoose(v as PlanConfirmChoice)}
+          onCancel={() => onChoose("cancel")}
+          footer="[↑↓] navigate  ·  [Enter] select  ·  [Esc] cancel"
+        />
+      </Box>
+    </Box>
+  );
+}
+
+// React.memo: parent App re-renders every 120ms while the global ticker
+// is running (even with the live status rows hidden — context changes
+// propagate). Unless props change, skip re-rendering the heavy Markdown
+// subtree. Default shallow prop compare is fine — `plan` + `onChoose`
+// identity + `projectRoot` are the only fields that change.
+export const PlanConfirm = React.memo(PlanConfirmInner);

src/cli/ui/PlanRefineInput.tsx

@@ -0,0 +1,91 @@
+/**
+ * Inline text input shown after the user picks Approve or Refine in
+ * PlanConfirm. Collects free-form feedback before the loop resumes.
+ *
+ * Why both paths: the plan may contain open questions or risks the
+ * model asked the user to weigh in on. If the user just picks Approve
+ * with no chance to answer, the model implements against its own
+ * guesses. This input lets the user answer questions, pass last-minute
+ * constraints, or (on Refine) request concrete changes. Empty input is
+ * fine for Approve (skip straight to implement) and triggers a
+ * "ask the user clarifying questions" path for Refine.
+ *
+ * Kept minimal: single-line prompt, Enter to submit, Esc to return to
+ * the picker without resuming.
+ */
+
+import { Box, Text, useInput } from "ink";
+import React, { useState } from "react";
+
+export interface PlanRefineInputProps {
+  /**
+   * Which path the user is on. Approve = "implement with these last
+   * instructions"; refine = "revise the plan with this feedback".
+   * Drives the header + hint text so users know what kind of message
+   * they're writing.
+   */
+  mode: "approve" | "refine";
+  /** Called with trimmed feedback. Empty string is allowed. */
+  onSubmit: (feedback: string) => void;
+  /** Called when the user presses Esc to return to the picker. */
+  onCancel: () => void;
+}
+
+export function PlanRefineInput({ mode, onSubmit, onCancel }: PlanRefineInputProps) {
+  const [value, setValue] = useState("");
+
+  useInput((input, key) => {
+    if (key.escape) {
+      onCancel();
+      return;
+    }
+    if (key.return) {
+      onSubmit(value.trim());
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setValue((v) => v.slice(0, -1));
+      return;
+    }
+    // Filter out non-printable chars; accept ordinary text + CJK.
+    if (input && !key.ctrl && !key.meta) {
+      setValue((v) => v + input);
+    }
+  });
+
+  const title =
+    mode === "approve"
+      ? "▸ approving — any last instructions or answers to open questions?"
+      : "▸ refining — what should the model change?";
+  const hint =
+    mode === "approve"
+      ? "Answer questions the plan raised, add constraints, or just press Enter to approve as-is."
+      : "Describe what's wrong or missing, or answer questions the plan raised.";
+  const blankHint =
+    mode === "approve"
+      ? " (Enter with blank = approve without extra instructions.)"
+      : " (Enter with blank = ask the model to list concrete questions.)";
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1} marginY={1}>
+      <Box>
+        <Text bold color="yellow">
+          {title}
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>
+          {hint} Enter to send · Esc to return to the picker.
+          {value === "" ? blankHint : ""}
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text>
+          <Text color="yellow">› </Text>
+          <Text>{value || " "}</Text>
+          <Text color="yellow">▍</Text>
+        </Text>
+      </Box>
+    </Box>
+  );
+}

src/cli/ui/PromptInput.tsx

@@ -1,6 +1,6 @@
 import { Box, Text, useInput } from "ink";
-import React from "react";
-import { type MultilineKey, processMultilineKey } from "./multiline-keys.js";
+import React, { useRef, useState } from "react";
+import { type MultilineKey, lineAndColumn, processMultilineKey } from "./multiline-keys.js";
 import { useTick } from "./ticker.js";
 
 export interface PromptInputProps {
@@ -12,19 +12,16 @@ export interface PromptInputProps {
 }
 
 /**
- * Input box with multi-line composition support. Behaves like the
- * old single-line prompt by default, but:
- *   - Ctrl+J inserts a newline (universal across terminals).
- *   - Shift+Enter inserts a newline (only on terminals that report
- *     the modifier via CSI-u — many don't).
- *   - `\<Enter>` at end of line acts as bash-style continuation —
- *     always works, even on terminals without modifier reporting.
- *   - Pasted multi-line text lands as-is instead of submitting on
- *     the first '\r'.
+ * Input box with real cursor support. ←/→ move one column, ↑/↓ move
+ * across lines in multi-line buffers, Ctrl+A / Ctrl+E jump to
+ * start/end of the current line. Backspace deletes before cursor,
+ * Delete deletes under cursor. Multi-line composition via Ctrl+J,
+ * Shift+Enter, or bash-style `\<Enter>`.
  *
- * No mid-string insertion cursor — edits happen at the end, like
- * a readline prompt in raw mode. Simple, predictable, enough for
- * 95% of prompts and any code paste.
+ * Cursor state lives locally. When the parent replaces `value` out
+ * of band (history recall, slash completion, setup wizard) the
+ * cursor jumps to end; the `lastLocalValueRef` guards distinguishes
+ * that case from our own edits.
  */
 export function PromptInput({
   value,
@@ -33,15 +30,29 @@ export function PromptInput({
   disabled,
   placeholder,
 }: PromptInputProps) {
-  // Blink from the shared ticker (TICK_MS ≈ 120ms) scaled by 4 so the
-  // visible on/off toggles land around 500ms — standard cursor blink.
-  // When disabled the cursor is hidden entirely.
+  const [cursor, setCursor] = useState(value.length);
+  // Tracks the last `value` we ourselves produced via onChange. If the
+  // incoming `value` prop diverges from this, the parent (or some other
+  // source) replaced the buffer — we reset the cursor to end.
+  const lastLocalValueRef = useRef(value);
+  if (value !== lastLocalValueRef.current) {
+    lastLocalValueRef.current = value;
+    if (cursor !== value.length) {
+      // Conditional setState during render is the "derived state" pattern;
+      // React schedules the re-render and the else branch of the `if`
+      // prevents infinite loops.
+      setCursor(value.length);
+    }
+  }
+
+  // Shared ticker drives the cursor blink. Dividing the tick by 4 lands
+  // the visible on/off cycle around 480ms — standard cursor cadence.
   const tick = useTick();
   const showCursor = disabled ? false : Math.floor(tick / 4) % 2 === 0;
 
   useInput(
     (input, key) => {
-      const keyEvent: MultilineKey = {
+      const ke: MultilineKey = {
         input,
         return: key.return,
         shift: key.shift,
@@ -58,30 +69,33 @@ export function PromptInput({
         pageUp: key.pageUp,
         pageDown: key.pageDown,
       };
-      const action = processMultilineKey(value, keyEvent);
-      if (action.next !== null) onChange(action.next);
+      const action = processMultilineKey(value, cursor, ke);
+      if (action.next !== null) {
+        lastLocalValueRef.current = action.next;
+        onChange(action.next);
+      }
+      if (action.cursor !== null) {
+        setCursor(action.cursor);
+      }
       if (action.submit) onSubmit(action.submitValue ?? value);
     },
     { isActive: !disabled },
   );
 
   const effectivePlaceholder = disabled
-    ? (placeholder ?? "…waiting for response…")
-    : (placeholder ?? "type a message, or /command · Ctrl+J for newline");
+    ? (placeholder ?? "…waiting for response…  ·  [Esc] to stop")
+    : (placeholder ?? "type a message, or /command  ·  [Shift+Enter] / [Ctrl+J] newline");
 
   const lines = value.length > 0 ? value.split("\n") : [""];
   const borderColor = disabled ? "gray" : "cyan";
+  const { line: cursorLine, col: cursorCol } = lineAndColumn(value, cursor);
 
   return (
     <Box borderStyle="round" borderColor={borderColor} paddingX={1} flexDirection="column">
       {lines.map((line, i) => {
-        const isLast = i === lines.length - 1;
         const isFirst = i === 0;
         const showPlaceholder = isFirst && value.length === 0;
-        // Line content never survives a re-keying here: the value buffer
-        // fully re-renders on every keystroke, so the array index IS the
-        // stable identity. Biome's rule targets list reordering, which
-        // doesn't apply to an append-only splits-by-newline view.
+        const isCursorLine = i === cursorLine;
         return (
           // biome-ignore lint/suspicious/noArrayIndexKey: stable by construction — lines are derived from `value.split("\n")` and never reordered
           <Box key={i}>
@@ -92,21 +106,59 @@ export function PromptInput({
             ) : (
               <Text dimColor>{"     "}</Text>
             )}
-            {/* When showing the placeholder, the cursor is at position 0 —
-                put it BEFORE the dimmed hint text so it visually matches
-                "you're about to type here," not "you typed the placeholder."
-                When showing real content, the cursor follows the last char
-                of the last line (append-only edit model). */}
-            {showPlaceholder && isLast && !disabled ? (
-              <Text color={borderColor}>{showCursor ? "▌" : " "}</Text>
-            ) : null}
-            {showPlaceholder ? <Text dimColor>{effectivePlaceholder}</Text> : <Text>{line}</Text>}
-            {!showPlaceholder && isLast && !disabled ? (
-              <Text color={borderColor}>{showCursor ? "▌" : " "}</Text>
-            ) : null}
+            {showPlaceholder ? (
+              <>
+                {isCursorLine && !disabled ? (
+                  <Text color={borderColor}>{showCursor ? "▌" : " "}</Text>
+                ) : null}
+                <Text dimColor>{effectivePlaceholder}</Text>
+              </>
+            ) : isCursorLine && !disabled ? (
+              <LineWithCursor
+                line={line}
+                col={cursorCol}
+                showCursor={showCursor}
+                borderColor={borderColor}
+              />
+            ) : (
+              <Text>{line}</Text>
+            )}
           </Box>
         );
       })}
     </Box>
   );
 }
+
+function LineWithCursor({
+  line,
+  col,
+  showCursor,
+  borderColor,
+}: {
+  line: string;
+  col: number;
+  showCursor: boolean;
+  borderColor: "cyan" | "gray";
+}) {
+  const before = line.slice(0, col);
+  const atCursor = line.slice(col, col + 1);
+  const after = line.slice(col + 1);
+  if (atCursor.length === 0) {
+    // Cursor sits past the last char of this line (end-of-line). Render
+    // a trailing block so the user sees where they're typing next.
+    return (
+      <>
+        <Text>{before}</Text>
+        <Text color={borderColor}>{showCursor ? "▌" : " "}</Text>
+      </>
+    );
+  }
+  return (
+    <>
+      <Text>{before}</Text>
+      <Text inverse={showCursor}>{atCursor}</Text>
+      <Text>{after}</Text>
+    </>
+  );
+}

src/cli/ui/Select.tsx

@@ -28,6 +28,13 @@ export interface SingleSelectProps<V extends string> {
   initialValue?: V;
   onSubmit: (value: V) => void;
   onCancel?: () => void;
+  /**
+   * Optional footer rendered dim beneath the list, e.g.
+   * `"↑/↓ navigate · Enter select · Esc cancel"`. Makes keyboard
+   * affordances discoverable — otherwise new users hit `y`/`n` and
+   * wonder why nothing happens.
+   */
+  footer?: string;
 }
 
 export function SingleSelect<V extends string>({
@@ -35,6 +42,7 @@ export function SingleSelect<V extends string>({
   initialValue,
   onSubmit,
   onCancel,
+  footer,
 }: SingleSelectProps<V>) {
   const initialIndex = Math.max(
     0,
@@ -65,6 +73,11 @@ export function SingleSelect<V extends string>({
           marker={i === index ? "▸" : " "}
         />
       ))}
+      {footer ? (
+        <Box marginTop={1}>
+          <Text dimColor>{footer}</Text>
+        </Box>
+      ) : null}
     </Box>
   );
 }

src/cli/ui/SessionPicker.tsx

@@ -0,0 +1,72 @@
+import { Box, Text } from "ink";
+import React from "react";
+import { SingleSelect } from "./Select.js";
+
+export type SessionChoice = "resume" | "new" | "delete";
+
+export interface SessionPickerProps {
+  sessionName: string;
+  messageCount: number;
+  /** mtime of the session file; used to render "last active Nh ago". */
+  lastActive: Date;
+  onChoose: (choice: SessionChoice) => void;
+}
+
+export function SessionPicker({
+  sessionName,
+  messageCount,
+  lastActive,
+  onChoose,
+}: SessionPickerProps) {
+  return (
+    <Box flexDirection="column" marginY={1}>
+      <Box marginBottom={1}>
+        <Text bold color="cyan">
+          {`Session "${sessionName}" has ${messageCount} prior message${messageCount === 1 ? "" : "s"}`}
+        </Text>
+        <Text dimColor>{` · last active ${relativeTime(lastActive)}`}</Text>
+      </Box>
+      <SingleSelect
+        initialValue="new"
+        items={[
+          {
+            value: "new",
+            label: "Start new conversation",
+            hint: "Previous messages kept on disk; your turn starts fresh.",
+          },
+          {
+            value: "resume",
+            label: "Resume",
+            hint: `Continue where you left off (${messageCount} messages in context).`,
+          },
+          {
+            value: "delete",
+            label: "Delete and start new",
+            hint: "Wipes the session file irreversibly. Other sessions untouched.",
+          },
+        ]}
+        onSubmit={(v) => onChoose(v as SessionChoice)}
+      />
+      <Box marginTop={1}>
+        <Text dimColor>↑↓ to move · Enter to pick</Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * "Nh ago" / "Nm ago" / "yesterday" style relative time. Deliberately
+ * coarse — the picker just needs a sense of "how stale is this session".
+ */
+function relativeTime(date: Date): string {
+  const ms = Date.now() - date.getTime();
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "yesterday";
+  if (days < 7) return `${days}d ago`;
+  return date.toISOString().slice(0, 10);
+}

src/cli/ui/ShellConfirm.tsx

@@ -0,0 +1,112 @@
+import { Box, Text } from "ink";
+import React from "react";
+import { SingleSelect } from "./Select.js";
+
+export type ShellConfirmChoice = "run_once" | "always_allow" | "deny";
+
+export interface ShellConfirmProps {
+  command: string;
+  /**
+   * The prefix that would be persisted if the user picks
+   * "always allow". Typically the first 1-2 tokens of `command`.
+   */
+  allowPrefix: string;
+  onChoose: (choice: ShellConfirmChoice) => void;
+}
+
+/**
+ * Modal-style approval for a shell command the model wants to run.
+ * Three choices:
+ *   1. Run once — execute this invocation, prefix NOT remembered.
+ *   2. Always allow — persist the prefix to `~/.reasonix/config.json`
+ *      under this project so every future invocation with that prefix
+ *      auto-runs.
+ *   3. Deny — tell the model the user refused.
+ * Arrow keys + Enter. No y/n hotkey — too easy to trigger by accident
+ * when the user was mid-typing a response.
+ */
+export function ShellConfirm({ command, allowPrefix, onChoose }: ShellConfirmProps) {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="yellow" paddingX={1} marginY={1}>
+      <Box>
+        <Text bold color="yellow">
+          ▸ model wants to run a shell command
+        </Text>
+      </Box>
+      <Box>
+        <Text color="yellow" dimColor>
+          {"──────────────────────────────────────────"}
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text>
+          <Text dimColor>{"$ "}</Text>
+          <Text color="cyan">{command}</Text>
+        </Text>
+      </Box>
+      <Box marginTop={1}>
+        <SingleSelect
+          initialValue="run_once"
+          items={[
+            {
+              value: "run_once",
+              label: "Run once",
+              hint: "Execute this command, don't remember it.",
+            },
+            {
+              value: "always_allow",
+              label: `Always allow "${allowPrefix}" in this project`,
+              hint: "Save the prefix to ~/.reasonix/config.json; future matches auto-run.",
+            },
+            {
+              value: "deny",
+              label: "Deny",
+              hint: "Tell the model the user refused; it will continue without this command.",
+            },
+          ]}
+          onSubmit={(v) => onChoose(v as ShellConfirmChoice)}
+          onCancel={() => onChoose("deny")}
+          footer="[↑↓] navigate  ·  [Enter] select  ·  [Esc] deny"
+        />
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * Pick the "always allow" prefix from a full command. Heuristic:
+ *   - one-token commands ("ls", "pytest") → the token itself
+ *   - multi-token → first two tokens for well-known wrappers
+ *     (`npm install`, `git commit`, `cargo add`, `docker run` …)
+ *     otherwise just the first token (covers `node <script>` where the
+ *     second token is usually a file path specific to this invocation).
+ * Exported so tests can pin the heuristic.
+ */
+export function derivePrefix(command: string): string {
+  const tokens = command.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return "";
+  if (tokens.length === 1) return tokens[0]!;
+  const first = tokens[0]!;
+  const TWO_TOKEN_WRAPPERS = new Set([
+    "npm",
+    "npx",
+    "pnpm",
+    "yarn",
+    "bun",
+    "git",
+    "cargo",
+    "go",
+    "docker",
+    "kubectl",
+    "python",
+    "python3",
+    "deno",
+    "pip",
+    "pip3",
+    "make",
+    "rake",
+    "bundle",
+    "gem",
+  ]);
+  return TWO_TOKEN_WRAPPERS.has(first) ? `${first} ${tokens[1]}` : first;
+}

src/cli/ui/SlashArgPicker.tsx

@@ -0,0 +1,108 @@
+import { Box, Text } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig.jsx = "react" needs React in value scope for JSX compilation
+import React from "react";
+import type { SlashCommandSpec } from "./slash.js";
+
+export interface SlashArgPickerProps {
+  /**
+   * When set, render a picker with these matches (filter already
+   * applied upstream). Null → not in picker mode; check `hintSpec`
+   * for a usage hint instead.
+   */
+  matches: readonly string[] | null;
+  /** Highlighted row within `matches`. */
+  selectedIndex: number;
+  /**
+   * Spec of the command the user is typing args for. Used to render
+   * the header label ("/edit <file>") even when matches is empty or
+   * the caller wants a hint instead of a picker.
+   */
+  spec: SlashCommandSpec;
+  /** What kind of arg guidance to render. */
+  kind: "picker" | "hint";
+  /** The user's partial input — shown in the "no matches" hint. */
+  partial: string;
+}
+
+/**
+ * Argument-level picker for a slash command. Mirrors the visual
+ * layout of SlashSuggestions / AtMentionSuggestions so the UI stays
+ * consistent across all three picker surfaces.
+ */
+export function SlashArgPicker({
+  matches,
+  selectedIndex,
+  spec,
+  kind,
+  partial,
+}: SlashArgPickerProps): React.ReactElement | null {
+  // Hint mode: a single dim row explaining the argsHint + summary.
+  if (kind === "hint") {
+    return (
+      <Box paddingX={1}>
+        <Text dimColor>
+          {"  "}
+          <Text bold>/{spec.cmd}</Text>
+          {spec.argsHint ? ` ${spec.argsHint}` : ""} — {spec.summary}
+        </Text>
+      </Box>
+    );
+  }
+
+  if (matches === null) return null;
+  if (matches.length === 0) {
+    return (
+      <Box flexDirection="column" paddingX={1}>
+        <Text dimColor>
+          {"  "}
+          <Text bold>/{spec.cmd}</Text>
+          {spec.argsHint ? ` ${spec.argsHint}` : ""} — {spec.summary}
+        </Text>
+        <Text color="yellow"> no match for "{partial}" — keep typing, or Backspace to edit</Text>
+      </Box>
+    );
+  }
+
+  const MAX = 8;
+  const total = matches.length;
+  const windowStart =
+    total <= MAX ? 0 : Math.max(0, Math.min(selectedIndex - Math.floor(MAX / 2), total - MAX));
+  const shown = matches.slice(windowStart, windowStart + MAX);
+  const hiddenAbove = windowStart;
+  const hiddenBelow = total - windowStart - shown.length;
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text dimColor>
+        {"  "}
+        <Text bold>/{spec.cmd}</Text>
+        {spec.argsHint ? ` ${spec.argsHint}` : ""} — {spec.summary}
+      </Text>
+      {hiddenAbove > 0 ? <Text dimColor> ↑ {hiddenAbove} more above</Text> : null}
+      {shown.map((value, i) => (
+        <ArgRow key={value} value={value} isSelected={windowStart + i === selectedIndex} />
+      ))}
+      {hiddenBelow > 0 ? <Text dimColor> ↓ {hiddenBelow} more below</Text> : null}
+      <Text dimColor> [↑↓] navigate · [Tab]/[Enter] pick</Text>
+    </Box>
+  );
+}
+
+function ArgRow({ value, isSelected }: { value: string; isSelected: boolean }) {
+  const marker = isSelected ? "▸" : " ";
+  if (isSelected) {
+    return (
+      <Box>
+        <Text bold color="cyan">
+          {marker} {value}
+        </Text>
+      </Box>
+    );
+  }
+  return (
+    <Box>
+      <Text dimColor>
+        {marker} {value}
+      </Text>
+    </Box>
+  );
+}

src/cli/ui/SlashSuggestions.tsx

@@ -51,7 +51,7 @@ export function SlashSuggestions({
         <SuggestionRow key={spec.cmd} spec={spec} isSelected={windowStart + i === selectedIndex} />
       ))}
       {hiddenBelow > 0 ? <Text dimColor> ↓ {hiddenBelow} more below</Text> : null}
-      <Text dimColor> ↑/↓ navigate · Tab or Enter to pick</Text>
+      <Text dimColor> [↑↓] navigate · [Tab]/[Enter] pick</Text>
     </Box>
   );
 }

src/cli/ui/StatsPanel.tsx

@@ -1,7 +1,54 @@
-import { Box, Text } from "ink";
+import { Box, Text, useStdout } from "ink";
 import React from "react";
 import { DEEPSEEK_CONTEXT_TOKENS, DEFAULT_CONTEXT_TOKENS } from "../../telemetry.js";
 import type { SessionSummary } from "../../telemetry.js";
+import { VERSION } from "../../version.js";
+import { useTick } from "./ticker.js";
+
+/**
+ * Cyan → blue → purple truecolor gradient for the REASONIX wordmark.
+ * Each char gets its own hex color — terminals that support 24-bit
+ * color (nearly all since 2016) render this as a smooth fade. Older
+ * 256-color terminals snap to nearest; 8-color fall all the way back
+ * to plain cyan via Ink's color pipeline, so the worst case is still
+ * legible.
+ */
+const WORDMARK_STYLES: ReadonlyArray<{ ch: string; color: string; isLogo: boolean }> = [
+  { ch: "◈", color: "#5eead4", isLogo: true }, // teal — brand mark
+  { ch: " ", color: "#5eead4", isLogo: false },
+  { ch: "R", color: "#67e8f9", isLogo: false }, // cyan
+  { ch: "E", color: "#7dd3fc", isLogo: false }, // sky
+  { ch: "A", color: "#93c5fd", isLogo: false }, // blue
+  { ch: "S", color: "#a5b4fc", isLogo: false }, // indigo
+  { ch: "O", color: "#c4b5fd", isLogo: false }, // violet
+  { ch: "N", color: "#d8b4fe", isLogo: false }, // purple
+  { ch: "I", color: "#f0abfc", isLogo: false }, // fuchsia
+  { ch: "X", color: "#f0abfc", isLogo: false }, // fuchsia
+];
+
+/**
+ * Gradient-filled, animated app wordmark. The `◈` brand mark breathes
+ * (bold on/off) once every ~1.6s when idle, ~600ms when the model is
+ * working, so a glance at the top of the screen tells you immediately
+ * whether the app is doing something. Letters' keys use the char+color
+ * pair (not an index) so React state attaches to the glyph itself;
+ * fine because WORDMARK_STYLES never reorders.
+ */
+function Wordmark({ busy }: { busy: boolean }) {
+  const tick = useTick();
+  // Slow pulse = 12 ticks (~1.4s). Busy pulse = 5 ticks (~600ms).
+  const period = busy ? 5 : 12;
+  const bright = Math.floor(tick / period) % 2 === 0;
+  return (
+    <Text>
+      {WORDMARK_STYLES.map((c) => (
+        <Text key={`${c.ch}-${c.color}`} color={c.color} bold={c.isLogo ? bright : true}>
+          {c.ch}
+        </Text>
+      ))}
+    </Text>
+  );
+}
 
 export interface StatsPanelProps {
   summary: SessionSummary;
@@ -9,6 +56,13 @@ export interface StatsPanelProps {
   prefixHash: string;
   harvestOn?: boolean;
   branchBudget?: number;
+  /**
+   * True when `reasonix code` is currently running in read-only Plan
+   * Mode. Surfaced as a red "PLAN" tag in the panel header so the user
+   * can tell at a glance that edits are gated behind submit_plan +
+   * approval.
+   */
+  planMode?: boolean;
   /**
    * Account balance fetched once at launch (and optionally refreshed
    * per-turn by the TUI). `null` or absent hides the balance cell
@@ -18,96 +72,361 @@ export interface StatsPanelProps {
    * with USD both see "getting low."
    */
   balance?: { currency: string; total: number } | null;
+  /**
+   * Published npm version newer than VERSION. Rendered as a yellow
+   * "· update: X" nudge in the panel header. `null` / `undefined`
+   * hides the nudge (offline launch, already up to date, or check
+   * still in flight).
+   */
+  updateAvailable?: string | null;
+  /**
+   * True when the loop is currently mid-turn — drives the wordmark's
+   * "busy breathing" animation. Visual signal that the app is thinking,
+   * visible at a glance from anywhere on screen.
+   */
+  busy?: boolean;
 }
 
+/**
+ * Terminal width under which we switch from one-line metrics to a
+ * stacked layout. Below 120 cols the wide version wraps mid-number
+ * and the parens ("in $X · out $Y") get split across lines — which
+ * looks broken. Stacking costs one row but stays readable on every
+ * SSH / split-pane case we've hit.
+ */
+const NARROW_BREAKPOINT = 120;
+
+/**
+ * Cache-hit ratio is always zero on turn 1 (there's literally no cache
+ * to hit yet). Showing that as red "0.0%" is a false alarm — new users
+ * read it as "something is broken." We suppress the gradient until a
+ * few turns have landed; by turn 4 the cache has had time to warm up.
+ */
+const COLD_START_TURNS = 3;
+
 export function StatsPanel({
   summary,
   model,
   prefixHash,
   harvestOn,
   branchBudget,
+  planMode,
   balance,
+  updateAvailable,
+  busy,
 }: StatsPanelProps) {
-  const hitPct = (summary.cacheHitRatio * 100).toFixed(1);
-  const hitColor =
-    summary.cacheHitRatio >= 0.7 ? "green" : summary.cacheHitRatio >= 0.4 ? "yellow" : "red";
   const branchOn = (branchBudget ?? 1) > 1;
-
   const ctxMax = DEEPSEEK_CONTEXT_TOKENS[model] ?? DEFAULT_CONTEXT_TOKENS;
   const ctxRatio = summary.lastPromptTokens / ctxMax;
-  const ctxColor = ctxRatio >= 0.8 ? "red" : ctxRatio >= 0.5 ? "yellow" : undefined;
+  const { stdout } = useStdout();
+  const columns = stdout?.columns ?? 80;
+  const narrow = columns < NARROW_BREAKPOINT;
+
+  // Cold-start: first few turns render cache+cost muted so a 0.0% hit
+  // rate on turn 1 doesn't look like an error. Once the cache has
+  // actually had a chance to build, we flip to the live gradient.
+  const coldStart = summary.turns <= COLD_START_TURNS;
 
   return (
     <Box borderStyle="round" borderColor="cyan" flexDirection="column" paddingX={1}>
-      <Box justifyContent="space-between">
-        <Text>
-          <Text color="cyan" bold>
-            Reasonix
-          </Text>
-          <Text dimColor> · model </Text>
-          <Text color="yellow">{model}</Text>
-          <Text dimColor> · prefix </Text>
-          <Text dimColor>{prefixHash}</Text>
-          {harvestOn ? <Text color="magenta"> · harvest</Text> : null}
-          {branchOn ? <Text color="blue"> · branch{branchBudget}</Text> : null}
-        </Text>
-        <Text dimColor>turns {summary.turns} · type /help</Text>
-      </Box>
-      <Box marginTop={1} gap={3}>
-        <Text>
-          <Text dimColor>cache hit </Text>
-          <Text color={hitColor} bold>
-            {hitPct}%
-          </Text>
-        </Text>
-        <Text>
-          <Text dimColor>cost </Text>
-          <Text color="green" bold>
-            ${summary.totalCostUsd.toFixed(6)}
-          </Text>
-          <Text dimColor>
-            {" (in "}${summary.totalInputCostUsd.toFixed(6)}
-            {" · out "}${summary.totalOutputCostUsd.toFixed(6)}
-            {")"}
-          </Text>
-        </Text>
-        {summary.lastPromptTokens > 0 ? (
-          <Text>
-            <Text dimColor>ctx </Text>
-            <Text color={ctxColor} bold={ctxColor !== undefined}>
-              {formatTokens(summary.lastPromptTokens)}/{formatTokens(ctxMax)}
-            </Text>
-            <Text dimColor> ({(ctxRatio * 100).toFixed(0)}%)</Text>
-            {ctxRatio >= 0.8 ? (
-              <Text color="red" bold>
-                {" "}
-                · /compact
-              </Text>
-            ) : null}
-          </Text>
-        ) : null}
-        {balance ? (
-          <Text>
-            <Text dimColor>balance </Text>
-            <Text color={balance.total < 1 ? "red" : balance.total < 5 ? "yellow" : "green"} bold>
-              {balance.currency === "USD" ? "$" : ""}
-              {balance.total.toFixed(2)}
-              {balance.currency !== "USD" ? ` ${balance.currency}` : ""}
-            </Text>
+      <Header
+        model={model}
+        prefixHash={prefixHash}
+        harvestOn={harvestOn}
+        branchOn={branchOn}
+        branchBudget={branchBudget ?? 1}
+        planMode={planMode}
+        turns={summary.turns}
+        updateAvailable={updateAvailable}
+        narrow={narrow}
+        busy={busy ?? false}
+      />
+      {narrow ? (
+        <StackedMetrics
+          summary={summary}
+          ctxRatio={ctxRatio}
+          ctxMax={ctxMax}
+          balance={balance}
+          coldStart={coldStart}
+        />
+      ) : (
+        <InlineMetrics
+          summary={summary}
+          ctxRatio={ctxRatio}
+          ctxMax={ctxMax}
+          balance={balance}
+          coldStart={coldStart}
+        />
+      )}
+    </Box>
+  );
+}
+
+function Header({
+  model,
+  prefixHash,
+  harvestOn,
+  branchOn,
+  branchBudget,
+  planMode,
+  turns,
+  updateAvailable,
+  narrow,
+  busy,
+}: {
+  model: string;
+  prefixHash: string;
+  harvestOn?: boolean;
+  branchOn: boolean;
+  branchBudget: number;
+  planMode?: boolean;
+  turns: number;
+  updateAvailable?: string | null;
+  narrow: boolean;
+  busy: boolean;
+}) {
+  return (
+    <Box justifyContent="space-between">
+      <Box>
+        <Wordmark busy={busy} />
+        <Text dimColor>{` v${VERSION}`}</Text>
+        <Text dimColor> · </Text>
+        <Text color="yellow">{model}</Text>
+        {narrow ? null : (
+          <>
+            <Text dimColor> · </Text>
+            <Text dimColor>{prefixHash}</Text>
+          </>
+        )}
+        {harvestOn ? <Text color="magenta"> · harvest</Text> : null}
+        {branchOn ? <Text color="blue"> · branch{branchBudget}</Text> : null}
+        {planMode ? (
+          <Text color="red" bold>
+            {" · PLAN"}
           </Text>
         ) : null}
       </Box>
+      <Text>
+        {updateAvailable ? (
+          <Text color="yellow" bold>{`update: ${updateAvailable} · `}</Text>
+        ) : null}
+        <Text dimColor>{narrow ? `turn ${turns}` : `turn ${turns} · /help`}</Text>
+      </Text>
     </Box>
   );
 }
 
 /**
- * Compact integer formatter: 1234 → "1.2k", 131072 → "131k". Keeps the
- * panel narrow enough to fit on 80-col terminals even when the context
- * is near full.
+ * Wide-terminal layout (≥120 cols): single metrics row. Matches the
+ * original panel, just with calmer spacing and the cold-start
+ * treatment folded in.
+ */
+function InlineMetrics({
+  summary,
+  ctxRatio,
+  ctxMax,
+  balance,
+  coldStart,
+}: {
+  summary: SessionSummary;
+  ctxRatio: number;
+  ctxMax: number;
+  balance?: { currency: string; total: number } | null;
+  coldStart: boolean;
+}) {
+  return (
+    <Box marginTop={1} gap={3}>
+      <ContextCell ratio={ctxRatio} promptTokens={summary.lastPromptTokens} ctxMax={ctxMax} />
+      <CacheCell hitRatio={summary.cacheHitRatio} coldStart={coldStart} turns={summary.turns} />
+      <CostCell summary={summary} coldStart={coldStart} />
+      {balance ? <BalanceCell balance={balance} /> : null}
+    </Box>
+  );
+}
+
+/**
+ * Narrow-terminal layout (<120 cols): one metric per line, in priority
+ * order (ctx → balance → cache → cost). Order matters because users
+ * scanning a cramped terminal want "am I about to hit a wall?" answered
+ * first; dollars spent comes later.
+ */
+function StackedMetrics({
+  summary,
+  ctxRatio,
+  ctxMax,
+  balance,
+  coldStart,
+}: {
+  summary: SessionSummary;
+  ctxRatio: number;
+  ctxMax: number;
+  balance?: { currency: string; total: number } | null;
+  coldStart: boolean;
+}) {
+  return (
+    <Box marginTop={1} flexDirection="column">
+      <ContextCell
+        ratio={ctxRatio}
+        promptTokens={summary.lastPromptTokens}
+        ctxMax={ctxMax}
+        showBar
+      />
+      {balance ? <BalanceCell balance={balance} /> : null}
+      <CacheCell hitRatio={summary.cacheHitRatio} coldStart={coldStart} turns={summary.turns} />
+      <CostCell summary={summary} coldStart={coldStart} />
+    </Box>
+  );
+}
+
+function ContextCell({
+  ratio,
+  promptTokens,
+  ctxMax,
+  showBar,
+}: {
+  ratio: number;
+  promptTokens: number;
+  ctxMax: number;
+  showBar?: boolean;
+}) {
+  if (promptTokens === 0) {
+    return (
+      <Text>
+        <Text dimColor>ctx </Text>
+        <Text dimColor>— (no turns yet)</Text>
+      </Text>
+    );
+  }
+  const color = ratio >= 0.8 ? "red" : ratio >= 0.6 ? "yellow" : "green";
+  const pct = Math.round(ratio * 100);
+  return (
+    <Text>
+      <Text dimColor>ctx </Text>
+      {showBar ? <Bar ratio={ratio} color={color} /> : null}
+      {showBar ? <Text> </Text> : null}
+      <Text color={color} bold>
+        {formatTokens(promptTokens)}/{formatTokens(ctxMax)}
+      </Text>
+      <Text dimColor> ({pct}%)</Text>
+      {ratio >= 0.8 ? (
+        <Text color="red" bold>
+          {"  ·  /compact"}
+        </Text>
+      ) : null}
+    </Text>
+  );
+}
+
+function CacheCell({
+  hitRatio,
+  coldStart,
+  turns,
+}: {
+  hitRatio: number;
+  coldStart: boolean;
+  turns: number;
+}) {
+  const pct = (hitRatio * 100).toFixed(1);
+  if (turns === 0) {
+    return (
+      <Text>
+        <Text dimColor>cache </Text>
+        <Text dimColor>—</Text>
+      </Text>
+    );
+  }
+  if (coldStart) {
+    return (
+      <Text>
+        <Text dimColor>cache </Text>
+        <Text dimColor>{pct}% </Text>
+        <Text dimColor italic>
+          (cold start)
+        </Text>
+      </Text>
+    );
+  }
+  const color = hitRatio >= 0.7 ? "green" : hitRatio >= 0.4 ? "yellow" : "red";
+  return (
+    <Text>
+      <Text dimColor>cache </Text>
+      <Text color={color} bold>
+        {pct}%
+      </Text>
+    </Text>
+  );
+}
+
+function CostCell({
+  summary,
+  coldStart,
+}: {
+  summary: SessionSummary;
+  coldStart: boolean;
+}) {
+  if (summary.turns === 0) {
+    return (
+      <Text>
+        <Text dimColor>cost </Text>
+        <Text dimColor>—</Text>
+      </Text>
+    );
+  }
+  // The first turn is unavoidably a cache-miss (nothing to hit),
+  // so the dollar figure is front-loaded. Muting it during the
+  // cold-start window keeps the "expensive first turn" from
+  // reading as "something is wrong."
+  const primaryColor = coldStart ? undefined : "green";
+  return (
+    <Text>
+      <Text dimColor>cost </Text>
+      <Text color={primaryColor} bold={!coldStart} dimColor={coldStart}>
+        ${summary.totalCostUsd.toFixed(6)}
+      </Text>
+      <Text dimColor>
+        {" (in "}${summary.totalInputCostUsd.toFixed(6)}
+        {" · out "}${summary.totalOutputCostUsd.toFixed(6)}
+        {")"}
+      </Text>
+    </Text>
+  );
+}
+
+function BalanceCell({ balance }: { balance: { currency: string; total: number } }) {
+  const color = balance.total < 1 ? "red" : balance.total < 5 ? "yellow" : "green";
+  return (
+    <Text>
+      <Text dimColor>balance </Text>
+      <Text color={color} bold>
+        {balance.currency === "USD" ? "$" : ""}
+        {balance.total.toFixed(2)}
+        {balance.currency !== "USD" ? ` ${balance.currency}` : ""}
+      </Text>
+    </Text>
+  );
+}
+
+/**
+ * Unicode progress bar for the narrow layout's context cell. 10 cells
+ * wide — narrow terminals are already cramped, and the bar is just a
+ * visual cue for the percentage next to it, not the primary readout.
+ */
+function Bar({ ratio, color }: { ratio: number; color: "green" | "yellow" | "red" }) {
+  const cells = 10;
+  const filled = Math.max(0, Math.min(cells, Math.round(ratio * cells)));
+  const bar = "█".repeat(filled) + "░".repeat(cells - filled);
+  return <Text color={color}>{bar}</Text>;
+}
+
+/**
+ * Compact token formatter using binary K (÷1024): 1234 → "1.2K",
+ * 131072 → "128K". Matches DeepSeek's marketing label of "128K context
+ * length" — showing "131k" confused users (the actual limit is
+ * 128×1024 = 131,072 tokens, but the doc consistently says "128K").
+ * Uppercase K signals binary-K to anyone who notices.
  */
 function formatTokens(n: number): string {
-  if (n < 1000) return String(n);
-  const k = n / 1000;
-  return k >= 100 ? `${k.toFixed(0)}k` : `${k.toFixed(1)}k`;
+  if (n < 1024) return String(n);
+  const k = n / 1024;
+  return k >= 100 ? `${k.toFixed(0)}K` : `${k.toFixed(1)}K`;
 }

src/cli/ui/bang.ts

@@ -0,0 +1,39 @@
+/**
+ * Bash-mode (`!cmd`) prefix parsing.
+ *
+ * A `!` at the start of the user's input means "run this as a shell
+ * command in the sandbox root, and put both the command and its output
+ * into the conversation so the model sees it next turn." Same idea as
+ * Claude Code's `!` prefix — faster than round-tripping through the
+ * model just to cat a file or check git status.
+ *
+ * Design choice: user-typed `!` commands skip the allowlist. The
+ * allowlist exists to bound what the MODEL can do with run_command;
+ * the user typing `!git push` by hand is explicit consent. If a user
+ * wants stricter gating they can set `REASONIX_BANG_CONFIRM=1` in a
+ * future iteration.
+ */
+
+/**
+ * Return the command portion of a `!`-prefixed input, or `null` if
+ * the text isn't a bang invocation. Trims leading/trailing whitespace
+ * from the command body. `!` alone (or `!` followed by only whitespace)
+ * returns `null` — no command to run.
+ */
+export function detectBangCommand(text: string): string | null {
+  if (!text.startsWith("!")) return null;
+  const body = text.slice(1).trim();
+  if (!body) return null;
+  return body;
+}
+
+/**
+ * Format a bang command + its output into a single user-role message
+ * body that the model will see on the next turn. The `[!cmd]` header
+ * marks the run explicitly so the model can distinguish
+ * user-typed shell output from its own `run_command` tool results
+ * (which are `role: tool`, different message shape entirely).
+ */
+export function formatBangUserMessage(cmd: string, output: string): string {
+  return `[!${cmd}]\n${output}`;
+}

src/cli/ui/markdown.tsx

@@ -14,6 +14,8 @@
  * show the expression verbatim; terminals don't do math fonts anyway.
  */
 
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { Box, Text } from "ink";
 import React from "react";
 
@@ -144,10 +146,135 @@ export function stripMath(s: string): string {
   );
 }
 
-/** Split a single line into styled segments for bold / italic / inline code. */
-const INLINE_RE = /(\*\*([^*\n]+?)\*\*|`([^`\n]+?)`|(?<![*\w])\*([^*\n]+?)\*(?!\w))/g;
+/**
+ * Citation links: `[text](url)` where url either points outside the repo
+ * (rendered as a plain external link) or resolves to a file/line in the
+ * project (rendered as a validated citation — broken citations turn
+ * red so the user can spot model hallucinations at a glance). The point
+ * is: the model is encouraged to ground every codebase claim in a
+ * link, and Reasonix surfaces broken links instead of silently letting
+ * fabrications past.
+ */
+export type CitationStatus = { ok: true } | { ok: false; reason: string };
+export type CitationMap = Map<string, CitationStatus>;
 
-function InlineMd({ text }: { text: string }) {
+interface CitationParts {
+  path: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+export function isExternalUrl(url: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith("mailto:") || url.startsWith("//");
+}
+
+export function parseCitationUrl(url: string): CitationParts | null {
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+  // GitHub-style anchor: foo.ts#L42 or foo.ts#L42-L58
+  let m = trimmed.match(/^(.+?)#L(\d+)(?:-L?(\d+))?$/);
+  if (m) {
+    return {
+      path: m[1] ?? "",
+      startLine: Number(m[2]),
+      endLine: m[3] ? Number(m[3]) : undefined,
+    };
+  }
+  // Colon-style: foo.ts:42 or foo.ts:42-58
+  m = trimmed.match(/^(.+?):(\d+)(?:-(\d+))?$/);
+  if (m) {
+    return {
+      path: m[1] ?? "",
+      startLine: Number(m[2]),
+      endLine: m[3] ? Number(m[3]) : undefined,
+    };
+  }
+  return { path: trimmed };
+}
+
+export function validateCitation(url: string, projectRoot: string): CitationStatus {
+  const parts = parseCitationUrl(url);
+  if (!parts || !parts.path) return { ok: false, reason: "empty path" };
+  // Strip a leading `/` or `\\`. Models habitually write `/foo.ts`
+  // meaning "project-root relative" — Aider / Claude-Code convention —
+  // rather than POSIX root-absolute. A literal absolute path is still
+  // reachable as `C:\foo` on Windows or once the strip drops the slash
+  // and Node's `isAbsolute` correctly rejects what's left. Real unix
+  // absolute references like `/etc/hosts` in a code citation are vanishingly
+  // rare — if anyone needs one we can revisit.
+  const normalized = parts.path.replace(/^[/\\]+/, "");
+  const fullPath = isAbsolute(normalized) ? normalized : join(projectRoot, normalized);
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(fullPath);
+  } catch {
+    return { ok: false, reason: "file not found" };
+  }
+  if (!stat.isFile()) return { ok: false, reason: "not a file" };
+  if (parts.startLine === undefined) return { ok: true };
+  let lineCount: number;
+  try {
+    lineCount = readFileSync(fullPath, "utf8").split("\n").length;
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+  if (parts.startLine < 1 || parts.startLine > lineCount) {
+    return { ok: false, reason: `line ${parts.startLine} > ${lineCount}` };
+  }
+  if (parts.endLine !== undefined) {
+    if (parts.endLine < parts.startLine || parts.endLine > lineCount) {
+      return { ok: false, reason: `range end ${parts.endLine} invalid` };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Pre-scan rendered text for every `[text](url)` link, validate the
+ * citation-shaped ones, and cache the result. Done once per Markdown
+ * mount so InlineMd doesn't re-stat the filesystem on every keystroke
+ * during streaming. External links short-circuit (no fs work).
+ */
+export function collectCitations(text: string, projectRoot: string): CitationMap {
+  const map: CitationMap = new Map();
+  const re = /\[([^\]\n]+)\]\(([^)\n]+)\)/g;
+  for (const m of text.matchAll(re)) {
+    const url = m[2] ?? "";
+    if (!url || isExternalUrl(url)) continue;
+    if (map.has(url)) continue;
+    map.set(url, validateCitation(url, projectRoot));
+  }
+  return map;
+}
+
+/**
+ * Split a single line into styled segments for bold / italic / inline
+ * code / links.
+ *
+ * Link group is FIRST so `[text](url)` with markup-looking URL chars
+ * doesn't get partially eaten by the bold/code branches.
+ *
+ * Triple-backtick (```…```) runs are matched BEFORE the single-backtick
+ * case so a one-line code span like `​``bash echo hi``​` is captured
+ * whole instead of the single-backtick regex greedily eating the
+ * middle and leaving two stray backticks on each side (what 0.4.15
+ * users saw when the model emitted `​``bash …``​` on the same line as
+ * prose). Content may contain single backticks but not newlines —
+ * multi-line fenced code is a block-level concern handled in
+ * `parseBlocks`.
+ */
+const INLINE_RE =
+  /(\[([^\]\n]+)\]\(([^)\n]+)\)|\*\*([^*\n]+?)\*\*|```([^\n]+?)```|`([^`\n]+?)`|(?<![*\w])\*([^*\n]+?)\*(?!\w))/g;
+
+function InlineMd({
+  text,
+  padTo,
+  citations,
+}: {
+  text: string;
+  padTo?: number;
+  citations?: CitationMap;
+}) {
   const parts: React.ReactNode[] = [];
   let last = 0;
   let idx = 0;
@@ -156,33 +283,106 @@ function InlineMd({ text }: { text: string }) {
     if (start > last) {
       parts.push(<Text key={`t${idx++}`}>{text.slice(last, start)}</Text>);
     }
-    if (m[2] !== undefined) {
-      parts.push(
-        <Text key={`b${idx++}`} bold>
-          {m[2]}
-        </Text>,
-      );
-    } else if (m[3] !== undefined) {
-      parts.push(
-        <Text key={`c${idx++}`} color="yellow">
-          {m[3]}
-        </Text>,
-      );
+    // Groups, in the order they appear in INLINE_RE:
+    //   m[2] = link text          m[3] = link url
+    //   m[4] = bold content (inside ** **)
+    //   m[5] = triple-backtick content (strip leading lang tag)
+    //   m[6] = single-backtick inline code
+    //   m[7] = italic content (inside * *)
+    if (m[2] !== undefined && m[3] !== undefined) {
+      const linkText = m[2];
+      const url = m[3];
+      if (isExternalUrl(url)) {
+        parts.push(
+          <Text key={`l${idx++}`} color="blue" underline>
+            {linkText}
+          </Text>,
+        );
+      } else {
+        const status = citations?.get(url);
+        if (status && !status.ok) {
+          parts.push(
+            <Text key={`l${idx++}`} color="red" strikethrough>
+              {`${linkText} ✗`}
+            </Text>,
+          );
+        } else {
+          parts.push(
+            <Text key={`l${idx++}`} color="cyan" underline>
+              {linkText}
+            </Text>,
+          );
+        }
+      }
     } else if (m[4] !== undefined) {
       parts.push(
-        <Text key={`i${idx++}`} italic>
+        <Text key={`b${idx++}`} bold>
           {m[4]}
         </Text>,
       );
+    } else if (m[5] !== undefined) {
+      // One-line fenced span: ```bash echo hi``` → drop the "bash "
+      // language tag so the user doesn't see it rendered in code color.
+      const stripped = m[5].replace(/^(\w+)\s+/, "");
+      parts.push(
+        <Text key={`c${idx++}`} color="yellow">
+          {stripped}
+        </Text>,
+      );
+    } else if (m[6] !== undefined) {
+      parts.push(
+        <Text key={`c${idx++}`} color="yellow">
+          {m[6]}
+        </Text>,
+      );
+    } else if (m[7] !== undefined) {
+      parts.push(
+        <Text key={`i${idx++}`} italic>
+          {m[7]}
+        </Text>,
+      );
     }
     last = start + m[0].length;
   }
   if (last < text.length) {
     parts.push(<Text key={`t${idx++}`}>{text.slice(last)}</Text>);
   }
+  // Trailing pad — used by table cells so column widths line up after
+  // the inline markup is rendered (markup chars like `**` and `` ` ``
+  // are invisible in output, so naive `pad(rawText, width)` over-pads
+  // styled cells and the columns drift out of alignment).
+  if (padTo !== undefined) {
+    const seen = visibleWidth(text);
+    if (seen < padTo) {
+      parts.push(<Text key={`pad${idx++}`}>{" ".repeat(padTo - seen)}</Text>);
+    }
+  }
   return <Text>{parts}</Text>;
 }
 
+/**
+ * Strip inline markdown markers (**, _, single + triple backtick) so the
+ * remaining text reflects what the user actually SEES on screen. Used
+ * to compute correct column widths for table cells where the raw cell
+ * length includes invisible markup chars.
+ */
+export function stripInlineMarkup(s: string): string {
+  return s
+    .replace(/\[([^\]\n]+)\]\(([^)\n]+)\)/g, "$1")
+    .replace(/\*\*([^*\n]+?)\*\*/g, "$1")
+    .replace(/```([^\n]+?)```/g, (_m, c: string) => c.replace(/^(\w+)\s+/, ""))
+    .replace(/`([^`\n]+?)`/g, "$1")
+    .replace(/(?<![*\w])\*([^*\n]+?)\*(?!\w)/g, "$1");
+}
+
+/**
+ * Display width AFTER stripping inline markup. The visible-on-screen
+ * column width — what padding decisions should be based on.
+ */
+export function visibleWidth(s: string): number {
+  return displayWidth(stripInlineMarkup(s));
+}
+
 interface ParagraphBlock {
   kind: "paragraph";
   text: string;
@@ -250,6 +450,11 @@ export function parseBlocks(raw: string): Block[] {
   let codeBuf: string[] = [];
   let listBuf: BulletBlock | null = null;
 
+  // Fence length of the currently-open code block so a block opened
+  // with ````` closes only on `````, matching GFM. Empty when we're
+  // not in code mode.
+  let codeFence = "";
+
   const flushPara = () => {
     if (para.length) {
       out.push({ kind: "paragraph", text: para.join(" ") });
@@ -307,22 +512,51 @@ export function parseBlocks(raw: string): Block[] {
       }
     }
 
-    const fence = line.match(/^```(\w*)/);
-    if (fence) {
-      if (inCode) {
-        out.push({ kind: "code", lang: codeLang, text: codeBuf.join("\n") });
-        codeBuf = [];
-        codeLang = "";
-        inCode = false;
-      } else {
+    // Fenced code block (GFM). The fence is 3+ backticks, may have up
+    // to 3 leading spaces, and carries an optional language tag. A
+    // closing fence must be the SAME backtick run length or longer.
+    //
+    // Two paths:
+    //   a) Fence on its own line → multi-line block, accumulate until
+    //      a matching close fence.
+    //   b) Fence opens AND closes on the same line (e.g.
+    //      `​``bash echo hi``​`) → emit as a one-line code block so
+    //      the inline parser doesn't half-eat the backticks.
+    if (!inCode) {
+      const open = line.match(/^ {0,3}(`{3,})(\w*)\s*(.*)$/);
+      if (open) {
+        const fence = open[1]!;
+        const lang = open[2] ?? "";
+        const rest = open[3] ?? "";
+        const closeOnSame = rest.match(new RegExp(`^(.*?)${fence}\\s*$`));
+        if (closeOnSame) {
+          flushPara();
+          flushList();
+          out.push({ kind: "code", lang, text: (closeOnSame[1] ?? "").trim() });
+          continue;
+        }
         flushPara();
         flushList();
         inCode = true;
-        codeLang = fence[1] ?? "";
+        codeLang = lang;
+        codeFence = fence;
+        // Anything after the opening fence on the SAME line is
+        // still body content (rare but legal).
+        if (rest.length > 0) codeBuf.push(rest);
+        continue;
+      }
+    } else {
+      // In code mode — check for closing fence. Same indent rules as
+      // opening, and the backtick run must be at least as long.
+      const close = line.match(/^ {0,3}(`{3,})\s*$/);
+      if (close && close[1]!.length >= codeFence.length) {
+        out.push({ kind: "code", lang: codeLang, text: codeBuf.join("\n") });
+        codeBuf = [];
+        codeLang = "";
+        codeFence = "";
+        inCode = false;
+        continue;
       }
-      continue;
-    }
-    if (inCode) {
       codeBuf.push(rawLine);
       continue;
     }
@@ -348,22 +582,79 @@ export function parseBlocks(raw: string): Block[] {
       continue;
     }
 
-    // Table detection: a line with at least one `|` where the NEXT
-    // line looks like a GFM separator (`| --- | --- |` or any mix of
-    // pipes + dashes + colons + spaces). Both the header row and the
-    // separator need to be present — a bare pipe in prose shouldn't
-    // trigger the table path.
-    if (line.includes("|")) {
+    // Box-drawing frame detection: top edge `┌────┐`, body lines that
+    // each begin and end with `│`, bottom edge `└────┘`. Models love to
+    // draw decorative frames around code snippets and flow charts using
+    // these characters; without this branch, every body line gets
+    // word-wrapped by Ink and the frame turns into garbage. Rendering
+    // the inner content as a code block preserves the fixed-width
+    // layout the model intended AND gives it a real border via the
+    // existing code-block renderer. Only triggers OUTSIDE code mode
+    // (where `inCode` is false) so a literal box-drawing character
+    // inside a real fenced block isn't grabbed.
+    if (/^\s*┌─+┐\s*$/.test(line)) {
+      let j = i + 1;
+      const bodyLines: string[] = [];
+      while (j < lines.length && !/^\s*└─+┘\s*$/.test(lines[j]!)) {
+        const inner = lines[j]!;
+        // Strip outer `│ ... │` so the content reads naturally.
+        const m = inner.match(/^\s*│\s?(.*?)\s?│\s*$/);
+        bodyLines.push(m ? (m[1] ?? "") : inner);
+        j++;
+      }
+      if (j < lines.length) {
+        flushPara();
+        flushList();
+        out.push({ kind: "code", lang: "", text: bodyLines.join("\n") });
+        i = j;
+        continue;
+      }
+      // No closing edge — fall through and let the line render as
+      // paragraph rather than eating to EOF.
+    }
+
+    // Table detection: a line with at least one column separator where
+    // the NEXT line looks like a separator row. Two flavors accepted:
+    //
+    //   - Standard GFM: `|` columns + `---` / `:---:` separators.
+    //   - Unicode box-drawing: `│` columns (U+2502) + `─` / `┼` (U+2500
+    //     / U+253C) separators. Models trained on Chinese text routinely
+    //     pick the box-drawing characters even when GFM was an option;
+    //     accepting both keeps their output legible without forcing a
+    //     re-prompt. `splitTableRow` normalizes `│` → `|` so the rest of
+    //     the path stays uniform.
+    //
+    // Both the header row and the separator must be present — a bare
+    // pipe in prose shouldn't trigger the table path.
+    if (line.includes("|") || line.includes("│")) {
       const next = (lines[i + 1] ?? "").trim();
-      if (/^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next)) {
+      const isGfmSep = /^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next);
+      const isBoxSep = /^[│─┼┬┴┌┐└┘├┤\s]+$/.test(next) && /─{2,}/.test(next);
+      if (isGfmSep || isBoxSep) {
         flushPara();
         flushList();
         const header = splitTableRow(line);
+        const colCount = header.length;
         const rows: string[][] = [];
         let j = i + 2; // skip header + separator
         while (j < lines.length) {
           const r = lines[j]!.replace(/\s+$/g, "");
-          if (r.trim() === "" || !r.includes("|")) break;
+          if (r.trim() === "") break;
+          if (!r.includes("|") && !r.includes("│")) {
+            // Continuation row: model wrapped a long cell across lines
+            // without re-emitting the column separator. Fold this line
+            // back into the LAST cell of the previous row so its inline
+            // markup (backticks, bold) parses as one piece instead of
+            // bleeding into the paragraph stream below the table.
+            const prev = rows[rows.length - 1];
+            if (prev && prev.length === colCount) {
+              const lastIdx = prev.length - 1;
+              prev[lastIdx] = `${prev[lastIdx] ?? ""} ${r.trim()}`;
+              j++;
+              continue;
+            }
+            break;
+          }
           rows.push(splitTableRow(r));
           j++;
         }
@@ -407,23 +698,23 @@ export function parseBlocks(raw: string): Block[] {
   return out;
 }
 
-function BlockView({ block }: { block: Block }) {
+function BlockView({ block, citations }: { block: Block; citations?: CitationMap }) {
   switch (block.kind) {
     case "heading":
       return (
         <Text bold color="cyan">
-          <InlineMd text={block.text} />
+          <InlineMd text={block.text} citations={citations} />
         </Text>
       );
     case "paragraph":
-      return <InlineMd text={block.text} />;
+      return <InlineMd text={block.text} citations={citations} />;
     case "bullet":
       return (
         <Box flexDirection="column">
           {block.items.map((item, i) => (
             <Box key={`${i}-${item.slice(0, 24)}`}>
               <Text color="cyan">{block.ordered ? ` ${block.start + i}. ` : "  • "}</Text>
-              <InlineMd text={item} />
+              <InlineMd text={item} citations={citations} />
             </Box>
           ))}
         </Box>
@@ -437,21 +728,23 @@ function BlockView({ block }: { block: Block }) {
     case "edit-block":
       return <EditBlockRow block={block} />;
     case "table":
-      return <TableBlockRow block={block} />;
+      return <TableBlockRow block={block} citations={citations} />;
     case "hr":
       return <Text dimColor>{"────────────────────────"}</Text>;
   }
 }
 
 /**
- * Split one table row into trimmed cells. Leading/trailing pipes are
- * optional (both `| a | b |` and `a | b` are accepted). Pipes escaped
- * as `\|` stay in the cell content.
+ * Split one table row into trimmed cells. Leading/trailing column
+ * markers are optional (both `| a | b |` and `a | b` are accepted).
+ * Pipes escaped as `\|` stay in the cell content. Unicode `│`
+ * (U+2502 BOX DRAWINGS LIGHT VERTICAL) is normalized to `|` first so
+ * box-drawing tables and GFM tables share one code path.
  */
 function splitTableRow(line: string): string[] {
   // Temporarily replace escaped pipes so split() doesn't fire on them.
   const SENTINEL = "\u0000";
-  const masked = line.replace(/\\\|/g, SENTINEL);
+  const masked = line.replace(/\\\|/g, SENTINEL).replace(/│/g, "|");
   const trimmed = masked.trim().replace(/^\||\|$/g, "");
   return trimmed.split("|").map((c) => c.trim().replace(new RegExp(SENTINEL, "g"), "|"));
 }
@@ -462,19 +755,19 @@ function splitTableRow(line: string): string[] {
  * doesn't wreck the layout. Header row is bold + cyan; body rows use
  * the default text color. Separator is a dim row of dashes.
  */
-function TableBlockRow({ block }: { block: TableBlock }) {
+function TableBlockRow({ block, citations }: { block: TableBlock; citations?: CitationMap }) {
   const colCount = Math.max(block.header.length, ...block.rows.map((r) => r.length));
   const widths: number[] = [];
   for (let c = 0; c < colCount; c++) {
-    const cellLengths = [displayWidth(block.header[c] ?? "")];
-    for (const r of block.rows) cellLengths.push(displayWidth(r[c] ?? ""));
+    // Use VISIBLE width (post-markup-strip) for column sizing —
+    // otherwise a cell like `**定义** \`dispatch\` 方法` would be
+    // measured with the ** and ` chars included, over-padding once
+    // the markers vanish at render time and shoving subsequent
+    // columns rightward.
+    const cellLengths = [visibleWidth(block.header[c] ?? "")];
+    for (const r of block.rows) cellLengths.push(visibleWidth(r[c] ?? ""));
     widths.push(Math.min(40, Math.max(3, ...cellLengths)));
   }
-  const pad = (s: string, w: number) => {
-    const dw = displayWidth(s);
-    if (dw >= w) return s;
-    return s + " ".repeat(w - dw);
-  };
   const separator = widths.map((w) => "─".repeat(w)).join("─┼─");
   return (
     <Box flexDirection="column">
@@ -482,7 +775,7 @@ function TableBlockRow({ block }: { block: TableBlock }) {
         {block.header.map((cell, ci) => (
           // biome-ignore lint/suspicious/noArrayIndexKey: table columns never reorder — derived from a static header array
           <Text key={`h-${ci}`} bold color="cyan">
-            {pad(cell, widths[ci] ?? 3)}
+            <InlineMd text={cell} padTo={widths[ci] ?? 3} citations={citations} />
             {ci < colCount - 1 ? " │ " : ""}
           </Text>
         ))}
@@ -494,7 +787,7 @@ function TableBlockRow({ block }: { block: TableBlock }) {
           {Array.from({ length: colCount }).map((_, ci) => (
             // biome-ignore lint/suspicious/noArrayIndexKey: same — column axis is fixed by the table shape
             <Text key={`c-${ri}-${ci}`}>
-              {pad(row[ci] ?? "", widths[ci] ?? 3)}
+              <InlineMd text={row[ci] ?? ""} padTo={widths[ci] ?? 3} citations={citations} />
               {ci < colCount - 1 ? " │ " : ""}
             </Text>
           ))}
@@ -582,13 +875,43 @@ function EditBlockRow({ block }: { block: EditBlockView }) {
   );
 }
 
-export function Markdown({ text }: { text: string }) {
+export function Markdown({ text, projectRoot }: { text: string; projectRoot?: string }) {
   const cleaned = stripMath(text);
+  const root = projectRoot ?? process.cwd();
+  const citations = React.useMemo(() => collectCitations(cleaned, root), [cleaned, root]);
   const blocks = React.useMemo(() => parseBlocks(cleaned), [cleaned]);
+  // Collect broken citations into an ordered list so the user sees
+  // exactly which paths/lines failed and why. A bare count ("⚠ 1
+  // broken citation") tells the user something's wrong but leaves them
+  // to scan the wall of text for the red strikethrough — listing each
+  // one with its reason makes the failure actionable: the user can
+  // immediately push back on the specific claim, or decide it doesn't
+  // matter and move on.
+  const broken: Array<{ url: string; reason: string }> = [];
+  for (const [url, status] of citations) {
+    if (!status.ok) broken.push({ url, reason: status.reason });
+  }
   return (
     <Box flexDirection="column" gap={1}>
       {blocks.map((b, i) => (
-        <BlockView key={`${i}-${b.kind}`} block={b} />
+        <BlockView key={`${i}-${b.kind}`} block={b} citations={citations} />
+      ))}
+      {broken.length > 0 ? <BrokenCitationsBlock items={broken} /> : null}
+    </Box>
+  );
+}
+
+function BrokenCitationsBlock({ items }: { items: Array<{ url: string; reason: string }> }) {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="red" paddingX={1}>
+      <Text color="red" bold>
+        {`⚠ ${items.length} broken citation${items.length > 1 ? "s" : ""} — the model referenced paths or lines that don't exist`}
+      </Text>
+      {items.map((b, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: list is derived from a Map iteration order, stable per render
+        <Text key={`bc-${i}`} color="red">
+          {`  ✗ ${b.url} → ${b.reason}`}
+        </Text>
       ))}
     </Box>
   );

src/cli/ui/mcp-browse.ts

@@ -0,0 +1,242 @@
+/**
+ * `/resource` and `/prompt` slash handlers for the chat/code TUI.
+ *
+ * The slash-command registry (slash.ts) advertises both commands so the
+ * argument-level picker and /help surface them, but the actual read/fetch
+ * work is async — McpClient.readResource and getPrompt both round-trip to
+ * the server — so it doesn't fit the synchronous `handleSlash` shape used
+ * by every other slash command. App.tsx intercepts the commands directly
+ * and calls into the helpers below.
+ *
+ * Split by effect boundary:
+ *   - formatters (resource list, contents, prompt list, messages) are
+ *     pure over already-fetched data and unit-tested
+ *   - find-server helpers are pure lookups against inspection reports
+ *   - `handleMcpBrowseSlash` is the async orchestrator App.tsx calls
+ *
+ * v1 intentionally does NOT inject the fetched resource/prompt into the
+ * next model turn. It's a display-only browser so users can see what
+ * their MCP servers expose. A future version may add a Tab-to-inject
+ * hotkey once the UX is settled.
+ */
+
+import type { McpClient } from "../../mcp/client.js";
+import type {
+  GetPromptResult,
+  McpPromptMessage,
+  McpResourceContents,
+  ReadResourceResult,
+} from "../../mcp/types.js";
+import type { DisplayEvent } from "./EventLog.js";
+import type { McpServerSummary } from "./slash.js";
+
+/**
+ * React setState for Historical — typed loose because the App state
+ * shape is App-internal. We only ever append, so `(prev) => prev.concat(row)`
+ * works against any array-of-DisplayEvent state.
+ */
+export type HistoricalSetter = (updater: (prev: DisplayEvent[]) => DisplayEvent[]) => void;
+
+export function formatResourceList(servers: readonly McpServerSummary[]): string {
+  const lines: string[] = [];
+  let total = 0;
+  for (const s of servers) {
+    if (!s.report.resources.supported) continue;
+    const items = s.report.resources.items;
+    if (items.length === 0) continue;
+    lines.push(`[${s.label}] ${items.length} resource(s):`);
+    for (const r of items.slice(0, 20)) {
+      const name = r.name && r.name !== r.uri ? `  ${r.name}` : "";
+      const mime = r.mimeType ? ` · ${r.mimeType}` : "";
+      lines.push(`  · ${r.uri}${name}${mime}`);
+      total++;
+    }
+    if (items.length > 20) lines.push(`  (+${items.length - 20} more)`);
+    lines.push("");
+  }
+  if (total === 0) {
+    return "No resources on any connected MCP server (or no servers connected). `/mcp` shows the current set.";
+  }
+  lines.push("Read one: `/resource <uri>` — or use Tab in the picker.");
+  return lines.join("\n");
+}
+
+export function formatPromptList(servers: readonly McpServerSummary[]): string {
+  const lines: string[] = [];
+  let total = 0;
+  for (const s of servers) {
+    if (!s.report.prompts.supported) continue;
+    const items = s.report.prompts.items;
+    if (items.length === 0) continue;
+    lines.push(`[${s.label}] ${items.length} prompt(s):`);
+    for (const p of items.slice(0, 20)) {
+      const desc = p.description ? ` — ${p.description}` : "";
+      const argHint =
+        p.arguments && p.arguments.length > 0
+          ? ` (args: ${p.arguments.map((a) => a.name + (a.required ? "*" : "?")).join(", ")})`
+          : "";
+      lines.push(`  · ${p.name}${argHint}${desc}`);
+      total++;
+    }
+    if (items.length > 20) lines.push(`  (+${items.length - 20} more)`);
+    lines.push("");
+  }
+  if (total === 0) {
+    return "No prompts on any connected MCP server (or no servers connected). `/mcp` shows the current set.";
+  }
+  lines.push(
+    "Fetch one: `/prompt <name>` — args are not supported yet; prompts with required args will surface an error from the server.",
+  );
+  return lines.join("\n");
+}
+
+export function findServerForResource(
+  servers: readonly McpServerSummary[],
+  uri: string,
+): McpServerSummary | null {
+  for (const s of servers) {
+    if (!s.report.resources.supported) continue;
+    if (s.report.resources.items.some((r) => r.uri === uri)) return s;
+  }
+  return null;
+}
+
+export function findServerForPrompt(
+  servers: readonly McpServerSummary[],
+  name: string,
+): McpServerSummary | null {
+  for (const s of servers) {
+    if (!s.report.prompts.supported) continue;
+    if (s.report.prompts.items.some((p) => p.name === name)) return s;
+  }
+  return null;
+}
+
+export function formatResourceContents(uri: string, result: ReadResourceResult): string {
+  const lines: string[] = [`Resource ${uri} (${result.contents.length} content block(s)):`, ""];
+  for (let i = 0; i < result.contents.length; i++) {
+    const c = result.contents[i]!;
+    const header = `— block ${i + 1}${c.mimeType ? ` · ${c.mimeType}` : ""}`;
+    lines.push(header);
+    lines.push(formatOneResourceContent(c));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function formatOneResourceContent(c: McpResourceContents): string {
+  if ("text" in c) {
+    const MAX = 8_000;
+    if (c.text.length > MAX) {
+      return `${c.text.slice(0, MAX)}\n\n[…truncated ${c.text.length - MAX} chars; full contents available via McpClient.readResource in library mode.]`;
+    }
+    return c.text;
+  }
+  // blob — we can't render arbitrary binary in the TUI; give the size.
+  const bytes = typeof c.blob === "string" ? approximateBase64ByteSize(c.blob) : 0;
+  return `[binary · ~${bytes.toLocaleString()} bytes · base64]`;
+}
+
+function approximateBase64ByteSize(b64: string): number {
+  // 4 base64 chars encode 3 bytes; padding `=` trims the output.
+  const padding = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+  return Math.floor((b64.length * 3) / 4) - padding;
+}
+
+export function formatPromptMessages(name: string, result: GetPromptResult): string {
+  const lines: string[] = [
+    `Prompt ${name}${result.description ? ` — ${result.description}` : ""}`,
+    `(${result.messages.length} message(s))`,
+    "",
+  ];
+  for (let i = 0; i < result.messages.length; i++) {
+    const m = result.messages[i]!;
+    lines.push(`— ${i + 1}. ${m.role}`);
+    lines.push(formatOnePromptMessage(m));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function formatOnePromptMessage(m: McpPromptMessage): string {
+  const block = m.content as { type?: string; text?: string; resource?: McpResourceContents };
+  if (block.type === "text" && typeof block.text === "string") return block.text;
+  if (block.type === "resource" && block.resource) {
+    return `[resource: ${block.resource.uri}]\n${formatOneResourceContent(block.resource)}`;
+  }
+  return `[non-text content: ${block.type ?? "unknown"}]`;
+}
+
+/**
+ * Orchestrator. Looks up the right server, calls readResource/getPrompt
+ * via its `client`, and pushes one info row into `Historical`. Errors
+ * (server missing, -32601, network) surface as a warning row; the user
+ * can always fall back to `reasonix mcp inspect <spec>` for diagnostics.
+ */
+export async function handleMcpBrowseSlash(
+  kind: "resource" | "prompt",
+  arg: string,
+  servers: readonly McpServerSummary[],
+  setHistorical: HistoricalSetter,
+): Promise<void> {
+  const ts = Date.now();
+  const push = (role: DisplayEvent["role"], text: string) => {
+    setHistorical((prev) => [...prev, { id: `mcp-${role}-${ts}-${prev.length}`, role, text }]);
+  };
+
+  // No arg → list mode.
+  if (!arg) {
+    push("info", kind === "resource" ? formatResourceList(servers) : formatPromptList(servers));
+    return;
+  }
+
+  if (kind === "resource") {
+    const server = findServerForResource(servers, arg);
+    if (!server) {
+      push(
+        "warning",
+        `no server exposes resource "${arg}". \`/resource\` with no arg lists what's available.`,
+      );
+      return;
+    }
+    const client: McpClient | undefined = server.client;
+    if (!client) {
+      push(
+        "warning",
+        `server [${server.label}] is not connected (display-only). Resource read requires a live MCP client.`,
+      );
+      return;
+    }
+    try {
+      const result = await client.readResource(arg);
+      push("info", formatResourceContents(arg, result));
+    } catch (err) {
+      push("warning", `readResource failed: ${(err as Error).message}`);
+    }
+    return;
+  }
+
+  // prompt
+  const server = findServerForPrompt(servers, arg);
+  if (!server) {
+    push(
+      "warning",
+      `no server exposes prompt "${arg}". \`/prompt\` with no arg lists what's available.`,
+    );
+    return;
+  }
+  const client: McpClient | undefined = server.client;
+  if (!client) {
+    push(
+      "warning",
+      `server [${server.label}] is not connected (display-only). Prompt fetch requires a live MCP client.`,
+    );
+    return;
+  }
+  try {
+    const result = await client.getPrompt(arg);
+    push("info", formatPromptMessages(arg, result));
+  } catch (err) {
+    push("warning", `getPrompt failed: ${(err as Error).message}`);
+  }
+}

src/cli/ui/multiline-keys.ts

@@ -1,30 +1,34 @@
 /**
- * Pure keystroke → action reducer for MultilineInput.
+ * Pure keystroke → action reducer for PromptInput.
  *
- * Kept separate from the React component so the keyboard
- * semantics are easy to unit-test. MultilineInput is otherwise
- * a thin Ink wrapper that threads its `useInput` callback
- * through this function and applies the result.
+ * Kept separate from the React component so the keyboard semantics
+ * are easy to unit-test. The component threads `useInput` through
+ * this function and applies the returned action.
  *
- * Terminal reality check: on most terminals, pressing Shift+Enter
- * sends the exact same byte as plain Enter — the modifier is lost.
- * That's why the reliable newline insertion path is Ctrl+J (which
- * really is LF, distinct from CR), with Shift+Enter only working
- * on terminals that opt into CSI-u modifier encoding. The `\<Enter>`
- * bash-style continuation is the portable fallback.
+ * Edit model:
+ *   - Full cursor support. ←/→ move one column. ↑/↓ move across
+ *     lines in a multi-line buffer (column preserved when possible).
+ *     Ctrl+A / Ctrl+E jump to start / end of the current line.
+ *   - Backspace deletes the char before the cursor; Delete deletes
+ *     the char under the cursor.
+ *   - Printable chars (including multi-char paste bursts) insert
+ *     at the cursor.
+ *   - Enter submits unless Shift is held (newline), the line ends
+ *     with '\' and cursor is at end (bash-style continuation), or
+ *     the input is Ctrl+J (LF, terminal-universal newline).
+ *   - Parent owns Tab, Esc, PageUp/Down (slash-complete, abort,
+ *     unused). Arrow keys are split: empty buffer → parent (history
+ *     recall); non-empty → child (cursor movement).
  */
 
 export interface MultilineKey {
-  /** Printable character(s) delivered by the key event, may be empty. */
   input: string;
-  /** Modifier + named-key flags as Ink reports them. */
   return?: boolean;
   shift?: boolean;
   ctrl?: boolean;
   meta?: boolean;
   backspace?: boolean;
   delete?: boolean;
-  /** Navigation/editing keys owned by the parent App (slash-nav, history). */
   tab?: boolean;
   upArrow?: boolean;
   downArrow?: boolean;
@@ -36,87 +40,160 @@ export interface MultilineKey {
 }
 
 export interface MultilineAction {
-  /** New value to set on the text buffer. `null` = unchanged. */
+  /** New buffer value. `null` = unchanged. */
   next: string | null;
-  /** When `true`, the caller should fire `onSubmit(next ?? value)`. */
+  /** New cursor position (0..value.length). `null` = unchanged. */
+  cursor: number | null;
+  /** When `true`, fire `onSubmit(submitValue ?? value)`. */
   submit: boolean;
-  /** When submitting, which value to submit (after any final trims). */
   submitValue?: string;
 }
 
 const BACKSLASH_SUFFIX = /\\$/;
 
-/**
- * Decide what to do with a single keystroke against the current buffer.
- *
- * Decisions:
- *   Ctrl+J              → insert '\n' (terminal-universal newline)
- *   Shift+Return        → insert '\n' (works where CSI-u is on)
- *   Enter with "\" end  → replace trailing '\' with '\n' (bash continuation)
- *   Enter               → submit the current buffer
- *   Backspace/Delete    → drop one char from the end (cursor-at-end model)
- *   Printable char(s)   → append at the end
- *
- * We don't model an insertion cursor inside the string: always-at-end
- * keeps the reducer tiny and matches how readline-in-raw-mode feels. The
- * user can still edit by backspacing — for deep edits, exit and compose
- * in $EDITOR.
- */
-export function processMultilineKey(value: string, key: MultilineKey): MultilineAction {
-  // Parent App owns these keys: Tab for slash auto-complete, arrows
-  // for slash-nav/history, Esc for abort. Bowing out here keeps the
-  // text buffer from eating a stray "\t" or arrow escape sequence
-  // when both the parent and child useInput fire on the same event.
-  if (
-    key.tab ||
-    key.upArrow ||
-    key.downArrow ||
-    key.leftArrow ||
-    key.rightArrow ||
-    key.escape ||
-    key.pageUp ||
-    key.pageDown
-  ) {
-    return { next: null, submit: false };
+const NOOP: MultilineAction = { next: null, cursor: null, submit: false };
+
+export function processMultilineKey(
+  value: string,
+  cursor: number,
+  key: MultilineKey,
+): MultilineAction {
+  // Parent-owned keys: Tab (slash-complete), Esc (abort), PageUp/Down.
+  if (key.tab || key.escape || key.pageUp || key.pageDown) {
+    return NOOP;
   }
 
-  // Reliable newline: Ctrl+J arrives as literal '\n' in key.input on
-  // every terminal we've checked. We also accept key.ctrl && input=='j'
-  // as a belt-and-braces match against terminals that normalize the
-  // control-char into its ASCII letter form.
+  // Empty buffer + ↑/↓ → parent handles history recall.
+  if (value.length === 0 && (key.upArrow || key.downArrow)) {
+    return NOOP;
+  }
+
+  // Cursor motion.
+  if (key.leftArrow) {
+    return { next: null, cursor: Math.max(0, cursor - 1), submit: false };
+  }
+  if (key.rightArrow) {
+    return { next: null, cursor: Math.min(value.length, cursor + 1), submit: false };
+  }
+  if (key.upArrow) {
+    const moved = moveCursorUp(value, cursor);
+    return moved === cursor ? NOOP : { next: null, cursor: moved, submit: false };
+  }
+  if (key.downArrow) {
+    const moved = moveCursorDown(value, cursor);
+    return moved === cursor ? NOOP : { next: null, cursor: moved, submit: false };
+  }
+
+  // Emacs-style line jumps (universal across terminals; Home/End aren't
+  // reliably reported by Ink so we don't depend on them).
+  if (key.ctrl && key.input === "a") {
+    return { next: null, cursor: startOfLine(value, cursor), submit: false };
+  }
+  if (key.ctrl && key.input === "e") {
+    return { next: null, cursor: endOfLine(value, cursor), submit: false };
+  }
+
+  // Newline: Ctrl+J (LF literal) or ctrl+'j' normalized form.
   if (key.input === "\n" || (key.ctrl && key.input === "j")) {
-    return { next: `${value}\n`, submit: false };
+    return insertAt(value, cursor, "\n");
   }
 
   if (key.return) {
-    // Shift+Return → newline (when terminal reports the modifier).
-    if (key.shift) {
-      return { next: `${value}\n`, submit: false };
+    if (key.shift) return insertAt(value, cursor, "\n");
+    // Bash-style line continuation: trailing '\' + Enter (only when the
+    // cursor sits at end-of-buffer, so a stray '\' mid-line doesn't
+    // trigger it).
+    if (cursor === value.length && BACKSLASH_SUFFIX.test(value)) {
+      const replaced = `${value.slice(0, -1)}\n`;
+      return { next: replaced, cursor: replaced.length, submit: false };
     }
-    // Bash-style line continuation: trailing '\' + Enter.
-    if (BACKSLASH_SUFFIX.test(value)) {
-      return { next: `${value.slice(0, -1)}\n`, submit: false };
-    }
-    // Plain Enter → submit.
-    return { next: null, submit: true, submitValue: value };
+    return { next: null, cursor: null, submit: true, submitValue: value };
   }
 
-  if (key.backspace || key.delete) {
-    if (value.length === 0) return { next: null, submit: false };
-    return { next: value.slice(0, -1), submit: false };
+  // Backspace = delete the char BEFORE the cursor. We also accept
+  // `key.delete` and the raw DEL (0x7f) / BS (0x08) bytes as backspace
+  // for the same purpose — some Windows terminals (cmd.exe, certain
+  // winpty configs) report plain Backspace without setting
+  // `key.backspace`, which used to leave the user typing into a prompt
+  // where the Backspace key did nothing. Reasonix doesn't offer a
+  // separate forward-delete operation, so collapsing them is safe.
+  if (key.backspace || key.delete || key.input === "\x7f" || key.input === "\b") {
+    if (cursor === 0) return NOOP;
+    return {
+      next: value.slice(0, cursor - 1) + value.slice(cursor),
+      cursor: cursor - 1,
+      submit: false,
+    };
   }
 
-  // Ignore bare modifier keys (ctrl/meta without accompanying printable).
-  if ((key.ctrl || key.meta) && key.input.length === 0) {
-    return { next: null, submit: false };
+  // Bare modifier events (Ctrl/Meta with no printable) and unhandled
+  // Ctrl-<letter> chords are dropped so a stray Ctrl+L doesn't insert "l".
+  if ((key.ctrl || key.meta) && key.input.length === 0) return NOOP;
+  if (key.ctrl || key.meta) return NOOP;
+
+  // Printable input (may be a multi-char paste; pasted newlines land
+  // inside the buffer rather than triggering submit on the first line).
+  if (key.input.length > 0) {
+    return insertAt(value, cursor, key.input);
   }
 
-  // Printable input (may be a multi-char paste burst — accept as-is;
-  // pasted newlines become part of the buffer rather than triggering
-  // submit on the first line).
-  if (key.input.length > 0 && !key.ctrl && !key.meta) {
-    return { next: value + key.input, submit: false };
+  return NOOP;
+}
+
+function insertAt(value: string, cursor: number, insert: string): MultilineAction {
+  return {
+    next: value.slice(0, cursor) + insert + value.slice(cursor),
+    cursor: cursor + insert.length,
+    submit: false,
+  };
+}
+
+/**
+ * Line + column of a cursor inside a buffer. Exported because the
+ * renderer needs the same mapping for drawing the cursor block on the
+ * right line.
+ */
+export function lineAndColumn(value: string, cursor: number): { line: number; col: number } {
+  let line = 0;
+  let col = 0;
+  const n = Math.min(cursor, value.length);
+  for (let i = 0; i < n; i++) {
+    if (value[i] === "\n") {
+      line++;
+      col = 0;
+    } else {
+      col++;
+    }
   }
+  return { line, col };
+}
+
+function startOfLine(value: string, cursor: number): number {
+  return value.lastIndexOf("\n", cursor - 1) + 1;
+}
+
+function endOfLine(value: string, cursor: number): number {
+  const nl = value.indexOf("\n", cursor);
+  return nl === -1 ? value.length : nl;
+}
+
+function moveCursorUp(value: string, cursor: number): number {
+  const curStart = startOfLine(value, cursor);
+  if (curStart === 0) return cursor; // already on the first line
+  const col = cursor - curStart;
+  const prevEnd = curStart - 1; // the '\n' between the two lines
+  const prevStart = value.lastIndexOf("\n", prevEnd - 1) + 1;
+  const prevLen = prevEnd - prevStart;
+  return prevStart + Math.min(col, prevLen);
+}
 
-  return { next: null, submit: false };
+function moveCursorDown(value: string, cursor: number): number {
+  const nextNl = value.indexOf("\n", cursor);
+  if (nextNl === -1) return cursor; // already on the last line
+  const curStart = startOfLine(value, cursor);
+  const col = cursor - curStart;
+  const nextStart = nextNl + 1;
+  const followingNl = value.indexOf("\n", nextStart);
+  const nextLen = (followingNl === -1 ? value.length : followingNl) - nextStart;
+  return nextStart + Math.min(col, nextLen);
 }

src/cli/ui/paste-collapse.ts

@@ -0,0 +1,81 @@
+/**
+ * Collapse long user-typed input for display purposes.
+ *
+ * Problem: pasting a stack trace, log dump, or sample file into the
+ * prompt box floods the Historical scrollback with a huge block — the
+ * user can't see their previous turns, the assistant's replies, or
+ * where the cursor is. Terminal UIs have shipped this shape for
+ * years (iTerm's "pasted text" notation, Claude Code's preview).
+ *
+ * Split of concerns: the MODEL still gets the full text. This helper
+ * only rewrites what we render in the Historical row. `@` expansions
+ * and `!` bang outputs have their own display paths (unaffected).
+ */
+
+/** Defaults tuned to typical prose vs. typical code-paste shapes. */
+export const DEFAULT_PASTE_LINE_THRESHOLD = 40;
+export const DEFAULT_PASTE_CHAR_THRESHOLD = 2000;
+/** Lines kept visible at the head of a collapsed paste. */
+export const DEFAULT_PASTE_HEAD_LINES = 10;
+
+export interface PasteCollapseOptions {
+  lineThreshold?: number;
+  charThreshold?: number;
+  headLines?: number;
+}
+
+export interface PasteCollapseResult {
+  /** Text to render in the Historical row (possibly collapsed). */
+  displayText: string;
+  /** True when collapsing happened. False = input passed through verbatim. */
+  collapsed: boolean;
+  /** Original char length — exposed so callers can log/annotate. */
+  originalChars: number;
+  /** Original line count. */
+  originalLines: number;
+}
+
+/**
+ * Collapse `input` when it exceeds either the line OR char threshold.
+ * Display shape:
+ *
+ *     ▸ pasted 2.3 KB (84 lines) — first 10 shown, full text sent to model
+ *     line 1
+ *     line 2
+ *     …
+ *     line 10
+ *     … (74 more lines)
+ *
+ * Short input passes through unchanged — collapsed = false.
+ */
+export function formatLongPaste(
+  input: string,
+  opts: PasteCollapseOptions = {},
+): PasteCollapseResult {
+  const lineCap = opts.lineThreshold ?? DEFAULT_PASTE_LINE_THRESHOLD;
+  const charCap = opts.charThreshold ?? DEFAULT_PASTE_CHAR_THRESHOLD;
+  const headN = Math.max(1, opts.headLines ?? DEFAULT_PASTE_HEAD_LINES);
+
+  const originalChars = input.length;
+  const lines = input.split("\n");
+  const originalLines = lines.length;
+
+  if (originalChars <= charCap && originalLines <= lineCap) {
+    return { displayText: input, collapsed: false, originalChars, originalLines };
+  }
+
+  const header = `▸ pasted ${formatBytes(originalChars)} (${originalLines} lines) — first ${Math.min(headN, originalLines)} shown, full text sent to model`;
+  const head = lines.slice(0, headN).join("\n");
+  const remaining = originalLines - headN;
+  const footer = remaining > 0 ? `… (${remaining} more line${remaining === 1 ? "" : "s"})` : "";
+  const displayText = footer ? `${header}\n${head}\n${footer}` : `${header}\n${head}`;
+  return { displayText, collapsed: true, originalChars, originalLines };
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const kb = n / 1024;
+  if (kb < 1024) return `${kb.toFixed(kb >= 10 ? 0 : 1)} KB`;
+  const mb = kb / 1024;
+  return `${mb.toFixed(mb >= 10 ? 0 : 1)} MB`;
+}

src/client.ts

@@ -64,6 +64,23 @@ export interface UserBalance {
   balance_infos: BalanceInfo[];
 }
 
+/**
+ * Response shape for DeepSeek's `/models` endpoint. Mirrors the OpenAI
+ * models list shape DeepSeek copied — `id` is the model name to pass to
+ * `/chat/completions`, `owned_by` is the provider string (always
+ * `"deepseek"` today).
+ */
+export interface ModelInfo {
+  id: string;
+  object: "model";
+  owned_by: string;
+}
+
+export interface ModelList {
+  object: "list";
+  data: ModelInfo[];
+}
+
 export interface DeepSeekClientOptions {
   apiKey?: string;
   baseUrl?: string;
@@ -133,6 +150,29 @@ export class DeepSeekClient {
     }
   }
 
+  /**
+   * Fetch the model catalog DeepSeek currently exposes. Today this is
+   * `deepseek-chat` (V3) and `deepseek-reasoner` (R1), but querying is
+   * the only way to learn about new ones without a Reasonix release.
+   * Returns null on any network/auth failure so callers can degrade
+   * gracefully — e.g. `/models` falls back to the hardcoded hint.
+   */
+  async listModels(opts: { signal?: AbortSignal } = {}): Promise<ModelList | null> {
+    try {
+      const resp = await this._fetch(`${this.baseUrl}/models`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: opts.signal,
+      });
+      if (!resp.ok) return null;
+      const data = (await resp.json()) as ModelList;
+      if (!data || !Array.isArray(data.data)) return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
   async chat(opts: ChatRequestOptions): Promise<ChatResponse> {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);

src/code/diff-preview.ts

@@ -0,0 +1,124 @@
+/**
+ * Render a SEARCH/REPLACE edit block as a compact unified-diff-style
+ * preview for the code-mode confirm gate. Shows the user what's about
+ * to land on disk BEFORE they press `y` — catches "wrong file" and
+ * "wrong replacement" mistakes that the old path + line-count summary
+ * couldn't.
+ *
+ * Not a full Myers diff: we trim shared leading/trailing lines as
+ * context and render the middle divergence as `-old` / `+new`. That's
+ * enough for the common SEARCH/REPLACE shape (small change inside a
+ * function body, wrapped with a few lines of surrounding code for
+ * uniqueness) and avoids pulling in a diff library.
+ */
+
+import type { EditBlock } from "./edit-blocks.js";
+
+export interface DiffPreviewOptions {
+  /** How many lines of unchanged context to show at each end. Default 2. */
+  contextLines?: number;
+  /** Hard cap on total rendered lines. Default 20 — beyond this the preview collapses. */
+  maxLines?: number;
+  /** Indent applied to every output line. Default 8 spaces — matches the pending-preview nesting. */
+  indent?: string;
+}
+
+/** Render one edit block's diff. Returns an array of formatted lines. */
+export function formatEditBlockDiff(block: EditBlock, opts: DiffPreviewOptions = {}): string[] {
+  const contextLines = Math.max(0, opts.contextLines ?? 2);
+  const maxLines = Math.max(4, opts.maxLines ?? 20);
+  const indent = opts.indent ?? "        ";
+
+  const search = block.search === "" ? [] : block.search.split("\n");
+  const replace = block.replace.split("\n");
+
+  // New-file case: no search to compare, show the full new content
+  // (capped). Mark every line `+` so the user knows it's all additions.
+  if (search.length === 0) {
+    return renderAllPlus(replace, indent, maxLines);
+  }
+
+  // Common leading / trailing lines — shared context we can collapse.
+  let leading = 0;
+  while (
+    leading < search.length &&
+    leading < replace.length &&
+    search[leading] === replace[leading]
+  ) {
+    leading++;
+  }
+  let trailing = 0;
+  while (
+    trailing < search.length - leading &&
+    trailing < replace.length - leading &&
+    search[search.length - 1 - trailing] === replace[replace.length - 1 - trailing]
+  ) {
+    trailing++;
+  }
+
+  const searchMiddle = search.slice(leading, search.length - trailing);
+  const replaceMiddle = replace.slice(leading, replace.length - trailing);
+
+  // Trim context to `contextLines` on each side.
+  const leadShown = search.slice(Math.max(0, leading - contextLines), leading);
+  const leadHidden = leading - leadShown.length;
+  const trailShown = search.slice(
+    search.length - trailing,
+    search.length - trailing + contextLines,
+  );
+  const trailHidden = trailing - trailShown.length;
+
+  const out: string[] = [];
+  if (leadHidden > 0) {
+    out.push(`${indent}  … ${leadHidden} unchanged line${leadHidden === 1 ? "" : "s"} above`);
+  }
+  for (const l of leadShown) out.push(`${indent}  ${l}`);
+  for (const l of searchMiddle) out.push(`${indent}- ${l}`);
+  for (const l of replaceMiddle) out.push(`${indent}+ ${l}`);
+  for (const l of trailShown) out.push(`${indent}  ${l}`);
+  if (trailHidden > 0) {
+    out.push(`${indent}  … ${trailHidden} unchanged line${trailHidden === 1 ? "" : "s"} below`);
+  }
+
+  return capLines(out, maxLines, indent);
+}
+
+/**
+ * Render the full set of blocks back-to-back, each preceded by a
+ * path-and-size header so the user can tell which file owns each
+ * diff chunk. Blocks are separated by a blank line for breathing room.
+ */
+export function formatAllBlockDiffs(
+  blocks: readonly EditBlock[],
+  opts: DiffPreviewOptions = {},
+): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const b = blocks[i]!;
+    const removed = b.search === "" ? 0 : countLines(b.search);
+    const added = countLines(b.replace);
+    const tag = b.search === "" ? "NEW " : "    ";
+    if (i > 0) out.push("");
+    out.push(`  ${tag}${b.path}  (-${removed} +${added} lines)`);
+    out.push(...formatEditBlockDiff(b, opts));
+  }
+  return out;
+}
+
+function countLines(s: string): number {
+  if (s.length === 0) return 0;
+  return (s.match(/\n/g)?.length ?? 0) + 1;
+}
+
+function renderAllPlus(lines: string[], indent: string, maxLines: number): string[] {
+  const out = lines.map((l) => `${indent}+ ${l}`);
+  return capLines(out, maxLines, indent);
+}
+
+function capLines(lines: string[], maxLines: number, indent: string): string[] {
+  if (lines.length <= maxLines) return lines;
+  const head = lines.slice(0, maxLines - 1);
+  const hidden = lines.length - head.length;
+  head.push(`${indent}… (${hidden} more diff lines — full content applies on /apply)`);
+  return head;
+}

src/code/pending-edits.ts

@@ -0,0 +1,111 @@
+/**
+ * Durable checkpoint for the pending-edits queue.
+ *
+ * Code mode holds parsed SEARCH/REPLACE blocks in an in-memory
+ * `useRef<EditBlock[]>` until the user runs `/apply` or `/discard`.
+ * Pre-0.5.14 that was ephemeral: a crash or accidental Ctrl+C after
+ * the model proposed seven edits discarded all seven — the session
+ * log had the assistant text, but the "please review this batch"
+ * state was gone.
+ *
+ * This module checkpoints the queue to
+ *   `~/.reasonix/sessions/<name>.pending.json`
+ * after every mutation (parse → set / apply → clear / discard →
+ * clear). On session resume the App reads the file and re-populates
+ * the queue. If the file doesn't exist the session resumes as before.
+ *
+ * Format choices:
+ *   - JSON (not JSONL) — the queue is a single array written at once,
+ *     not a stream of records.
+ *   - Overwrite-on-write — the queue is small (kilobytes) and atomicity
+ *     is "last write wins"; partial-write on crash is fine since we'd
+ *     rather lose the checkpoint than have a torn file block resume.
+ *   - Best-effort I/O — disk full or permission denied must not break
+ *     the session. Silent skip matches the rest of the durable logs
+ *     (session.ts, usage.ts).
+ *
+ * Ephemeral sessions (sessionName === null) skip persistence entirely:
+ * there's no stable name to key the checkpoint to.
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sanitizeName, sessionsDir } from "../session.js";
+import type { EditBlock } from "./edit-blocks.js";
+
+/** Absolute path for the checkpoint file that belongs to this session. */
+export function pendingEditsPath(sessionName: string): string {
+  return join(sessionsDir(), `${sanitizeName(sessionName)}.pending.json`);
+}
+
+/**
+ * Write the queue to disk, or delete the checkpoint file when `blocks`
+ * is empty. Callers pass the full current queue every time; we don't
+ * attempt append-style deltas because the queue is tiny.
+ *
+ * No-op when `sessionName` is null (ephemeral session has nowhere to
+ * write), so call sites can pass the session name directly without a
+ * null guard.
+ */
+export function savePendingEdits(sessionName: string | null, blocks: EditBlock[]): void {
+  if (!sessionName) return;
+  const path = pendingEditsPath(sessionName);
+  try {
+    if (blocks.length === 0) {
+      if (existsSync(path)) unlinkSync(path);
+      return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(blocks, null, 2), "utf8");
+  } catch {
+    /* best-effort — disk full / perms should not break the session */
+  }
+}
+
+/**
+ * Load the queue from disk, returns `null` when there's no checkpoint.
+ * A malformed file (power-loss torn write, user hand-edit) also returns
+ * null — silent recovery beats failing to open the session.
+ */
+export function loadPendingEdits(sessionName: string | null): EditBlock[] | null {
+  if (!sessionName) return null;
+  const path = pendingEditsPath(sessionName);
+  if (!existsSync(path)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return null;
+    const out: EditBlock[] = [];
+    for (const item of parsed) {
+      if (
+        item &&
+        typeof item === "object" &&
+        typeof item.path === "string" &&
+        typeof item.search === "string" &&
+        typeof item.replace === "string" &&
+        typeof item.offset === "number"
+      ) {
+        out.push(item as EditBlock);
+      }
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/** Delete the checkpoint file unconditionally — called by /apply and /discard. */
+export function clearPendingEdits(sessionName: string | null): void {
+  if (!sessionName) return;
+  const path = pendingEditsPath(sessionName);
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    /* best-effort */
+  }
+}

src/code/prompt.ts

@@ -15,9 +15,69 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { applyMemoryStack } from "../user-memory.js";
 
 export const CODE_SYSTEM_PROMPT = `You are Reasonix Code, a coding assistant. You have filesystem tools (read_file, write_file, list_directory, search_files, etc.) rooted at the user's working directory.
 
+# Cite or shut up — non-negotiable
+
+Every factual claim you make about THIS codebase must be backed by evidence. Reasonix VALIDATES the citations you write — broken paths or out-of-range lines render in **red strikethrough with ❌** in front of the user.
+
+**Positive claims** (a file exists, a function does X, a feature IS implemented) — append a markdown link to the source:
+
+- ✅ Correct: \`The MCP client supports listResources [listResources](src/mcp/client.ts:142).\`
+- ❌ Wrong:   \`The MCP client supports listResources.\` ← no citation, looks authoritative but unverifiable.
+
+**Negative claims** (X is missing, Y is not implemented, lacks Z, doesn't have W) are the **most common hallucination shape**. They feel safe to write because no citation seems possible — but that's exactly why you must NOT write them on instinct.
+
+If you are about to write "X is missing" or "Y is not implemented" — **STOP**. Call \`search_content\` for the relevant symbol or term FIRST. Only then:
+
+- If the search returns matches → you were wrong; correct yourself and cite the matches.
+- If the search returns nothing → state the absence with the search query as your evidence: \`No callers of \\\`foo()\\\` found (search_content "foo").\`
+
+Asserting absence without a search is the #1 way evaluative answers go wrong. Treat the urge to write "missing" as a red flag in your own reasoning.
+
+# When to propose a plan (submit_plan)
+
+You have a \`submit_plan\` tool that shows the user a markdown plan and lets them Approve / Refine / Cancel before you execute. Use it proactively when the task is large enough to deserve a review gate:
+
+- Multi-file refactors or renames.
+- Architecture changes (moving modules, splitting / merging files, new abstractions).
+- Anything where "undo" after the fact would be expensive — migrations, destructive cleanups, API shape changes.
+- When the user's request is ambiguous and multiple reasonable interpretations exist — propose your reading as a plan and let them confirm.
+
+Skip submit_plan for small, obvious changes: one-line typo, clear bug with a clear fix, adding a missing import, renaming a local variable. Just do those.
+
+Plan body: one-sentence summary, then a file-by-file breakdown of what you'll change and why, and any risks or open questions. If some decisions are genuinely up to the user (naming, tradeoffs, out-of-scope possibilities), list them in an "Open questions" section — the user sees the plan in a picker and has a text input to answer your questions before approving. Don't pretend certainty you don't have; flagged questions are how the user tells you what they care about. After calling submit_plan, STOP — don't call any more tools, wait for the user's verdict.
+
+# Plan mode (/plan)
+
+The user can ALSO enter "plan mode" via /plan, which is a stronger, explicit constraint:
+- Write tools (edit_file, write_file, create_directory, move_file) and non-allowlisted run_command calls are BOUNCED at dispatch — you'll get a tool result like "unavailable in plan mode". Don't retry them.
+- Read tools (read_file, list_directory, search_files, directory_tree, get_file_info) and allowlisted read-only / test shell commands still work — use them to investigate.
+- You MUST call submit_plan before anything will execute. Approve exits plan mode; Refine stays in; Cancel exits without implementing.
+
+
+# Delegating to subagents via Skills (🧬)
+
+The pinned Skills index below lists playbooks you can invoke with \`run_skill\`. Skills marked with **🧬** spawn an **isolated subagent** — a fresh child loop that runs the playbook in its own context and returns only the final answer. The subagent's tool calls and reasoning never enter your context, so 🧬 skills are how you keep the main session lean.
+
+Two built-ins ship by default:
+- **🧬 explore** — read-only investigation across the codebase. Use when the user says things like "find all places that...", "how does X work across the project", "survey the code for Y". Pass \`arguments\` describing the concrete question.
+- **🧬 research** — combines web search + code reading. Use for "is X supported by lib Y", "what's the canonical way to Z", "compare our impl to the spec".
+
+When to delegate (call \`run_skill\` with a 🧬 skill):
+- The task would otherwise need >5 file reads or searches.
+- You only need the conclusion, not the exploration trail.
+- The work is self-contained (you can describe it in one paragraph).
+
+When NOT to delegate:
+- Direct, narrow questions answerable in 1-2 tool calls — just do them.
+- Anything where you need to track intermediate results yourself (planning, multi-step edits).
+- Anything that requires user interaction (subagents can't submit plans or ask you for clarification).
+
+Always pass a clear, self-contained \`arguments\` — that text is the **only** context the subagent gets.
+
 # When to edit vs. when to explore
 
 Only propose edits when the user explicitly asks you to change, fix, add, remove, refactor, or write something. Do NOT propose edits when the user asks you to:
@@ -52,16 +112,28 @@ Rules:
 - Do NOT use write_file to change existing files — the user reviews your edits as SEARCH/REPLACE. write_file is only for files you explicitly want to overwrite wholesale (rare).
 - Paths are relative to the working directory. Don't use absolute paths.
 
+# Trust what you already know
+
+Before exploring the filesystem to answer a factual question, check whether the answer is already in context: the user's current message, earlier turns in this conversation (including prior tool results from \`remember\`), and the pinned memory blocks at the top of this prompt. When the user has stated a fact or you have remembered one, it outranks what the files say — don't re-derive from code what the user already told you. Explore when you genuinely don't know.
+
 # Exploration
 
-- Avoid listing or reading inside these common dependency / build directories unless the user explicitly asks about them: node_modules, dist, build, out, .next, .nuxt, .svelte-kit, .git, .venv, venv, __pycache__, target, coverage, .turbo, .cache. They're expensive and usually irrelevant.
-- Prefer search_files / grep over list_directory when you know roughly what you're looking for — it saves context and avoids enumerating huge trees.
+- Skip dependency, build, and VCS directories unless the user explicitly asks. The pinned .gitignore block (if any, below) is your authoritative denylist.
+- Prefer \`search_files\` over \`list_directory\` when you know roughly what you're looking for — it saves context and avoids enumerating huge trees. Note: \`search_files\` matches file NAMES; for searching file CONTENTS use \`search_content\`.
+- Available exploration tools: \`read_file\`, \`list_directory\`, \`directory_tree\`, \`search_files\` (filename match), \`search_content\` (content grep — use for "where is X called", "find all references to Y"), \`get_file_info\`. Don't call \`grep\` or other tools that aren't in this list — they don't exist as functions.
+
+# Path conventions
+
+Two different rules depending on which tool:
+
+- **Filesystem tools** (\`read_file\`, \`list_directory\`, \`search_files\`, \`edit_file\`, etc.): paths are sandbox-relative. \`/\` means the project root, \`/src/foo.ts\` means \`<project>/src/foo.ts\`. Both relative (\`src/foo.ts\`) and POSIX-absolute (\`/src/foo.ts\`) forms work.
+- **\`run_command\`**: the command runs in a real OS shell with cwd pinned to the project root. Paths inside the shell command are interpreted by THAT shell, not by us. **Never use leading \`/\` in run_command arguments** — Windows treats \`/tests\` as drive-root \`F:\\tests\` (non-existent), POSIX shells treat it as filesystem root. Use plain relative paths (\`tests\`, \`./tests\`, \`src/loop.ts\`) instead.
 
 # Style
 
 - Show edits; don't narrate them in prose. "Here's the fix:" is enough.
 - One short paragraph explaining *why*, then the blocks.
-- If you need to explore first (list / grep / read), do it with tool calls before writing any prose — silence while exploring is fine.
+- If you need to explore first (list / read / search), do it with tool calls before writing any prose — silence while exploring is fine.
 `;
 
 /**
@@ -70,23 +142,25 @@ Rules:
  * the file — we hand it to the model as-is. Truncate long ones so we
  * don't eat context budget on huge generated ignore lists.
  *
- * Missing or unreadable .gitignore → returns the base prompt unchanged.
+ * Stacking order (stable for cache prefix):
+ *   base prompt → REASONIX.md → global MEMORY.md → project MEMORY.md → .gitignore
  */
 export function codeSystemPrompt(rootDir: string): string {
+  const withMemory = applyMemoryStack(CODE_SYSTEM_PROMPT, rootDir);
   const gitignorePath = join(rootDir, ".gitignore");
-  if (!existsSync(gitignorePath)) return CODE_SYSTEM_PROMPT;
+  if (!existsSync(gitignorePath)) return withMemory;
   let content: string;
   try {
     content = readFileSync(gitignorePath, "utf8");
   } catch {
-    return CODE_SYSTEM_PROMPT;
+    return withMemory;
   }
   const MAX = 2000;
   const truncated =
     content.length > MAX
       ? `${content.slice(0, MAX)}\n… (truncated ${content.length - MAX} chars)`
       : content;
-  return `${CODE_SYSTEM_PROMPT}
+  return `${withMemory}
 
 # Project .gitignore
 

src/config.ts

@@ -44,6 +44,23 @@ export interface ReasonixConfig {
   session?: string | null;
   /** Marks that `reasonix setup` has completed at least once. */
   setupCompleted?: boolean;
+  /**
+   * Whether `web_search` + `web_fetch` tools are registered. Default:
+   * enabled (no key required — backed by DuckDuckGo's public HTML
+   * endpoint). Set to `false` to keep the session offline.
+   */
+  search?: boolean;
+  /**
+   * Per-project state keyed by absolute directory path. Written by the
+   * "always allow" choice on a shell confirmation prompt; merged into
+   * `registerShellTools({ extraAllowed })` when `reasonix code` runs
+   * against that directory again.
+   */
+  projects?: {
+    [absoluteRootDir: string]: {
+      shellAllowed?: string[];
+    };
+  };
 }
 
 export function defaultConfigPath(): string {
@@ -78,12 +95,57 @@ export function loadApiKey(path: string = defaultConfigPath()): string | undefin
   return readConfig(path).apiKey;
 }
 
+/**
+ * Resolve whether web-search tools should be registered. Default: on.
+ * Env `REASONIX_SEARCH=off` or config `search: false` turns it off.
+ * Any other value falls through to enabled.
+ */
+export function searchEnabled(path: string = defaultConfigPath()): boolean {
+  const env = process.env.REASONIX_SEARCH;
+  if (env === "off" || env === "false" || env === "0") return false;
+  const cfg = readConfig(path).search;
+  if (cfg === false) return false;
+  return true;
+}
+
 export function saveApiKey(key: string, path: string = defaultConfigPath()): void {
   const cfg = readConfig(path);
   cfg.apiKey = key.trim();
   writeConfig(cfg, path);
 }
 
+/**
+ * Read the persisted "always allow" shell-command prefixes for a
+ * given project root. Returns an empty array when nothing's stored.
+ */
+export function loadProjectShellAllowed(
+  rootDir: string,
+  path: string = defaultConfigPath(),
+): string[] {
+  const cfg = readConfig(path);
+  return cfg.projects?.[rootDir]?.shellAllowed ?? [];
+}
+
+/**
+ * Append a prefix to the project's shell-allowed list, dedup and
+ * persist. No-op if the prefix is empty/whitespace or already stored.
+ */
+export function addProjectShellAllowed(
+  rootDir: string,
+  prefix: string,
+  path: string = defaultConfigPath(),
+): void {
+  const trimmed = prefix.trim();
+  if (!trimmed) return;
+  const cfg = readConfig(path);
+  if (!cfg.projects) cfg.projects = {};
+  if (!cfg.projects[rootDir]) cfg.projects[rootDir] = {};
+  const existing = cfg.projects[rootDir].shellAllowed ?? [];
+  if (existing.includes(trimmed)) return;
+  cfg.projects[rootDir].shellAllowed = [...existing, trimmed];
+  writeConfig(cfg, path);
+}
+
 export function isPlausibleKey(key: string): boolean {
   const trimmed = key.trim();
   return /^sk-[A-Za-z0-9_-]{16,}$/.test(trimmed);

src/hooks.ts

@@ -0,0 +1,404 @@
+/**
+ * Hooks — user-defined automation that fires at well-known points in
+ * the agent loop. Mirrors the two-scope layout we use for memory and
+ * skills:
+ *
+ *   - `<project>/.reasonix/settings.json` — committable per-project
+ *   - `~/.reasonix/settings.json`         — every session
+ *
+ * A hook is a shell command. We invoke it with stdin = a JSON
+ * payload describing the event, and interpret the exit code:
+ *
+ *   - `0` — pass; loop continues normally
+ *   - `2` — block; for `PreToolUse` / `UserPromptSubmit` the
+ *     loop refuses to continue with that step and surfaces the
+ *     hook's stderr as the reason. For `PostToolUse` / `Stop` block
+ *     is meaningless (the action already happened) — treat as warn.
+ *   - anything else — warn; loop continues but stderr is rendered
+ *     to the user as an inline notice.
+ *
+ * stdin JSON shape (one envelope per event):
+ *
+ *   {
+ *     "event":    "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop",
+ *     "cwd":      "<absolute project root or process.cwd()>",
+ *     "toolName": "<string>",   // tool events only
+ *     "toolArgs": <unknown>,    // tool events only — already JSON-decoded
+ *     "toolResult": "<string>", // PostToolUse only — same body the model sees
+ *     "prompt":   "<string>",   // UserPromptSubmit only
+ *     "lastAssistantText": "<string>", // Stop only
+ *     "turn":     <number>,     // Stop only
+ *   }
+ *
+ * Hooks are executed in order: project scope first, then global.
+ * `Pre*` events stop dispatching at the first block; non-block
+ * outcomes accumulate into a single report so the UI can render
+ * each warning inline.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop";
+
+/** All four events as a const array — drives slash listing + validation. */
+export const HOOK_EVENTS: readonly HookEvent[] = [
+  "PreToolUse",
+  "PostToolUse",
+  "UserPromptSubmit",
+  "Stop",
+] as const;
+
+/** Only the gating events can block the loop. */
+const BLOCKING_EVENTS: ReadonlySet<HookEvent> = new Set(["PreToolUse", "UserPromptSubmit"]);
+
+/** Per-event default timeout. Tool/prompt hooks gate progress, so they're tight. */
+const DEFAULT_TIMEOUTS_MS: Record<HookEvent, number> = {
+  PreToolUse: 5_000,
+  UserPromptSubmit: 5_000,
+  PostToolUse: 30_000,
+  Stop: 30_000,
+};
+
+export type HookScope = "project" | "global";
+
+export interface HookConfig {
+  /**
+   * Tool-name pattern (PreToolUse / PostToolUse only). Anchored regex.
+   * Omitted or `"*"` matches every tool. Ignored for prompt / Stop
+   * events (they have no tool name to match against).
+   */
+  match?: string;
+  /** Shell command to run. Spawned through the platform shell. */
+  command: string;
+  /** Optional human description — surfaced in `/hooks`. */
+  description?: string;
+  /** Per-hook timeout override in ms. */
+  timeout?: number;
+  /**
+   * Working directory for the spawned process. Defaults to:
+   *   - project scope → the project root
+   *   - global scope  → process.cwd()
+   */
+  cwd?: string;
+}
+
+/** Shape of `<scope>/.reasonix/settings.json` — only `hooks` for now. */
+export interface HookSettings {
+  hooks?: Partial<Record<HookEvent, HookConfig[]>>;
+}
+
+/** A loaded hook with its origin scope baked in (used for ordering and `/hooks`). */
+export interface ResolvedHook extends HookConfig {
+  event: HookEvent;
+  scope: HookScope;
+  /** Absolute path to the settings.json the hook came from. */
+  source: string;
+}
+
+/** Outcome of a single hook invocation. */
+export interface HookOutcome {
+  /** Which hook fired. */
+  hook: ResolvedHook;
+  /**
+   * Decision:
+   *   - `pass`    — exit 0
+   *   - `block`   — exit 2 on a blocking event (otherwise downgraded to `warn`)
+   *   - `warn`    — non-zero exit that is not a successful block
+   *   - `timeout` — the spawn was killed past `timeout`
+   *   - `error`   — could not spawn at all (missing command, etc.)
+   */
+  decision: "pass" | "block" | "warn" | "timeout" | "error";
+  exitCode: number | null;
+  /** Captured stdout (trimmed). May be empty. */
+  stdout: string;
+  /** Captured stderr (trimmed). The block / warn message comes from here. */
+  stderr: string;
+  durationMs: number;
+}
+
+/** Aggregate report for `runHooks`. */
+export interface HookReport {
+  event: HookEvent;
+  outcomes: HookOutcome[];
+  /** True iff at least one outcome was a `block` — only meaningful for blocking events. */
+  blocked: boolean;
+}
+
+export const HOOK_SETTINGS_FILENAME = "settings.json";
+export const HOOK_SETTINGS_DIRNAME = ".reasonix";
+
+/** Where the global settings.json lives. Equivalent to `~/.reasonix/settings.json`. */
+export function globalSettingsPath(homeDirOverride?: string): string {
+  return join(homeDirOverride ?? homedir(), HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME);
+}
+
+/** Where the project settings.json lives for a given root. */
+export function projectSettingsPath(projectRoot: string): string {
+  return join(projectRoot, HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME);
+}
+
+function readSettingsFile(path: string): HookSettings | null {
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as HookSettings;
+  } catch {
+    /* malformed JSON → treat as no hooks; do NOT throw, the user
+     * shouldn't lose the whole CLI to a typo in their settings */
+  }
+  return null;
+}
+
+/**
+ * Pull every configured hook out of the project + global settings
+ * files, in the order they should fire (project first, global second,
+ * within each scope: array order from the file).
+ *
+ * Returns a flat list — the dispatcher filters by event + match
+ * pattern at run time. Loading is cheap (one or two JSON files), so
+ * we don't memoize across processes; re-load is allowed via
+ * `/hooks reload` and on every fresh App mount.
+ */
+export interface LoadHookSettingsOptions {
+  /** Absolute project root, if any. Without it, only global hooks load. */
+  projectRoot?: string;
+  /** Override `~` for tests. */
+  homeDir?: string;
+}
+
+export function loadHooks(opts: LoadHookSettingsOptions = {}): ResolvedHook[] {
+  const out: ResolvedHook[] = [];
+  if (opts.projectRoot) {
+    const projPath = projectSettingsPath(opts.projectRoot);
+    const settings = readSettingsFile(projPath);
+    if (settings) appendResolved(out, settings, "project", projPath);
+  }
+  const globalPath = globalSettingsPath(opts.homeDir);
+  const settings = readSettingsFile(globalPath);
+  if (settings) appendResolved(out, settings, "global", globalPath);
+  return out;
+}
+
+function appendResolved(
+  out: ResolvedHook[],
+  settings: HookSettings,
+  scope: HookScope,
+  source: string,
+): void {
+  if (!settings.hooks) return;
+  for (const event of HOOK_EVENTS) {
+    const list = settings.hooks[event];
+    if (!Array.isArray(list)) continue;
+    for (const cfg of list) {
+      if (!cfg || typeof cfg.command !== "string" || cfg.command.trim() === "") continue;
+      out.push({ ...cfg, event, scope, source });
+    }
+  }
+}
+
+/**
+ * True if `toolName` matches the hook's `match` field. `"*"` and
+ * undefined match everything. Otherwise we anchor the field as a
+ * regex — partial-name matches don't fire, so `"file"` would not
+ * trigger on `read_file` (use `".*file"` for that).
+ */
+export function matchesTool(hook: ResolvedHook, toolName: string): boolean {
+  if (hook.event !== "PreToolUse" && hook.event !== "PostToolUse") return true;
+  const m = hook.match;
+  if (!m || m === "*") return true;
+  try {
+    const re = new RegExp(`^(?:${m})$`);
+    return re.test(toolName);
+  } catch {
+    /* malformed regex → don't fire (safer than firing on every tool) */
+    return false;
+  }
+}
+
+/** Payload envelope passed to hook stdin. */
+export interface HookPayload {
+  event: HookEvent;
+  cwd: string;
+  toolName?: string;
+  toolArgs?: unknown;
+  toolResult?: string;
+  prompt?: string;
+  lastAssistantText?: string;
+  turn?: number;
+}
+
+/** Test seam — same shape as Node's spawn but returns a Promise of the raw outcome bits. */
+export interface HookSpawnInput {
+  command: string;
+  cwd: string;
+  stdin: string;
+  timeoutMs: number;
+}
+
+export interface HookSpawnResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  /** True iff spawn() itself failed (ENOENT, EACCES, …). */
+  spawnError?: Error;
+}
+
+export type HookSpawner = (input: HookSpawnInput) => Promise<HookSpawnResult>;
+
+/**
+ * Default spawner — runs `command` through the platform shell so
+ * `&&`, pipes, env-var expansion all work without a tokenizer.
+ * Stdin is the JSON payload, stdout / stderr are buffered.
+ *
+ * Why `shell: true`? A hook is intentionally a shell command — that's
+ * the contract. Treating it like an argv array would surprise users
+ * who write `bun run check && eslint .` and expect it to behave the
+ * way it does in their terminal.
+ */
+function defaultSpawner(input: HookSpawnInput): Promise<HookSpawnResult> {
+  return new Promise<HookSpawnResult>((resolve) => {
+    const child = spawn(input.command, {
+      cwd: input.cwd,
+      shell: true,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      // SIGTERM may not land on Windows for shell children — followed
+      // by a hard kill a moment later if the process is still around.
+      setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          /* already gone */
+        }
+      }, 500);
+    }, input.timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.once("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: null,
+        stdout,
+        stderr,
+        timedOut: false,
+        spawnError: err,
+      });
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: code,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        timedOut,
+      });
+    });
+
+    try {
+      child.stdin.write(input.stdin);
+      child.stdin.end();
+    } catch {
+      /* stdin write can race with spawn errors; the close handler
+       * still fires with exit 0/null */
+    }
+  });
+}
+
+/**
+ * Format a hook outcome as a single-line UI string. Used by both the
+ * loop (for `warning` events) and the App (for UserPromptSubmit /
+ * Stop outcomes). Centralizing keeps the language consistent across
+ * scopes.
+ */
+export function formatHookOutcomeMessage(outcome: HookOutcome): string {
+  if (outcome.decision === "pass") return "";
+  const detail = (outcome.stderr || outcome.stdout || "").trim();
+  const tag = `${outcome.hook.scope}/${outcome.hook.event}`;
+  const cmd =
+    outcome.hook.command.length > 60
+      ? `${outcome.hook.command.slice(0, 60)}…`
+      : outcome.hook.command;
+  const head = `hook ${tag} \`${cmd}\` ${outcome.decision}`;
+  return detail ? `${head}: ${detail}` : head;
+}
+
+/**
+ * Decide the hook's outcome decision from raw spawn results.
+ * Pulled out as a pure function so tests can pin the matrix.
+ */
+export function decideOutcome(
+  event: HookEvent,
+  raw: HookSpawnResult,
+): "pass" | "block" | "warn" | "timeout" | "error" {
+  if (raw.spawnError) return "error";
+  if (raw.timedOut) return BLOCKING_EVENTS.has(event) ? "block" : "warn";
+  if (raw.exitCode === 0) return "pass";
+  if (raw.exitCode === 2 && BLOCKING_EVENTS.has(event)) return "block";
+  return "warn";
+}
+
+export interface RunHooksOptions {
+  payload: HookPayload;
+  hooks: ResolvedHook[];
+  /** Test seam — defaults to a real `spawn`. */
+  spawner?: HookSpawner;
+}
+
+/**
+ * Filter hooks down to the ones that match `payload.event` (and
+ * `payload.toolName`, for tool events), then run them in order.
+ * Stops at the first `block` outcome on a blocking event so a
+ * gating hook can prevent later hooks from incorrectly seeing a
+ * success that wasn't going to happen.
+ */
+export async function runHooks(opts: RunHooksOptions): Promise<HookReport> {
+  const spawner = opts.spawner ?? defaultSpawner;
+  const event = opts.payload.event;
+  const toolName = opts.payload.toolName ?? "";
+  const matching = opts.hooks.filter((h) => h.event === event && matchesTool(h, toolName));
+
+  const outcomes: HookOutcome[] = [];
+  let blocked = false;
+  const stdin = `${JSON.stringify(opts.payload)}\n`;
+
+  for (const hook of matching) {
+    const start = Date.now();
+    const timeoutMs = hook.timeout ?? DEFAULT_TIMEOUTS_MS[event];
+    const cwd = hook.cwd ?? opts.payload.cwd;
+    const raw = await spawner({ command: hook.command, cwd, stdin, timeoutMs });
+    const decision = decideOutcome(event, raw);
+    outcomes.push({
+      hook,
+      decision,
+      exitCode: raw.exitCode,
+      stdout: raw.stdout,
+      stderr:
+        raw.stderr ||
+        (raw.spawnError ? raw.spawnError.message : "") ||
+        (raw.timedOut ? `hook timed out after ${timeoutMs}ms` : ""),
+      durationMs: Date.now() - start,
+    });
+    if (decision === "block") {
+      blocked = true;
+      break;
+    }
+  }
+
+  return { event, outcomes, blocked };
+}

src/index.ts

@@ -6,9 +6,30 @@ export type { ChatResponse, StreamChunk, DeepSeekClientOptions } from "./client.
 export {
   CacheFirstLoop,
   formatLoopError,
+  fixToolCallPairing,
   healLoadedMessages,
+  healLoadedMessagesByTokens,
   stripHallucinatedToolMarkup,
 } from "./loop.js";
+export {
+  AT_MENTION_PATTERN,
+  AT_PICKER_PREFIX,
+  DEFAULT_AT_MENTION_MAX_BYTES,
+  DEFAULT_PICKER_IGNORE_DIRS,
+  detectAtPicker,
+  expandAtMentions,
+  listFilesSync,
+  listFilesWithStatsSync,
+  rankPickerCandidates,
+} from "./at-mentions.js";
+export type {
+  AtMentionExpansion,
+  AtMentionOptions,
+  FileWithStats,
+  ListFilesOptions,
+  PickerCandidate,
+  RankPickerOptions,
+} from "./at-mentions.js";
 export type {
   CacheFirstLoopOptions,
   LoopEvent,
@@ -29,10 +50,77 @@ export type {
 export { ImmutablePrefix, AppendOnlyLog, VolatileScratch } from "./memory.js";
 export type { ImmutablePrefixOptions } from "./memory.js";
 
+export {
+  PROJECT_MEMORY_FILE,
+  PROJECT_MEMORY_MAX_CHARS,
+  applyProjectMemory,
+  memoryEnabled,
+  readProjectMemory,
+} from "./project-memory.js";
+export type { ProjectMemory } from "./project-memory.js";
+
+export {
+  MEMORY_INDEX_FILE,
+  MEMORY_INDEX_MAX_CHARS,
+  MemoryStore,
+  USER_MEMORY_DIR,
+  applyMemoryStack,
+  applyUserMemory,
+  projectHash,
+  sanitizeMemoryName,
+} from "./user-memory.js";
+export type {
+  MemoryEntry,
+  MemoryScope,
+  MemoryStoreOptions,
+  MemoryType,
+  WriteInput as MemoryWriteInput,
+} from "./user-memory.js";
+
 export { ToolRegistry } from "./tools.js";
 export type { ToolDefinition, ToolCallContext } from "./tools.js";
 export { registerFilesystemTools } from "./tools/filesystem.js";
 export type { FilesystemToolsOptions } from "./tools/filesystem.js";
+export { registerMemoryTools } from "./tools/memory.js";
+export type { MemoryToolsOptions } from "./tools/memory.js";
+export { PlanProposedError, registerPlanTool } from "./tools/plan.js";
+export type { PlanToolOptions } from "./tools/plan.js";
+export { forkRegistryExcluding, registerSubagentTool } from "./tools/subagent.js";
+export type {
+  SubagentEvent,
+  SubagentSink,
+  SubagentToolOptions,
+} from "./tools/subagent.js";
+export {
+  NeedsConfirmationError,
+  detectShellOperator,
+  formatCommandResult,
+  injectPowerShellUtf8,
+  isAllowed,
+  prepareSpawn,
+  quoteForCmdExe,
+  registerShellTools,
+  resolveExecutable,
+  runCommand,
+  tokenizeCommand,
+  withUtf8Codepage,
+} from "./tools/shell.js";
+export type { RunCommandResult, ShellToolsOptions } from "./tools/shell.js";
+export {
+  formatSearchResults,
+  htmlToText,
+  parseMojeekResults,
+  registerWebTools,
+  webFetch,
+  webSearch,
+} from "./tools/web.js";
+export type {
+  PageContent,
+  SearchResult,
+  WebFetchOptions,
+  WebSearchOptions,
+  WebToolsOptions,
+} from "./tools/web.js";
 
 export {
   SessionStats,
@@ -107,9 +195,11 @@ export { SseTransport } from "./mcp/sse.js";
 export type { SseTransportOptions } from "./mcp/sse.js";
 export {
   DEFAULT_MAX_RESULT_CHARS,
+  DEFAULT_MAX_RESULT_TOKENS,
   bridgeMcpTools,
   flattenMcpResult,
   truncateForModel,
+  truncateForModelByTokens,
 } from "./mcp/registry.js";
 export type { BridgeOptions, BridgeResult, FlattenOptions } from "./mcp/registry.js";
 export { parseMcpSpec } from "./mcp/spec.js";
@@ -186,4 +276,56 @@ export type {
   JSONSchema,
 } from "./types.js";
 
-export const VERSION = "0.4.14";
+export {
+  LATEST_CACHE_TTL_MS,
+  LATEST_FETCH_TIMEOUT_MS,
+  VERSION,
+  compareVersions,
+  getLatestVersion,
+  isNpxInstall,
+} from "./version.js";
+export type { GetLatestVersionOptions } from "./version.js";
+
+export {
+  HOOK_EVENTS,
+  HOOK_SETTINGS_DIRNAME,
+  HOOK_SETTINGS_FILENAME,
+  decideOutcome,
+  formatHookOutcomeMessage,
+  globalSettingsPath,
+  loadHooks,
+  matchesTool,
+  projectSettingsPath,
+  runHooks,
+} from "./hooks.js";
+export {
+  aggregateUsage,
+  appendUsage,
+  bucketCacheHitRatio,
+  bucketSavingsFraction,
+  defaultUsageLogPath,
+  formatLogSize,
+  readUsageLog,
+} from "./usage.js";
+export type {
+  AggregateOptions,
+  AppendUsageInput,
+  UsageAggregate,
+  UsageBucket,
+  UsageRecord,
+} from "./usage.js";
+export type {
+  HookConfig,
+  HookEvent,
+  HookOutcome,
+  HookPayload,
+  HookReport,
+  HookScope,
+  HookSettings,
+  HookSpawner,
+  HookSpawnInput,
+  HookSpawnResult,
+  LoadHookSettingsOptions,
+  ResolvedHook,
+  RunHooksOptions,
+} from "./hooks.js";

src/loop.ts

@@ -6,7 +6,19 @@ import {
   runBranches,
 } from "./consistency.js";
 import { type HarvestOptions, type TypedPlanState, emptyPlanState, harvest } from "./harvest.js";
-import { DEFAULT_MAX_RESULT_CHARS, truncateForModel } from "./mcp/registry.js";
+import {
+  type HookOutcome,
+  type HookPayload,
+  type ResolvedHook,
+  formatHookOutcomeMessage,
+  runHooks,
+} from "./hooks.js";
+import {
+  DEFAULT_MAX_RESULT_CHARS,
+  DEFAULT_MAX_RESULT_TOKENS,
+  truncateForModel,
+  truncateForModelByTokens,
+} from "./mcp/registry.js";
 import { AppendOnlyLog, type ImmutablePrefix, VolatileScratch } from "./memory.js";
 import { type RepairReport, ToolCallRepair } from "./repair/index.js";
 import { appendSessionMessage, loadSessionMessages, rewriteSession } from "./session.js";
@@ -16,6 +28,7 @@ import {
   SessionStats,
   type TurnStats,
 } from "./telemetry.js";
+import { countTokens, estimateRequestTokens } from "./tokenizer.js";
 import { ToolRegistry } from "./tools.js";
 import type { ChatMessage, ToolCall } from "./types.js";
 
@@ -127,6 +140,21 @@ export interface CacheFirstLoopOptions {
    * `~/.reasonix/sessions/<name>.jsonl` so the next run can resume.
    */
   session?: string;
+  /**
+   * Resolved hook list — loaded from `<project>/.reasonix/settings.json`
+   * + `~/.reasonix/settings.json` by the CLI before constructing the loop.
+   * The loop dispatches `PreToolUse` and `PostToolUse` events itself; the
+   * CLI handles `UserPromptSubmit` and `Stop` since they live at the App
+   * boundary. Empty / unset → no hooks fire (the runtime cost of an empty
+   * filter is one ms). See `src/hooks.ts` for the full contract.
+   */
+  hooks?: ResolvedHook[];
+  /**
+   * `cwd` reported to hooks via the stdin payload. Defaults to `process.cwd()`.
+   * `reasonix code` overrides this to the sandbox root so a hook that does
+   * `cd $REASONIX_CWD` lands in the project, not in the user's shell home.
+   */
+  hookCwd?: string;
 }
 
 /**
@@ -165,6 +193,15 @@ export class CacheFirstLoop {
   branchOptions: BranchOptions;
   sessionName: string | null;
 
+  /**
+   * Hook list, mutable so `/hooks reload` can swap it without
+   * reconstructing the loop. Default empty — the filter cost on a
+   * tool call is one array length check.
+   */
+  hooks: ResolvedHook[];
+  /** `cwd` reported to hook stdin. Resolved once at construction. */
+  readonly hookCwd: string;
+
   /** Number of messages that were pre-loaded from the session file. */
   readonly resumedMessageCount: number;
 
@@ -194,6 +231,8 @@ export class CacheFirstLoop {
     // the decision, keep the iter cap as a last-resort backstop for
     // the case where something spins without growing the prompt.
     this.maxToolIters = opts.maxToolIters ?? 64;
+    this.hooks = opts.hooks ?? [];
+    this.hookCwd = opts.hookCwd ?? process.cwd();
 
     // Resolve branch config first (since it forces harvest on).
     if (typeof opts.branch === "number") {
@@ -234,9 +273,9 @@ export class CacheFirstLoop {
     this.sessionName = opts.session ?? null;
     if (this.sessionName) {
       const prior = loadSessionMessages(this.sessionName);
-      const { messages, healedCount, healedFrom } = healLoadedMessages(
+      const { messages, healedCount, tokensSaved } = healLoadedMessagesByTokens(
         prior,
-        DEFAULT_MAX_RESULT_CHARS,
+        DEFAULT_MAX_RESULT_TOKENS,
       );
       for (const msg of messages) this.log.append(msg);
       this.resumedMessageCount = messages.length;
@@ -252,7 +291,7 @@ export class CacheFirstLoop {
           /* disk full / perms — skip, in-memory heal still applies */
         }
         process.stderr.write(
-          `▸ session "${this.sessionName}": healed ${healedCount} entr${healedCount === 1 ? "y" : "ies"}${healedFrom > 0 ? ` (was ${healedFrom.toLocaleString()} chars oversized)` : " (dropped dangling tool_calls tail)"}. Rewrote session file.\n`,
+          `▸ session "${this.sessionName}": healed ${healedCount} entr${healedCount === 1 ? "y" : "ies"}${tokensSaved > 0 ? ` (shrunk ${tokensSaved.toLocaleString()} tokens of oversized tool output)` : " (dropped dangling tool_calls tail)"}. Rewrote session file.\n`,
         );
       }
     } else {
@@ -262,28 +301,36 @@ export class CacheFirstLoop {
 
   /**
    * Shrink the log by re-truncating oversized tool results to a tighter
-   * cap, and persist the result back to disk so the next launch doesn't
-   * re-inherit a fat session file. Returns a summary the TUI can
-   * display.
+   * token cap, and persist the result back to disk so the next launch
+   * doesn't re-inherit a fat session file. Returns a summary the TUI
+   * can display.
+   *
+   * The cap is in DeepSeek V3 tokens (not chars) — so CJK text gets
+   * capped at the same effective context footprint as English instead
+   * of slipping past a char cap at 2× the token cost. Default 4000
+   * tokens, matching the token-aware dispatch cap from 0.5.2.
    *
    * Only tool-role messages are touched (same rationale as
    * {@link healLoadedMessages}). User and assistant messages carry
    * authored intent we can't mechanically shrink without losing
    * meaning.
    */
-  compact(tightCapChars = 4000): { healedCount: number; charsSaved: number } {
+  compact(maxTokens = 4000): {
+    healedCount: number;
+    tokensSaved: number;
+    charsSaved: number;
+  } {
     const before = this.log.toMessages();
-    // Use `shrinkOversizedToolResults` (not `healLoadedMessages`) — the
-    // full heal would also strip a dangling `assistant.tool_calls` tail,
-    // which during an active turn is legitimate state we still need
-    // (tools haven't been dispatched yet). Structural healing is only
-    // appropriate at session LOAD; mid-session `/compact` is strictly
-    // about shrinking oversized tool payloads.
-    const { messages, healedCount, healedFrom } = shrinkOversizedToolResults(before, tightCapChars);
-    const afterBytes = messages
-      .filter((m) => m.role === "tool")
-      .reduce((s, m) => s + (typeof m.content === "string" ? m.content.length : 0), 0);
-    const charsSaved = healedFrom - afterBytes;
+    // Use `shrinkOversizedToolResultsByTokens` (not `healLoadedMessages`)
+    // — the full heal would also strip a dangling `assistant.tool_calls`
+    // tail, which during an active turn is legitimate state we still
+    // need (tools haven't been dispatched yet). Structural healing is
+    // only appropriate at session LOAD; mid-session `/compact` is
+    // strictly about shrinking oversized tool payloads.
+    const { messages, healedCount, tokensSaved, charsSaved } = shrinkOversizedToolResultsByTokens(
+      before,
+      maxTokens,
+    );
     if (healedCount > 0) {
       this.log.compactInPlace(messages);
       if (this.sessionName) {
@@ -294,10 +341,10 @@ export class CacheFirstLoop {
         }
       }
     }
-    return { healedCount, charsSaved };
+    return { healedCount, tokensSaved, charsSaved };
   }
 
-  private appendAndPersist(message: ChatMessage): void {
+  appendAndPersist(message: ChatMessage): void {
     this.log.append(message);
     if (this.sessionName) {
       try {
@@ -438,6 +485,11 @@ export class CacheFirstLoop {
   async *step(userInput: string): AsyncGenerator<LoopEvent> {
     this._turn++;
     this.scratch.reset();
+    // A fresh user turn is a new intent — don't let StormBreaker's
+    // old sliding window of (name, args) signatures keep blocking
+    // calls that are now legitimately on-task. The window repopulates
+    // naturally as this turn's tool calls flow through.
+    this.repair.resetStorm();
     // Fresh controller for this turn: the prior step's signal has
     // already fired (or stayed clean); either way we don't want its
     // state to bleed into the new turn.
@@ -473,7 +525,12 @@ export class CacheFirstLoop {
         };
         const stoppedMsg =
           "[aborted by user (Esc) — no summary produced. Ask again or /retry when ready; prior tool output is still in the log.]";
-        this.appendAndPersist({ role: "assistant", content: stoppedMsg });
+        // Synthetic assistant turn — no real model output exists. For
+        // reasoner sessions R1 still demands `reasoning_content` on
+        // every assistant message, so we attach an empty-string
+        // placeholder to satisfy the validator without inventing
+        // reasoning we don't have. V3 gets a plain message as before.
+        this.appendAndPersist(this.syntheticAssistantMessage(stoppedMsg));
         yield {
           turn: this._turn,
           role: "assistant_final",
@@ -510,7 +567,43 @@ export class CacheFirstLoop {
           content: `${iter}/${this.maxToolIters} tool calls used — approaching budget. Press Esc to force a summary now.`,
         };
       }
-      const messages = this.buildMessages(pendingUser);
+      let messages = this.buildMessages(pendingUser);
+
+      // Preflight context check. Reactive auto-compact at 60%/80%
+      // keys off the PREVIOUS turn's server-reported prompt_tokens,
+      // so a single new oversized tool result (or a fresh resumed
+      // session) can push this turn's request straight past 131,072
+      // tokens before we ever see a usage number — DeepSeek 400s with
+      // "maximum context length". Here we estimate the outgoing
+      // payload locally and compact preemptively when it's in the red
+      // zone (>95% of the model's context window). One cheap
+      // tokenize-pass per iter, only on our side.
+      {
+        const ctxMax = DEEPSEEK_CONTEXT_TOKENS[this.model] ?? DEFAULT_CONTEXT_TOKENS;
+        const estimate = estimateRequestTokens(messages, this.prefix.toolSpecs);
+        if (estimate / ctxMax > 0.95) {
+          const result = this.compact(1_000);
+          if (result.healedCount > 0) {
+            yield {
+              turn: this._turn,
+              role: "warning",
+              content: `preflight: request ~${estimate.toLocaleString()}/${ctxMax.toLocaleString()} tokens (${Math.round(
+                (estimate / ctxMax) * 100,
+              )}%) — pre-compacted ${result.healedCount} tool result(s), saved ${result.tokensSaved.toLocaleString()} tokens. Sending.`,
+            };
+            // Rebuild with the compacted log so we send the smaller payload.
+            messages = this.buildMessages(pendingUser);
+          } else {
+            yield {
+              turn: this._turn,
+              role: "warning",
+              content: `preflight: request ~${estimate.toLocaleString()}/${ctxMax.toLocaleString()} tokens (${Math.round(
+                (estimate / ctxMax) * 100,
+              )}%) and nothing to auto-compact — DeepSeek will likely 400. Run /forget or /clear to start fresh.`,
+            };
+          }
+        }
+      }
 
       let assistantContent = "";
       let reasoningContent = "";
@@ -674,6 +767,20 @@ export class CacheFirstLoop {
           usage = resp.usage;
         }
       } catch (err) {
+        // An aborted signal here is almost always our own doing —
+        // either Esc, or App.tsx calling `loop.abort()` to switch to a
+        // queued synthetic input (ShellConfirm "always allow", PlanConfirm
+        // approve, etc.). The DeepSeek client's fetch path translates
+        // the abort into a generic `AbortError("This operation was
+        // aborted")`, which used to bubble up here and render as a
+        // scary red "error" row even though nothing actually broke.
+        // Treat it as a clean early-exit instead: the next turn (queued
+        // synthetic OR user re-prompt) starts immediately and gets to
+        // produce its own answer.
+        if (signal.aborted) {
+          yield { turn: this._turn, role: "done", content: "" };
+          return;
+        }
         yield {
           turn: this._turn,
           role: "error",
@@ -719,7 +826,9 @@ export class CacheFirstLoop {
         assistantContent || null,
       );
 
-      this.appendAndPersist(this.assistantMessage(assistantContent, repairedCalls));
+      this.appendAndPersist(
+        this.assistantMessage(assistantContent, repairedCalls, reasoningContent),
+      );
 
       yield {
         turn: this._turn,
@@ -731,6 +840,25 @@ export class CacheFirstLoop {
         branch: branchSummary,
       };
 
+      // Loud signal when the storm breaker caught a repeat pattern.
+      // The `repair` field on assistant_final already carries the
+      // count as a subtext on the assistant row, but a dedicated
+      // warning row is far more noticeable — and critical when ALL
+      // calls were suppressed, because the turn then ends with no
+      // visible explanation of why nothing happened.
+      if (report.stormsBroken > 0) {
+        const noteTail = report.notes.length ? ` — ${report.notes[report.notes.length - 1]}` : "";
+        const allSuppressed = repairedCalls.length === 0 && toolCalls.length > 0;
+        const phrase = allSuppressed
+          ? `stopped the model from calling the same tool with identical args repeatedly (all ${toolCalls.length} call(s) this turn were already in the recent-repeat window). Likely a stuck retry — reword your instruction, rule out the underlying blocker, or try /retry after fixing it`
+          : `suppressed ${report.stormsBroken} repeat tool call(s) that had fired 3+ times with identical args in a sliding window`;
+        yield {
+          turn: this._turn,
+          role: "warning",
+          content: `${phrase}${noteTail}`,
+        };
+      }
+
       if (repairedCalls.length === 0) {
         yield { turn: this._turn, role: "done", content: assistantContent };
         return;
@@ -755,19 +883,38 @@ export class CacheFirstLoop {
       //      tool_calls"). The summary is about what was LEARNED so far,
       //      not what we intended to do next.
       const ctxMax = DEEPSEEK_CONTEXT_TOKENS[this.model] ?? DEFAULT_CONTEXT_TOKENS;
+      // Proactive tier: between 60% and 80%, pre-shrink oversized tool
+      // results to a moderate cap (4k tokens) so the next iter doesn't
+      // slam straight into the 80% reactive path — which shrinks far
+      // more aggressively (1k tokens) and risks losing useful tail
+      // info. This catches the slow-growth pattern (lots of medium
+      // reads) before it compounds.
+      if (usage) {
+        const ratio = usage.promptTokens / ctxMax;
+        if (ratio > 0.6 && ratio <= 0.8) {
+          const before = usage.promptTokens;
+          const soft = this.compact(4_000);
+          if (soft.healedCount > 0) {
+            const after = Math.max(0, before - soft.tokensSaved);
+            yield {
+              turn: this._turn,
+              role: "warning",
+              content: `context ${before.toLocaleString()}/${ctxMax.toLocaleString()} (${Math.round(
+                ratio * 100,
+              )}%) — proactively compacted ${soft.healedCount} tool result(s) to 4k tokens, saved ${soft.tokensSaved.toLocaleString()} tokens (now ~${after.toLocaleString()}). Staying ahead of the 80% guard.`,
+            };
+          }
+        }
+      }
       if (usage && usage.promptTokens / ctxMax > 0.8) {
         const before = usage.promptTokens;
-        const compactResult = this.compact(4000);
+        const compactResult = this.compact(1_000);
         if (compactResult.healedCount > 0) {
-          // Rough estimate: 4 chars per token. Good enough to decide
-          // whether compaction pushed us back under the threshold; the
-          // exact number comes back from the NEXT API response's usage.
-          const approxSaved = Math.round(compactResult.charsSaved / 4);
-          const after = before - approxSaved;
+          const after = Math.max(0, before - compactResult.tokensSaved);
           yield {
             turn: this._turn,
             role: "warning",
-            content: `context ${before.toLocaleString()}/${ctxMax.toLocaleString()} — auto-compacted ${compactResult.healedCount} oversized tool result(s), saved ~${approxSaved.toLocaleString()} tokens (now ~${after.toLocaleString()}). Continuing.`,
+            content: `context ${before.toLocaleString()}/${ctxMax.toLocaleString()} — auto-compacted ${compactResult.healedCount} oversized tool result(s), saved ${compactResult.tokensSaved.toLocaleString()} tokens (now ~${after.toLocaleString()}). Continuing.`,
           };
           // Intentionally don't re-check the threshold here: even if
           // compaction didn't fully clear us under 80%, one more tool
@@ -822,7 +969,55 @@ export class CacheFirstLoop {
           toolName: name,
           toolArgs: args,
         };
-        const result = await this.tools.dispatch(name, args, { signal });
+
+        // PreToolUse hooks. A `block` decision (exit 2) skips dispatch
+        // and surfaces the hook's stderr as the tool result so the model
+        // sees a structured refusal instead of a silent omission. Non-
+        // block non-zero outcomes are warnings: the loop continues, the
+        // UI gets a yellow row.
+        const parsedArgs = safeParseToolArgs(args);
+        const preReport = await runHooks({
+          hooks: this.hooks,
+          payload: {
+            event: "PreToolUse",
+            cwd: this.hookCwd,
+            toolName: name,
+            toolArgs: parsedArgs,
+          },
+        });
+        for (const w of hookWarnings(preReport.outcomes, this._turn)) yield w;
+
+        let result: string;
+        if (preReport.blocked) {
+          const blocking = preReport.outcomes[preReport.outcomes.length - 1];
+          const reason = (
+            blocking?.stderr ||
+            blocking?.stdout ||
+            "blocked by PreToolUse hook"
+          ).trim();
+          result = `[hook block] ${blocking?.hook.command ?? "<unknown>"}\n${reason}`;
+        } else {
+          result = await this.tools.dispatch(name, args, {
+            signal,
+            maxResultTokens: DEFAULT_MAX_RESULT_TOKENS,
+          });
+
+          // PostToolUse hooks — block is meaningless after the fact, so
+          // every non-pass outcome is a warning. Hooks here are the
+          // natural place for "after every edit, run the formatter."
+          const postReport = await runHooks({
+            hooks: this.hooks,
+            payload: {
+              event: "PostToolUse",
+              cwd: this.hookCwd,
+              toolName: name,
+              toolArgs: parsedArgs,
+              toolResult: result,
+            },
+          });
+          for (const w of hookWarnings(postReport.outcomes, this._turn)) yield w;
+        }
+
         this.appendAndPersist({
           role: "tool",
           tool_call_id: call.id ?? "",
@@ -885,7 +1080,7 @@ export class CacheFirstLoop {
       const reasonPrefix = reasonPrefixFor(opts.reason, this.maxToolIters);
       const annotated = `${reasonPrefix}\n\n${summary}`;
       const summaryStats = this.stats.record(this._turn, this.model, resp.usage ?? new Usage());
-      this.appendAndPersist({ role: "assistant", content: summary });
+      this.appendAndPersist(this.assistantMessage(summary, [], resp.reasoningContent ?? undefined));
       yield {
         turn: this._turn,
         role: "assistant_final",
@@ -916,9 +1111,41 @@ export class CacheFirstLoop {
     return final;
   }
 
-  private assistantMessage(content: string, toolCalls: ToolCall[]): ChatMessage {
+  private assistantMessage(
+    content: string,
+    toolCalls: ToolCall[],
+    reasoningContent?: string,
+  ): ChatMessage {
     const msg: ChatMessage = { role: "assistant", content };
     if (toolCalls.length > 0) msg.tool_calls = toolCalls;
+    // DeepSeek's "thinking mode must be passed back" rule applies to
+    // ANY R1-generated assistant message, not just the ones with
+    // tool_calls. 0.5.15 mis-scoped this: if the loop produced a
+    // plain-text R1 turn (e.g. "plan submitted — awaiting approval")
+    // between a tool-call turn and the next user turn, its reasoning
+    // was stripped, and the following request 400'd with the same
+    // error we already thought we'd fixed. deepseek-chat never emits
+    // reasoning_content, so V3 requests stay untouched (the field
+    // simply isn't present).
+    if (reasoningContent && reasoningContent.length > 0) {
+      msg.reasoning_content = reasoningContent;
+    }
+    return msg;
+  }
+
+  /**
+   * Build a synthetic assistant message we insert into the log without
+   * a real API round trip (abort notices, future system injections).
+   * Reasoner models reject follow-up requests whose assistant history
+   * is missing `reasoning_content`, so we stamp an empty-string
+   * placeholder on reasoner sessions to satisfy the validator. V3
+   * doesn't care — field stays absent there.
+   */
+  private syntheticAssistantMessage(content: string): ChatMessage {
+    const msg: ChatMessage = { role: "assistant", content };
+    if (this.model.includes("reasoner")) {
+      msg.reasoning_content = "";
+    }
     return msg;
   }
 }
@@ -948,6 +1175,28 @@ export function stripHallucinatedToolMarkup(s: string): string {
   return out.trim();
 }
 
+/**
+ * Try to JSON-decode the model's tool-call arguments so PreToolUse /
+ * PostToolUse hooks get a structured object instead of a string.
+ * Falls back to the raw string when the model emits malformed JSON
+ * (the loop's own dispatch already tolerates that — keep parity).
+ */
+function safeParseToolArgs(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+/** Format non-pass hook outcomes as `LoopEvent`s of role `warning`. */
+function* hookWarnings(outcomes: HookOutcome[], turn: number): Generator<LoopEvent> {
+  for (const o of outcomes) {
+    if (o.decision === "pass") continue;
+    yield { turn, role: "warning", content: formatHookOutcomeMessage(o) };
+  }
+}
+
 function reasonPrefixFor(reason: "budget" | "aborted" | "context-guard", iterCap: number): string {
   if (reason === "aborted") return "[aborted by user (Esc) — summarizing what I found so far]";
   if (reason === "context-guard") {
@@ -1000,44 +1249,84 @@ export function shrinkOversizedToolResults(
   return { messages: out, healedCount, healedFrom };
 }
 
-export function healLoadedMessages(
+/**
+ * Token-aware variant of `shrinkOversizedToolResults`. Used by live
+ * `/compact` and auto-compact so the shrink cap bounds the REAL
+ * context footprint (CJK at 1 char/token would otherwise survive a
+ * char cap at 2× the intended token cost). Session-load heal still
+ * uses the char version for backward-compat on stored session files.
+ *
+ * Per-message token accounting: we tokenize each shrink candidate
+ * twice (before + after) so `tokensSaved` is exact. At typical log
+ * sizes (≤20 tool results) this is bounded; at pathological sizes
+ * the `truncateForModelByTokens` call internally never tokenizes the
+ * full input, so worst-case stays bounded too.
+ */
+export function shrinkOversizedToolResultsByTokens(
   messages: ChatMessage[],
-  maxChars: number,
-): { messages: ChatMessage[]; healedCount: number; healedFrom: number } {
-  // Pass 1: shrink oversized tool results (original heal purpose).
-  const shrunk = shrinkOversizedToolResults(messages, maxChars);
-  let healedCount = shrunk.healedCount;
-  // Pass 2: enforce tool_calls ↔ tool pairing across the full log.
-  //
-  // DeepSeek rejects two shapes at the API boundary:
-  //   (a) assistant with tool_calls not followed by matching tool
-  //       responses ("insufficient tool messages following tool_calls")
-  //   (b) tool message without a preceding assistant.tool_calls with
-  //       the matching tool_call_id ("must be a response to a preceding
-  //       message with 'tool_calls'")
-  //
-  // Corrupted session files from earlier builds have hit both. Rebuild
-  // the message stream so only well-formed (assistant.tool_calls + all
-  // matching responses) groups survive. Plain user/assistant messages
-  // (no tool_calls) always pass through.
+  maxTokens: number,
+): {
+  messages: ChatMessage[];
+  healedCount: number;
+  tokensSaved: number;
+  charsSaved: number;
+} {
+  let healedCount = 0;
+  let tokensSaved = 0;
+  let charsSaved = 0;
+  const out = messages.map((msg) => {
+    if (msg.role !== "tool") return msg;
+    const content = typeof msg.content === "string" ? msg.content : "";
+    // Fast path: length ≤ maxTokens ⇒ tokens ≤ maxTokens (every token
+    // is ≥1 char). Skip the per-message tokenize for small results.
+    if (content.length <= maxTokens) return msg;
+    const beforeTokens = countTokens(content);
+    if (beforeTokens <= maxTokens) return msg;
+    const truncated = truncateForModelByTokens(content, maxTokens);
+    const afterTokens = countTokens(truncated);
+    healedCount += 1;
+    tokensSaved += Math.max(0, beforeTokens - afterTokens);
+    charsSaved += Math.max(0, content.length - truncated.length);
+    return { ...msg, content: truncated };
+  });
+  return { messages: out, healedCount, tokensSaved, charsSaved };
+}
+
+/**
+ * Enforce tool_calls ↔ tool pairing across a message log. DeepSeek
+ * rejects two shapes at the API boundary:
+ *   (a) assistant with tool_calls not followed by matching tool
+ *       responses ("insufficient tool messages following tool_calls")
+ *   (b) tool message without a preceding assistant.tool_calls with
+ *       the matching tool_call_id ("must be a response to a preceding
+ *       message with 'tool_calls'")
+ *
+ * Corrupted session files from earlier builds have hit both. This pass
+ * rebuilds the message stream so only well-formed (assistant.tool_calls
+ * + all matching responses) groups survive. Plain user/assistant/system
+ * messages (no tool_calls) always pass through.
+ *
+ * Exported so both char-based and token-based heal can compose it.
+ */
+export function fixToolCallPairing(messages: ChatMessage[]): {
+  messages: ChatMessage[];
+  droppedAssistantCalls: number;
+  droppedStrayTools: number;
+} {
   const out: ChatMessage[] = [];
-  const openCallIds = new Set<string>();
   let droppedAssistantCalls = 0;
   let droppedStrayTools = 0;
-  for (let i = 0; i < shrunk.messages.length; i++) {
-    const msg = shrunk.messages[i]!;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i]!;
     if (msg.role === "assistant" && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
-      // Look ahead for tool responses matching every id in this
-      // assistant's tool_calls. If all present (in any order, but
-      // contiguous after this message), include the whole group.
       const needed = new Set<string>();
       for (const call of msg.tool_calls) {
         if (call?.id) needed.add(call.id);
       }
       const candidates: ChatMessage[] = [];
       let j = i + 1;
-      while (j < shrunk.messages.length && needed.size > 0) {
-        const nxt = shrunk.messages[j]!;
+      while (j < messages.length && needed.size > 0) {
+        const nxt = messages[j]!;
         if (nxt.role !== "tool") break;
         const id = nxt.tool_call_id ?? "";
         if (!needed.has(id)) break;
@@ -1046,13 +1335,10 @@ export function healLoadedMessages(
         j++;
       }
       if (needed.size === 0) {
-        // Every call has a response — emit the whole group.
         out.push(msg);
         for (const r of candidates) out.push(r);
-        i = j - 1; // for-loop ++ will advance past the last response
+        i = j - 1;
       } else {
-        // Drop the assistant entry and anything that was speculatively
-        // its responses — they'd become stray tool messages.
         droppedAssistantCalls += 1;
         droppedStrayTools += candidates.length;
         i = j - 1;
@@ -1060,17 +1346,51 @@ export function healLoadedMessages(
       continue;
     }
     if (msg.role === "tool") {
-      // Any tool message that reaches here did NOT get consumed by
-      // the assistant-with-tool_calls branch above, so it's stray.
-      // Drop it — surfacing it would 400 the next API call.
       droppedStrayTools += 1;
       continue;
     }
-    // Plain user/assistant/system message — pass through.
     out.push(msg);
   }
-  healedCount += droppedAssistantCalls + droppedStrayTools;
-  return { messages: out, healedCount, healedFrom: shrunk.healedFrom };
+  return { messages: out, droppedAssistantCalls, droppedStrayTools };
+}
+
+export function healLoadedMessages(
+  messages: ChatMessage[],
+  maxChars: number,
+): { messages: ChatMessage[]; healedCount: number; healedFrom: number } {
+  const shrunk = shrinkOversizedToolResults(messages, maxChars);
+  const paired = fixToolCallPairing(shrunk.messages);
+  const healedCount = shrunk.healedCount + paired.droppedAssistantCalls + paired.droppedStrayTools;
+  return { messages: paired.messages, healedCount, healedFrom: shrunk.healedFrom };
+}
+
+/**
+ * Token-aware counterpart of {@link healLoadedMessages}. Used at
+ * session-load time so resumed sessions come back capped at the same
+ * token budget (not char budget) as live tool results — CJK text no
+ * longer slips past at 2× the intended token cost when re-hydrated.
+ *
+ * Still does the same structural pass for tool_calls ↔ tool pairing;
+ * that logic is orthogonal to the truncation cap.
+ */
+export function healLoadedMessagesByTokens(
+  messages: ChatMessage[],
+  maxTokens: number,
+): {
+  messages: ChatMessage[];
+  healedCount: number;
+  tokensSaved: number;
+  charsSaved: number;
+} {
+  const shrunk = shrinkOversizedToolResultsByTokens(messages, maxTokens);
+  const paired = fixToolCallPairing(shrunk.messages);
+  const healedCount = shrunk.healedCount + paired.droppedAssistantCalls + paired.droppedStrayTools;
+  return {
+    messages: paired.messages,
+    healedCount,
+    tokensSaved: shrunk.tokensSaved,
+    charsSaved: shrunk.charsSaved,
+  };
 }
 
 /**

src/mcp/registry.ts

@@ -7,6 +7,7 @@
  * MCP ecosystem tool, wrapped in Reasonix's Pillar 1 + Pillar 3 benefits.
  */
 
+import { countTokens } from "../tokenizer.js";
 import { ToolRegistry } from "../tools.js";
 import type { JSONSchema } from "../types.js";
 import type { McpClient } from "./client.js";
@@ -58,6 +59,18 @@ export interface BridgeOptions {
  */
 export const DEFAULT_MAX_RESULT_CHARS = 32_000;
 
+/**
+ * Token-aware cap for tool results, in DeepSeek V3 tokens.
+ *
+ * 8,000 tokens ≈ 6% of DeepSeek V3's 131K context. One oversized tool
+ * result can't eat more than that no matter what character density the
+ * content has. The char cap (32K chars) only bounds tokens for English
+ * — CJK text at 1 char/token blows past 16K tokens under the same
+ * ceiling. With the tokenizer shipped in 0.5.0 we can cap the thing
+ * that actually matters.
+ */
+export const DEFAULT_MAX_RESULT_TOKENS = 8_000;
+
 export interface BridgeResult {
   registry: ToolRegistry;
   /** Names actually registered (may differ from MCP names when a prefix is applied). */
@@ -159,6 +172,94 @@ export function truncateForModel(s: string, maxChars: number): string {
   return `${head}\n\n[…truncated ${dropped} chars — raise BridgeOptions.maxResultChars, or call the tool with a narrower scope (filter, head, pagination)…]\n\n${tail}`;
 }
 
+/**
+ * Token-aware truncation. Same head+tail policy as `truncateForModel`,
+ * but sizes the slices against a DeepSeek V3 token budget instead of a
+ * raw character count — so CJK text (which previously survived at 2×
+ * the token cost per char) gets capped at the same effective context
+ * footprint as English.
+ *
+ * Strategy: fast path when `s.length <= maxTokens` (every token is ≥1
+ * char, so this bounds tokens ≤ maxTokens — skip tokenize entirely).
+ * Short-ish strings are confirmed against the real token count.
+ * Long strings go straight to char-sliced head+tail with one or two
+ * tokenize-verify-and-shrink rounds per slice — we deliberately never
+ * tokenize the full input, because pathological repetitive text
+ * (megabytes of `AAAA…`) can cost 30s+ on the pure-TS BPE port.
+ */
+export function truncateForModelByTokens(s: string, maxTokens: number): string {
+  if (maxTokens <= 0) return "";
+  // Every token is ≥1 char — if length ≤ budget, tokens ≤ budget.
+  if (s.length <= maxTokens) return s;
+  // Small enough to tokenize-check without pathological cost: confirm
+  // whether we're actually over budget. (Threshold is the char-bound
+  // worst case for English/code — ~4 chars/token.)
+  if (s.length <= maxTokens * 4) {
+    const tokens = countTokens(s);
+    if (tokens <= maxTokens) return s;
+  }
+
+  const markerOverhead = 48; // rough token cost of the truncation marker
+  const contentBudget = Math.max(0, maxTokens - markerOverhead);
+  const tailBudget = Math.min(256, Math.floor(contentBudget * 0.1));
+  const headBudget = Math.max(0, contentBudget - tailBudget);
+
+  const head = sizePrefixToTokens(s, headBudget);
+  const tail = sizeSuffixToTokens(s, tailBudget);
+  const droppedChars = s.length - head.length - tail.length;
+  // Estimate dropped tokens from the per-slice char/token ratio we
+  // already measured, rather than paying another full-string tokenize.
+  // The marker says "~N tokens" so the ≤10% slop is visible to readers.
+  const headTokens = head ? countTokens(head) : 0;
+  const tailTokens = tail ? countTokens(tail) : 0;
+  const sampleChars = head.length + tail.length;
+  const sampleTokens = headTokens + tailTokens;
+  const ratio = sampleChars > 0 ? sampleTokens / sampleChars : 0.3;
+  const estTotalTokens = Math.ceil(s.length * ratio);
+  const droppedTokens = Math.max(0, estTotalTokens - sampleTokens);
+  return `${head}\n\n[…truncated ~${droppedTokens} tokens (${droppedChars} chars) — raise BridgeOptions.maxResultTokens, or call the tool with a narrower scope (filter, head, pagination)…]\n\n${tail}`;
+}
+
+/**
+ * Slice `s` from the start to the largest prefix that fits `budget`
+ * tokens. Never tokenizes the full input: starts with a char-bound
+ * estimate, then verifies and shrinks. Converges in 1–2 iterations.
+ */
+function sizePrefixToTokens(s: string, budget: number): string {
+  if (budget <= 0 || s.length === 0) return "";
+  // Optimistic starting size: assume ~4 chars/token (English/code
+  // average). If the content is denser (CJK ~1 char/token), the first
+  // tokenize will show we're over and we shrink.
+  let size = Math.min(s.length, budget * 4);
+  for (let iter = 0; iter < 6; iter++) {
+    if (size <= 0) return "";
+    const slice = s.slice(0, size);
+    const count = countTokens(slice);
+    if (count <= budget) return slice;
+    // Shrink by the overshoot fraction plus a small safety margin.
+    const next = Math.floor(size * (budget / count) * 0.95);
+    if (next >= size) return s.slice(0, Math.max(0, size - 1));
+    size = next;
+  }
+  return s.slice(0, Math.max(0, size));
+}
+
+/** Slice `s` from the end to the largest suffix that fits `budget` tokens. */
+function sizeSuffixToTokens(s: string, budget: number): string {
+  if (budget <= 0 || s.length === 0) return "";
+  let size = Math.min(s.length, budget * 4);
+  for (let iter = 0; iter < 6; iter++) {
+    if (size <= 0) return "";
+    const slice = s.slice(-size);
+    const count = countTokens(slice);
+    if (count <= budget) return slice;
+    const next = Math.floor(size * (budget / count) * 0.95);
+    if (next >= size) return s.slice(-Math.max(0, size - 1));
+    size = next;
+  }
+  return s.slice(-Math.max(0, size));
+}
+
 function blockToString(block: McpContentBlock): string {
   if (block.type === "text") return block.text;
   if (block.type === "image") return `[image ${block.mimeType}, ${block.data.length} chars base64]`;

src/project-memory.ts

@@ -0,0 +1,99 @@
+/**
+ * Project memory — a user-authored `REASONIX.md` in the project root
+ * that gets pinned into the immutable-prefix system prompt.
+ *
+ * Design notes:
+ *
+ *   - The file lands in `ImmutablePrefix.system`, so the whole memory
+ *     block is hashed into the cache prefix fingerprint. Editing the
+ *     file invalidates the prefix; unchanged memory across sessions
+ *     keeps the DeepSeek prefix cache warm. That matches Pillar 1 —
+ *     memory is a deliberate, stable prefix, not per-turn drift.
+ *   - Only one source: the working-root `REASONIX.md`. No parent walk,
+ *     no `~/.reasonix/REASONIX.md`, no CLAUDE.md fallback. User-global
+ *     memory can come later; for v1 one file == one mental model.
+ *   - Truncated at 8 000 chars (≈ 2k tokens). `.gitignore` gets 2 000
+ *     because it's a constraint dump; memory gets more headroom because
+ *     it's deliberate instructions.
+ *   - Opt-out via `REASONIX_MEMORY=off|false|0`. No CLI flag — memory
+ *     is a file, `rm REASONIX.md` is the other opt-out.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const PROJECT_MEMORY_FILE = "REASONIX.md";
+export const PROJECT_MEMORY_MAX_CHARS = 8000;
+
+export interface ProjectMemory {
+  /** Absolute path the memory was read from. */
+  path: string;
+  /** Post-truncation content (may include a "… (truncated N chars)" marker). */
+  content: string;
+  /** Original byte length before truncation. */
+  originalChars: number;
+  /** True iff `originalChars > PROJECT_MEMORY_MAX_CHARS`. */
+  truncated: boolean;
+}
+
+/**
+ * Read `REASONIX.md` from `rootDir`. Returns `null` when the file is
+ * missing, unreadable, or empty (whitespace-only counts as empty — an
+ * empty memory file shouldn't perturb the cache prefix).
+ */
+export function readProjectMemory(rootDir: string): ProjectMemory | null {
+  const path = join(rootDir, PROJECT_MEMORY_FILE);
+  if (!existsSync(path)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const originalChars = trimmed.length;
+  const truncated = originalChars > PROJECT_MEMORY_MAX_CHARS;
+  const content = truncated
+    ? `${trimmed.slice(0, PROJECT_MEMORY_MAX_CHARS)}\n… (truncated ${
+        originalChars - PROJECT_MEMORY_MAX_CHARS
+      } chars)`
+    : trimmed;
+  return { path, content, originalChars, truncated };
+}
+
+/**
+ * Resolve whether project memory should be read. Default: on.
+ * `REASONIX_MEMORY=off|false|0` turns it off (CI, reproducing issues,
+ * intentional offline runs).
+ */
+export function memoryEnabled(): boolean {
+  const env = process.env.REASONIX_MEMORY;
+  if (env === "off" || env === "false" || env === "0") return false;
+  return true;
+}
+
+/**
+ * Return `basePrompt` with the project's `REASONIX.md` appended as a
+ * "Project memory" section. No-op when the file is absent, empty, or
+ * memory is disabled via env.
+ *
+ * The appended block is deterministic — identical input ⇒ identical
+ * output — so every session that opens against the same memory file
+ * gets the same prefix hash.
+ */
+export function applyProjectMemory(basePrompt: string, rootDir: string): string {
+  if (!memoryEnabled()) return basePrompt;
+  const mem = readProjectMemory(rootDir);
+  if (!mem) return basePrompt;
+  return `${basePrompt}
+
+# Project memory (REASONIX.md)
+
+The user pinned these notes about this project — treat them as authoritative context for every turn:
+
+\`\`\`
+${mem.content}
+\`\`\`
+`;
+}

src/repair/index.ts

@@ -46,6 +46,17 @@ export class ToolCallRepair {
     this.storm = new StormBreaker(opts.stormWindow ?? 6, opts.stormThreshold ?? 3);
   }
 
+  /**
+   * Drop the StormBreaker's sliding window of recent (name, args)
+   * signatures. Called at the start of every user turn — a fresh user
+   * message is a new intent, so carrying old repetition state into it
+   * would turn a valid "try again with different input" flow into a
+   * false-positive block.
+   */
+  resetStorm(): void {
+    this.storm.reset();
+  }
+
   process(
     declaredCalls: ToolCall[],
     reasoningContent: string | null,

src/session.ts

@@ -107,6 +107,15 @@ export function deleteSession(name: string): boolean {
   const path = sessionPath(name);
   try {
     unlinkSync(path);
+    // Best-effort cleanup of side-car files that belong to this session
+    // so `/forget` doesn't leave orphans in `sessionsDir()`. Currently
+    // just the pending-edits checkpoint (src/code/pending-edits.ts).
+    const sidecar = path.replace(/\.jsonl$/, ".pending.json");
+    try {
+      unlinkSync(sidecar);
+    } catch {
+      /* no sidecar present — expected for sessions without pending edits */
+    }
     return true;
   } catch {
     return false;

src/skills.ts

@@ -0,0 +1,397 @@
+/**
+ * Skills — user-defined prompt packs pinned (by name) into the
+ * immutable prefix and loaded (by body) on demand.
+ *
+ * Two scopes mirror the user-memory layout:
+ *   - `project` → `<projectRoot>/.reasonix/skills/` (this repo only)
+ *   - `global`  → `~/.reasonix/skills/`            (every session)
+ *
+ * Project scope wins on a name collision. Deliberately NOT tied to
+ * any specific client's directory convention (`.claude/`, `.glm/`,
+ * etc.) — Reasonix is model-agnostic at the conversation layer, so
+ * coupling the skill filesystem to one vendor would break any user
+ * running a different backend.
+ *
+ * Accepted file layouts (both emit the same `Skill`):
+ *   - `{dir}/<name>/SKILL.md`   (preferred — lets a skill bundle
+ *                                additional assets alongside)
+ *   - `{dir}/<name>.md`         (flat, one-file shorthand)
+ *
+ * Frontmatter keys we read:
+ *   - `name`          — optional, defaults to the file / dir name
+ *   - `description`   — one-line index description (REQUIRED for listing)
+ *   - `allowed-tools` — parsed but UNUSED in v1 (see tools/skills.ts)
+ *
+ * Cache-First contract (Pillar 1):
+ *   - The PREFIX sees only names + descriptions (one line each).
+ *   - Bodies enter the APPEND-ONLY LOG lazily, via `run_skill` or
+ *     `/skill <name>` — never the prefix. That keeps the prefix hash
+ *     stable across skill additions to the body store.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export const SKILLS_DIRNAME = "skills";
+export const SKILL_FILE = "SKILL.md";
+/** Cap on the pinned skills-index block, mirrors memory-index cap. */
+export const SKILLS_INDEX_MAX_CHARS = 4000;
+/** Skill identifier shape — alnum + `_` + `-` + interior `.`, 1-64 chars. */
+const VALID_SKILL_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+
+export type SkillScope = "project" | "global" | "builtin";
+
+/**
+ * Execution mode for a skill. `inline` (default) returns the body as a
+ * tool result so the body enters the parent's append-only log — the
+ * model continues the loop using the loaded instructions. `subagent`
+ * spawns an isolated child loop with the body as the system prompt and
+ * the user-supplied `arguments` as the task; only the child's final
+ * answer comes back. Use `subagent` for big-context exploration / research
+ * playbooks where the parent doesn't need to see the trail.
+ */
+export type SkillRunAs = "inline" | "subagent";
+
+export interface Skill {
+  /** Canonical name — sanitized, matches the directory / filename stem. */
+  name: string;
+  /** One-line description shown in the pinned index. */
+  description: string;
+  /** Full markdown body (post-frontmatter). Loaded on demand. */
+  body: string;
+  /** Which scope this skill was loaded from. */
+  scope: SkillScope;
+  /** Absolute path to the SKILL.md (or {name}.md) file, or "(builtin)" for shipped defaults. */
+  path: string;
+  /** Raw `allowed-tools` field from frontmatter, if any. Unused in v1. */
+  allowedTools?: string;
+  /**
+   * Execution mode (frontmatter `runAs`). Defaults to `inline` for
+   * backwards compatibility with skills written before this field
+   * existed.
+   */
+  runAs: SkillRunAs;
+  /**
+   * Frontmatter `model` — when set, overrides the default model the
+   * subagent runs on. Only meaningful when `runAs === "subagent"`.
+   * Accept any DeepSeek model id; the subagent layer falls back to its
+   * own default if this is missing or invalid.
+   */
+  model?: string;
+}
+
+export interface SkillStoreOptions {
+  /** Override `$HOME` — tests point this at a tmpdir. */
+  homeDir?: string;
+  /**
+   * Absolute project root. Required to surface project-scope skills;
+   * omit (e.g. in `reasonix chat` without `code`) and the store only
+   * reads the global scope.
+   */
+  projectRoot?: string;
+  /**
+   * Suppress the bundled built-in skills (`explore`, `research`).
+   * Used by unit tests that want to assert exact list contents
+   * without the +2 builtins distorting counts. Production callers
+   * leave this off so users always get the bundled defaults.
+   */
+  disableBuiltins?: boolean;
+}
+
+/**
+ * Parse a `---` frontmatter block. Same minimal shape as user-memory:
+ * `key: value` lines, no quoting, no nesting. Returns `{}` data and the
+ * full input as body when no frontmatter fence is present — so hand-
+ * written files without frontmatter still surface (with empty desc).
+ */
+function parseFrontmatter(raw: string): { data: Record<string, string>; body: string } {
+  const lines = raw.split(/\r?\n/);
+  if (lines[0] !== "---") return { data: {}, body: raw };
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return { data: {}, body: raw };
+  const data: Record<string, string> = {};
+  for (let i = 1; i < end; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (m?.[1]) data[m[1]] = (m[2] ?? "").trim();
+  }
+  return {
+    data,
+    body: lines
+      .slice(end + 1)
+      .join("\n")
+      .replace(/^\n+/, ""),
+  };
+}
+
+function isValidSkillName(name: string): boolean {
+  return VALID_SKILL_NAME.test(name);
+}
+
+export class SkillStore {
+  private readonly homeDir: string;
+  private readonly projectRoot: string | undefined;
+  private readonly disableBuiltins: boolean;
+
+  constructor(opts: SkillStoreOptions = {}) {
+    this.homeDir = opts.homeDir ?? homedir();
+    this.projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : undefined;
+    this.disableBuiltins = opts.disableBuiltins === true;
+  }
+
+  /** True iff this store was configured with a project root. */
+  hasProjectScope(): boolean {
+    return this.projectRoot !== undefined;
+  }
+
+  /**
+   * Root directories scanned, in priority order. Project scope first
+   * so a per-repo skill overrides a global one with the same name —
+   * users expect the local copy to win when both exist.
+   */
+  roots(): Array<{ dir: string; scope: SkillScope }> {
+    const out: Array<{ dir: string; scope: SkillScope }> = [];
+    if (this.projectRoot) {
+      out.push({
+        dir: join(this.projectRoot, ".reasonix", SKILLS_DIRNAME),
+        scope: "project",
+      });
+    }
+    out.push({ dir: join(this.homeDir, ".reasonix", SKILLS_DIRNAME), scope: "global" });
+    return out;
+  }
+
+  /**
+   * List every skill visible to this store. On name collisions the
+   * higher-priority root (project over global over builtin) wins.
+   * Sorted by name for stable prefix hashing.
+   */
+  list(): Skill[] {
+    const byName = new Map<string, Skill>();
+    for (const { dir, scope } of this.roots()) {
+      if (!existsSync(dir)) continue;
+      let entries: import("node:fs").Dirent[];
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const skill = this.readEntry(dir, scope, entry);
+        if (!skill) continue;
+        if (!byName.has(skill.name)) byName.set(skill.name, skill);
+      }
+    }
+    // Builtins are appended last so user/project files take precedence
+    // when names collide. The same priority you'd expect: my-project's
+    // "explore" overrides the shipped one without forcing a different
+    // name.
+    if (!this.disableBuiltins) {
+      for (const skill of BUILTIN_SKILLS) {
+        if (!byName.has(skill.name)) byName.set(skill.name, skill);
+      }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /** Resolve one skill by name. Returns `null` if not found or malformed. */
+  read(name: string): Skill | null {
+    if (!isValidSkillName(name)) return null;
+    for (const { dir, scope } of this.roots()) {
+      if (!existsSync(dir)) continue;
+      const dirCandidate = join(dir, name, SKILL_FILE);
+      if (existsSync(dirCandidate) && statSync(dirCandidate).isFile()) {
+        return this.parse(dirCandidate, name, scope);
+      }
+      const flatCandidate = join(dir, `${name}.md`);
+      if (existsSync(flatCandidate) && statSync(flatCandidate).isFile()) {
+        return this.parse(flatCandidate, name, scope);
+      }
+    }
+    // Fall back to builtins. Same precedence as `list()` — user-authored
+    // wins, builtins are the floor.
+    if (!this.disableBuiltins) {
+      for (const skill of BUILTIN_SKILLS) {
+        if (skill.name === name) return skill;
+      }
+    }
+    return null;
+  }
+
+  private readEntry(dir: string, scope: SkillScope, entry: import("node:fs").Dirent): Skill | null {
+    if (entry.isDirectory()) {
+      if (!isValidSkillName(entry.name)) return null;
+      const file = join(dir, entry.name, SKILL_FILE);
+      if (!existsSync(file)) return null;
+      return this.parse(file, entry.name, scope);
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      const stem = entry.name.slice(0, -3);
+      if (!isValidSkillName(stem)) return null;
+      return this.parse(join(dir, entry.name), stem, scope);
+    }
+    return null;
+  }
+
+  private parse(path: string, stem: string, scope: SkillScope): Skill | null {
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch {
+      return null;
+    }
+    const { data, body } = parseFrontmatter(raw);
+    const name = data.name && isValidSkillName(data.name) ? data.name : stem;
+    return {
+      name,
+      description: (data.description ?? "").trim(),
+      body: body.trim(),
+      scope,
+      path,
+      allowedTools: data["allowed-tools"],
+      runAs: parseRunAs(data.runAs),
+      model: data.model?.startsWith("deepseek-") ? data.model : undefined,
+    };
+  }
+}
+
+/**
+ * Coerce a frontmatter `runAs` string to the discriminated union. Any
+ * value other than the literal "subagent" is treated as inline — typos
+ * and unknown values default to the safe (non-spawning) mode rather
+ * than failing the load.
+ */
+function parseRunAs(raw: string | undefined): SkillRunAs {
+  return raw?.trim() === "subagent" ? "subagent" : "inline";
+}
+
+/**
+ * Build a single index line for one skill. Shape mirrors memory's
+ * `indexLine` — a bullet suitable for a markdown fenced block in the
+ * system prompt. Description is truncated to keep the full line under
+ * ~150 chars. Subagent-runAs skills carry a 🧬 marker so the model
+ * sees at a glance which skills will spawn an isolated child loop.
+ */
+function skillIndexLine(s: Pick<Skill, "name" | "description" | "runAs">): string {
+  const safeDesc = s.description.replace(/\n/g, " ").trim();
+  const marker = s.runAs === "subagent" ? "🧬 " : "";
+  const max = 130 - s.name.length - marker.length;
+  const clipped = safeDesc.length > max ? `${safeDesc.slice(0, Math.max(1, max - 1))}…` : safeDesc;
+  return clipped ? `- ${marker}${s.name} — ${clipped}` : `- ${marker}${s.name}`;
+}
+
+/**
+ * Append a `# Skills` block to `basePrompt` listing every discovered
+ * skill (name + description only). Bodies are NOT inlined — that's the
+ * whole point: the prefix stays short and cacheable; full content loads
+ * on demand via `run_skill` or `/skill <name>`.
+ *
+ * Emits nothing when no skills are discovered — keeps the prefix hash
+ * stable for users who don't use skills at all.
+ */
+export function applySkillsIndex(basePrompt: string, opts: SkillStoreOptions = {}): string {
+  const store = new SkillStore(opts);
+  const skills = store.list().filter((s) => s.description);
+  if (skills.length === 0) return basePrompt;
+  const lines = skills.map(skillIndexLine);
+  const joined = lines.join("\n");
+  const truncated =
+    joined.length > SKILLS_INDEX_MAX_CHARS
+      ? `${joined.slice(0, SKILLS_INDEX_MAX_CHARS)}\n… (truncated ${
+          joined.length - SKILLS_INDEX_MAX_CHARS
+        } chars)`
+      : joined;
+  return [
+    basePrompt,
+    "",
+    "# Skills — playbooks you can invoke",
+    "",
+    'One-liner index. Each entry is either a built-in or a user-authored playbook. Call `run_skill({ name: "<skill-name>", arguments: "<task>" })` to invoke one. Skills marked with 🧬 spawn an **isolated subagent** — its tool calls and reasoning never enter your context, only its final answer does. Use 🧬 skills for tasks that would otherwise flood your context (deep exploration, multi-step research, anything where you only need the conclusion). Plain skills are inlined: their body becomes a tool result you read and act on directly. The user can also invoke a skill via `/skill <name>`.',
+    "",
+    "```",
+    truncated,
+    "```",
+  ].join("\n");
+}
+
+/**
+ * Built-in skills shipped with Reasonix. These are always available
+ * (no install step) and live as constants rather than files because:
+ *   - Zero filesystem coupling — no copy-on-first-run dance, nothing
+ *     to migrate when we update them.
+ *   - They participate in the same `byName` priority as user/project
+ *     skills: write `~/.reasonix/skills/explore.md` to override.
+ *
+ * Keep this list small and high-leverage. The bar for adding one: it
+ * demonstrates a pattern users would otherwise have to invent
+ * themselves, and the body fits in a screen.
+ */
+const BUILTIN_EXPLORE_BODY = `You are running as an exploration subagent. Your job is to investigate the codebase the parent agent pointed you at, then return one focused, distilled answer.
+
+How to operate:
+- Use read_file, search_files, search_content, directory_tree, list_directory, get_file_info as your primary tools. Stay read-only.
+- For "find all places that call / reference / use X" questions, use \`search_content\` (content grep) — NOT \`search_files\` (which only matches file names). This is the most common subagent mistake; using the wrong tool gives empty results and you waste your iter budget chasing a phantom.
+- Cast a wide net first (search_content for symbol references, directory_tree for structure) to map the territory; then read the 3-10 most relevant files in full.
+- Don't read every file — be selective. Aim for breadth on the first pass, depth only where the question demands it.
+- Stop exploring as soon as you can answer the question. The parent doesn't see your tool calls, so over-exploration is pure waste.
+
+Your final answer:
+- One paragraph (or a few short bullets). Lead with the conclusion.
+- Cite specific file paths + line ranges when they support the answer.
+- If the question can't be answered from what you found, say so plainly and suggest where to look next.
+- No follow-up offers, no "let me know if you need more." The parent will ask again if they need more.
+
+Formatting (rendered in a TUI):
+- Tabular data → GitHub-Flavored Markdown tables with ASCII pipes (\`| col | col |\` + \`| --- | --- |\`). Never use Unicode box-drawing characters (│ ─ ┼) — they break word-wrap.
+- Keep table cells short; if a cell needs a paragraph, use bullets below the table instead.
+- Code, file paths with line ranges, and shell commands → fenced code blocks (\`\`\`).
+- NEVER draw decorative frames around code or text with \`┌──┐ │ └──┘\` box-drawing characters. Use plain code blocks; the renderer adds its own border.
+- For flow charts: use a bullet list with \`→\` or \`↓\` between steps, not ASCII boxes-and-arrows.
+
+The 'task' the parent gave you is the question you must answer. Treat any other reading of it as scope creep.`;
+
+const BUILTIN_RESEARCH_BODY = `You are running as a research subagent. Your job is to gather information from code AND the web, synthesize it, and return one focused conclusion.
+
+How to operate:
+- Combine code reading (read_file, search_files) with web tools (web_search, web_fetch) as appropriate to the question.
+- For "how does X work" / "is Y supported" questions: web first to find the canonical reference, then verify against the local code.
+- For "what's our policy on Z" / "where do we use Q": local code first, web only if you need to compare against external standards.
+- Cap yourself at ~10 tool calls. If you can't converge in 10, return what you have plus a note about what's missing.
+
+Your final answer:
+- One paragraph (or short bullets). Lead with the conclusion.
+- Cite both code (file:line) AND web sources (URL) when they back the answer.
+- Distinguish "I verified this in code" from "I read this on a docs page" — the parent will trust the former more.
+- If the answer is uncertain, say so. Don't invent confidence.
+
+Formatting (rendered in a TUI):
+- Tabular data → GitHub-Flavored Markdown tables with ASCII pipes (\`| col | col |\` + \`| --- | --- |\`). Never use Unicode box-drawing characters (│ ─ ┼) — they break word-wrap.
+- Keep table cells short; if a cell needs a paragraph, use bullets below the table instead.
+- Code, file paths with line ranges, and shell commands → fenced code blocks (\`\`\`).
+- NEVER draw decorative frames around code or text with \`┌──┐ │ └──┘\` box-drawing characters. Use plain code blocks; the renderer adds its own border.
+- For flow charts: use a bullet list with \`→\` or \`↓\` between steps, not ASCII boxes-and-arrows.
+
+The 'task' the parent gave you is the research question. Stay on it.`;
+
+const BUILTIN_SKILLS: readonly Skill[] = Object.freeze([
+  Object.freeze<Skill>({
+    name: "explore",
+    description:
+      "Explore the codebase in an isolated subagent — wide-net read-only investigation that returns one distilled answer. Best for: 'find all places that...', 'how does X work across the project', 'survey the code for Y'.",
+    body: BUILTIN_EXPLORE_BODY,
+    scope: "builtin",
+    path: "(builtin)",
+    runAs: "subagent",
+  }),
+  Object.freeze<Skill>({
+    name: "research",
+    description:
+      "Research a question by combining web search + code reading in an isolated subagent. Best for: 'is X feature supported by lib Y', 'what's the canonical way to do Z', 'compare our impl against the spec'.",
+    body: BUILTIN_RESEARCH_BODY,
+    scope: "builtin",
+    path: "(builtin)",
+    runAs: "subagent",
+  }),
+]);

src/telemetry.ts

@@ -1,12 +1,24 @@
 import type { Usage } from "./client.js";
 
-/** USD per 1M tokens. Update as DeepSeek pricing changes. */
+/**
+ * USD per 1M tokens. Source of truth is DeepSeek's CNY price sheet at
+ * https://api-docs.deepseek.com/zh-cn/quick_start/pricing (as of
+ * 2026-04-23): chat and reasoner are unified at ¥0.2 / ¥2 / ¥3 per 1M
+ * tokens (cache-hit input / cache-miss input / output). Converted at
+ * a fixed 7.2 CNY/USD rate so stats stay stable across the daily FX
+ * drift; revisit if the rate moves more than ±5%.
+ *
+ * Historical note: the pre-unification prices were chat $0.07/$0.27/$1.10
+ * and reasoner $0.14/$0.55/$2.19. Sessions logged under those values
+ * in `~/.reasonix/usage.jsonl` remain as-is (USD frozen at record time)
+ * — we never retroactively rewrite billing history.
+ */
 export const DEEPSEEK_PRICING: Record<
   string,
   { inputCacheHit: number; inputCacheMiss: number; output: number }
 > = {
-  "deepseek-chat": { inputCacheHit: 0.07, inputCacheMiss: 0.27, output: 1.1 },
-  "deepseek-reasoner": { inputCacheHit: 0.14, inputCacheMiss: 0.55, output: 2.19 },
+  "deepseek-chat": { inputCacheHit: 0.028, inputCacheMiss: 0.28, output: 0.42 },
+  "deepseek-reasoner": { inputCacheHit: 0.028, inputCacheMiss: 0.28, output: 0.42 },
 };
 
 /** Reference Claude Sonnet 4.6 pricing (USD per 1M tokens). */

src/tokenizer.ts

@@ -0,0 +1,375 @@
+/**
+ * Pure-TS port of DeepSeek's V3 tokenizer. Reads the slimmed+gzipped
+ * HuggingFace-format tokenizer data shipped at
+ * `data/deepseek-tokenizer.json.gz` and implements enough of the HF
+ * pipeline (Split pre-tokenizers → ByteLevel → BPE) to count tokens
+ * offline without pulling the `@lenml/tokenizers` or native Rust deps.
+ *
+ * Accuracy target: within ~3% of the API-returned `usage.prompt_tokens`
+ * for mixed CJK+English+code input. Exact-to-API match would also
+ * require replaying the Jinja chat template (role markers / tool call
+ * framing); we intentionally skip that — for a gauge/UI estimate the
+ * raw-text count is the useful number.
+ *
+ * Scope: ENCODE-SIDE ONLY. We don't need decode for counting; adding
+ * it later is trivial via the inverse byte-level table.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+interface AddedToken {
+  id: number;
+  content: string;
+  special: boolean;
+  normalized: boolean;
+}
+
+interface SplitPretokenizer {
+  type: "Split";
+  pattern: { Regex: string };
+  behavior: "Isolated" | "Removed" | string;
+  invert: boolean;
+}
+
+interface ByteLevelPretokenizer {
+  type: "ByteLevel";
+  add_prefix_space: boolean;
+  trim_offsets: boolean;
+  use_regex: boolean;
+}
+
+type Pretokenizer = SplitPretokenizer | ByteLevelPretokenizer;
+
+interface TokenizerData {
+  added_tokens: AddedToken[];
+  pre_tokenizer: {
+    type: "Sequence";
+    pretokenizers: Pretokenizer[];
+  };
+  model: {
+    type: "BPE";
+    vocab: Record<string, number>;
+    merges: string[];
+  };
+}
+
+interface LoadedTokenizer {
+  vocab: Record<string, number>;
+  mergeRank: Map<string, number>;
+  splitRegexes: RegExp[];
+  byteToChar: string[];
+  /**
+   * Non-special added tokens (e.g. `<think>`, `<｜fim▁hole｜>`) that the
+   * HF tokenizer recognizes as atomic units when they appear inline in
+   * the text. Special tokens like `<｜begin▁of▁sentence｜>` are NOT in
+   * this list — the model ignores them when they appear in user text
+   * (the default HF `split_special_tokens=False` behavior), so we do
+   * the same: they get tokenized byte-by-byte, not as the special ID.
+   */
+  addedPattern: RegExp | null;
+  addedMap: Map<string, number>;
+}
+
+/**
+ * GPT-2 byte-to-unicode mapping. Covers every byte 0..255 with a
+ * deterministic visible-printable unicode char — this is what lets the
+ * byte-level BPE show up in JSON vocabs as readable strings (`Ġ` for
+ * space, `Ċ` for `\n`, etc). Identical across every byte-level BPE
+ * tokenizer DeepSeek ships.
+ */
+function buildByteToChar(): string[] {
+  const result: string[] = new Array(256);
+  const bs: number[] = [];
+  for (let b = 33; b <= 126; b++) bs.push(b);
+  for (let b = 161; b <= 172; b++) bs.push(b);
+  for (let b = 174; b <= 255; b++) bs.push(b);
+  const cs = bs.slice();
+  let n = 0;
+  for (let b = 0; b < 256; b++) {
+    if (!bs.includes(b)) {
+      bs.push(b);
+      cs.push(256 + n);
+      n++;
+    }
+  }
+  for (let i = 0; i < bs.length; i++) {
+    result[bs[i]!] = String.fromCodePoint(cs[i]!);
+  }
+  return result;
+}
+
+let cached: LoadedTokenizer | null = null;
+
+/**
+ * Find the bundled tokenizer data file. Resolution order (first hit wins):
+ * 1. `REASONIX_TOKENIZER_PATH` env var (tests / custom builds).
+ * 2. `../data/deepseek-tokenizer.json.gz` relative to this module —
+ *    covers dev (src/tokenizer.ts → data/) AND production bundled at
+ *    dist/index.js → dist/../data = data/.
+ * 3. `../../data/deepseek-tokenizer.json.gz` — covers the CLI bundle
+ *    at dist/cli/index.js → dist/cli/../../data = data/. Without this
+ *    step 2 resolves to dist/data/ which doesn't exist (the data file
+ *    is shipped at package root per package.json `files` entry), and
+ *    every step() preflight crashes the loop with ENOENT.
+ * 4. `require.resolve("reasonix/package.json")` — last-resort package
+ *    root lookup for unusual bundlers.
+ */
+function resolveDataPath(): string {
+  if (process.env.REASONIX_TOKENIZER_PATH) return process.env.REASONIX_TOKENIZER_PATH;
+  const candidates: string[] = [];
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    candidates.push(join(here, "..", "data", "deepseek-tokenizer.json.gz"));
+    candidates.push(join(here, "..", "..", "data", "deepseek-tokenizer.json.gz"));
+  } catch {
+    /* import.meta.url unavailable — skip to the package resolution step. */
+  }
+  try {
+    const req = createRequire(import.meta.url);
+    candidates.push(
+      join(dirname(req.resolve("reasonix/package.json")), "data", "deepseek-tokenizer.json.gz"),
+    );
+  } catch {
+    /* Not installed as `reasonix/` — the earlier candidates still may hit. */
+  }
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  // Nothing exists — return the first candidate anyway so readFileSync
+  // surfaces a concrete path in the ENOENT message (better than silent miss).
+  return candidates[0] ?? join(process.cwd(), "data", "deepseek-tokenizer.json.gz");
+}
+
+function loadTokenizer(): LoadedTokenizer {
+  if (cached) return cached;
+  const buf = readFileSync(resolveDataPath());
+  const json = gunzipSync(buf).toString("utf8");
+  const data = JSON.parse(json) as TokenizerData;
+
+  const mergeRank = new Map<string, number>();
+  for (let i = 0; i < data.model.merges.length; i++) {
+    mergeRank.set(data.model.merges[i]!, i);
+  }
+
+  const splitRegexes: RegExp[] = [];
+  for (const p of data.pre_tokenizer.pretokenizers) {
+    if (p.type === "Split") {
+      // All three Split rules use Isolated — matches become their own
+      // pre-tokens and so do the in-between stretches. The ByteLevel
+      // stage in the Sequence does no extra splitting here
+      // (use_regex:false), so our 3 Split regexes are the whole story.
+      splitRegexes.push(new RegExp(p.pattern.Regex, "gu"));
+    }
+  }
+
+  const addedMap = new Map<string, number>();
+  const addedContents: string[] = [];
+  for (const t of data.added_tokens) {
+    if (!t.special) {
+      addedMap.set(t.content, t.id);
+      addedContents.push(t.content);
+    }
+  }
+  // Longest-first ensures greedy matching doesn't lose a longer token
+  // to a shorter prefix (e.g. `<think>` before `<`).
+  addedContents.sort((a, b) => b.length - a.length);
+  const addedPattern = addedContents.length
+    ? new RegExp(addedContents.map(escapeRegex).join("|"), "g")
+    : null;
+
+  cached = {
+    vocab: data.model.vocab,
+    mergeRank,
+    splitRegexes,
+    byteToChar: buildByteToChar(),
+    addedPattern,
+    addedMap,
+  };
+  return cached;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Apply one "Isolated" Split: the matches become their own pre-tokens,
+ * stretches between matches pass through unchanged. Empty pre-tokens
+ * are dropped so downstream stages don't see them.
+ */
+function applySplit(chunks: string[], re: RegExp): string[] {
+  const out: string[] = [];
+  for (const chunk of chunks) {
+    if (!chunk) continue;
+    // Reset lastIndex — reusing a /g regex across matchAll iterations
+    // is safe (matchAll internally advances), but across different
+    // input strings we want a clean start.
+    re.lastIndex = 0;
+    let last = 0;
+    for (const m of chunk.matchAll(re)) {
+      const idx = m.index ?? 0;
+      if (idx > last) out.push(chunk.slice(last, idx));
+      if (m[0].length > 0) out.push(m[0]);
+      last = idx + m[0].length;
+    }
+    if (last < chunk.length) out.push(chunk.slice(last));
+  }
+  return out;
+}
+
+/** UTF-8 bytes of `s`, each mapped to its byte-level visible char. */
+function byteLevelEncode(s: string, byteToChar: string[]): string {
+  const bytes = new TextEncoder().encode(s);
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) out += byteToChar[bytes[i]!];
+  return out;
+}
+
+/**
+ * Standard BPE merge loop. Starts from single byte-level chars and
+ * repeatedly applies the lowest-rank merge until none remain. O(n²)
+ * in chunk length, which is fine because chunks are ≤ a few hundred
+ * byte-level chars after pre-tokenization (and most are <50).
+ */
+function bpeEncode(piece: string, mergeRank: Map<string, number>): string[] {
+  if (piece.length <= 1) return piece ? [piece] : [];
+  let word: string[] = Array.from(piece);
+  while (true) {
+    let bestIdx = -1;
+    let bestRank = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < word.length - 1; i++) {
+      const pair = `${word[i]} ${word[i + 1]}`;
+      const rank = mergeRank.get(pair);
+      if (rank !== undefined && rank < bestRank) {
+        bestRank = rank;
+        bestIdx = i;
+        if (rank === 0) break; // 0 is already the best possible
+      }
+    }
+    if (bestIdx < 0) break;
+    word = [
+      ...word.slice(0, bestIdx),
+      word[bestIdx]! + word[bestIdx + 1]!,
+      ...word.slice(bestIdx + 2),
+    ];
+    if (word.length === 1) break;
+  }
+  return word;
+}
+
+/**
+ * Tokenize a UTF-8 string into DeepSeek token IDs. Mirrors the HF
+ * pipeline: (1) isolate non-special added tokens so they stay atomic,
+ * (2) for each in-between segment run the three Split regexes, (3)
+ * byte-level encode, (4) BPE merge, (5) look up vocab IDs.
+ *
+ * Not reentrancy-hazardous: loads a module-level singleton on first
+ * call and reuses it. Subsequent calls are pure compute.
+ */
+export function encode(text: string): number[] {
+  if (!text) return [];
+  const t = loadTokenizer();
+  const ids: number[] = [];
+
+  const process = (segment: string) => {
+    if (!segment) return;
+    let chunks: string[] = [segment];
+    for (const re of t.splitRegexes) chunks = applySplit(chunks, re);
+    for (const chunk of chunks) {
+      if (!chunk) continue;
+      const byteLevel = byteLevelEncode(chunk, t.byteToChar);
+      const pieces = bpeEncode(byteLevel, t.mergeRank);
+      for (const p of pieces) {
+        const id = t.vocab[p];
+        // If not in vocab we silently skip: shouldn't happen for
+        // byte-level BPE (every single byte has its own vocab entry),
+        // but if a future tokenizer update breaks that invariant we'd
+        // rather under-count than throw from a UI gauge.
+        if (id !== undefined) ids.push(id);
+      }
+    }
+  };
+
+  if (t.addedPattern) {
+    t.addedPattern.lastIndex = 0;
+    let last = 0;
+    for (const m of text.matchAll(t.addedPattern)) {
+      const idx = m.index ?? 0;
+      if (idx > last) process(text.slice(last, idx));
+      const id = t.addedMap.get(m[0]);
+      if (id !== undefined) ids.push(id);
+      last = idx + m[0].length;
+    }
+    if (last < text.length) process(text.slice(last));
+  } else {
+    process(text);
+  }
+  return ids;
+}
+
+/**
+ * Fast path for UI: we only need the count, not the IDs. Saves a
+ * per-call array allocation and lets callers batch large logs
+ * without holding the full ID stream.
+ */
+export function countTokens(text: string): number {
+  return encode(text).length;
+}
+
+/**
+ * Estimate the tokens a full conversation would cost. Sums raw-text
+ * counts for every message's content; we do NOT add overhead for the
+ * chat template's role markers (`<｜User｜>`, `<｜Assistant｜>`) because
+ * the exact framing varies between the chat/reasoner templates and
+ * DeepSeek applies them server-side anyway. Empirically adds ~3-6%
+ * to the real `prompt_tokens` — callers who care can post-multiply.
+ */
+export function estimateConversationTokens(
+  messages: Array<{ content?: string | null; tool_calls?: unknown }>,
+): number {
+  let total = 0;
+  for (const m of messages) {
+    if (typeof m.content === "string" && m.content) {
+      total += countTokens(m.content);
+    }
+    // Tool-call arguments are serialized as JSON in the prompt by the
+    // chat template; their bytes WILL count upstream, so we count
+    // them too. Stringify-once is cheap relative to the tokenize.
+    if (m.tool_calls && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+      total += countTokens(JSON.stringify(m.tool_calls));
+    }
+  }
+  return total;
+}
+
+/**
+ * Estimate the tokens a full DeepSeek request would cost: the
+ * conversation-side tokens (what `estimateConversationTokens` already
+ * counts) PLUS the serialized tool-spec payload. Tool specs ride in
+ * their own JSON blob in the request body, not folded into any
+ * message's `content`, so they need a separate count to land an
+ * accurate preflight estimate.
+ *
+ * Returned number matches what `/context` displays for "next request"
+ * — reuse this helper anywhere (preflight guard, diagnostics, UI) to
+ * keep the two values from drifting.
+ */
+export function estimateRequestTokens(
+  messages: Array<{ content?: string | null; tool_calls?: unknown }>,
+  toolSpecs?: ReadonlyArray<unknown> | null,
+): number {
+  let total = estimateConversationTokens(messages);
+  if (toolSpecs && toolSpecs.length > 0) {
+    total += countTokens(JSON.stringify(toolSpecs));
+  }
+  return total;
+}
+
+/** Exposed for tests — resets the lazy-load singleton. */
+export function _resetForTests(): void {
+  cached = null;
+}

src/tools.ts

@@ -1,3 +1,4 @@
+import { truncateForModel, truncateForModelByTokens } from "./mcp/registry.js";
 import { analyzeSchema, flattenSchema, nestArguments } from "./repair/flatten.js";
 import type { JSONSchema, ToolSpec } from "./types.js";
 
@@ -17,6 +18,25 @@ export interface ToolDefinition<A = any, R = any> {
   name: string;
   description?: string;
   parameters?: JSONSchema;
+  /**
+   * Marks a tool as read-only: safe to invoke during plan mode. `true`
+   * for tools that only observe (read_file, list_directory, search, web
+   * fetch/search). Leave undefined / `false` for anything that can write,
+   * execute, or mutate state.
+   *
+   * The registry enforces this at dispatch: non-readonly tools called
+   * while `planMode` is on return a refusal string the model can
+   * learn from, instead of actually running.
+   */
+  readOnly?: boolean;
+  /**
+   * Dynamic read-only check for tools whose safety depends on arguments
+   * — `run_command` with an allowlisted argv is safe, `run_command
+   * rm -rf` isn't. Called with the parsed arguments; `true` means "treat
+   * as read-only for plan mode". Takes precedence over `readOnly` when
+   * both are set.
+   */
+  readOnlyCheck?: (args: A) => boolean;
   fn: (args: A, ctx?: ToolCallContext) => R | Promise<R>;
 }
 
@@ -42,11 +62,29 @@ export interface ToolRegistryOptions {
 export class ToolRegistry {
   private readonly _tools = new Map<string, InternalTool>();
   private readonly _autoFlatten: boolean;
+  /**
+   * When true, `dispatch` refuses any tool whose `readOnly` flag isn't
+   * set (and whose `readOnlyCheck` doesn't pass on the specific args).
+   * Drives `reasonix code`'s Plan Mode — the model can still explore
+   * via read tools but its writes and non-allowlisted shell calls are
+   * bounced until the user approves a submitted plan.
+   */
+  private _planMode = false;
 
   constructor(opts: ToolRegistryOptions = {}) {
     this._autoFlatten = opts.autoFlatten !== false;
   }
 
+  /** Enable / disable plan-mode enforcement at dispatch. */
+  setPlanMode(on: boolean): void {
+    this._planMode = Boolean(on);
+  }
+
+  /** True when the registry is currently refusing non-readonly calls. */
+  get planMode(): boolean {
+    return this._planMode;
+  }
+
   register<A, R>(def: ToolDefinition<A, R>): this {
     if (!def.name) throw new Error("tool requires a name");
     const internal: InternalTool = { ...(def as ToolDefinition) };
@@ -91,7 +129,7 @@ export class ToolRegistry {
   async dispatch(
     name: string,
     argumentsRaw: string | Record<string, unknown>,
-    opts: { signal?: AbortSignal } = {},
+    opts: { signal?: AbortSignal; maxResultChars?: number; maxResultTokens?: number } = {},
   ): Promise<string> {
     const tool = this._tools.get(name);
     if (!tool) {
@@ -120,17 +158,67 @@ export class ToolRegistry {
       args = nestArguments(args);
     }
 
+    // Plan-mode enforcement — runs AFTER arg parsing so a tool with a
+    // runtime `readOnlyCheck` can inspect the actual args (e.g.
+    // `run_command` is read-only iff the command matches its allowlist).
+    if (this._planMode && !isReadOnlyCall(tool, args)) {
+      return JSON.stringify({
+        error: `${name}: unavailable in plan mode — this is a read-only exploration phase. Use read_file / list_directory / search_files / directory_tree / web_search / allowlisted shell commands to investigate. Call submit_plan with your proposed plan when you're ready for the user's review.`,
+      });
+    }
+
     try {
       const result = await tool.fn(args, { signal: opts.signal });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const str = typeof result === "string" ? result : JSON.stringify(result);
+      // Pre-clip at dispatch so a single fat result can't balloon the
+      // log (and disk session file) on its way in. Healing at load time
+      // still catches pre-existing oversize entries; this closes the
+      // door on new ones.
+      //
+      // Two caps available: `maxResultTokens` (preferred — bounds the
+      // real context footprint, so CJK doesn't slip past at 2× density)
+      // and `maxResultChars` (legacy). If both are set, apply both and
+      // the tighter one wins; char-only callers keep their old behavior.
+      let clipped = str;
+      if (opts.maxResultTokens !== undefined) {
+        clipped = truncateForModelByTokens(clipped, opts.maxResultTokens);
+      }
+      if (opts.maxResultChars !== undefined) {
+        clipped = truncateForModel(clipped, opts.maxResultChars);
+      }
+      return clipped;
     } catch (err) {
+      const e = err as Error & { toToolResult?: () => unknown };
+      // Errors may opt into a richer tool-result shape by implementing
+      // `toToolResult()`. Used by `PlanProposedError` to smuggle the
+      // submitted plan text out to the UI without stuffing it into the
+      // error message (which the dispatcher truncates at no fixed limit,
+      // but keeping payloads structured is cleaner for UI parsing).
+      if (typeof e.toToolResult === "function") {
+        try {
+          return JSON.stringify(e.toToolResult());
+        } catch {
+          /* fall through to the default shape */
+        }
+      }
       return JSON.stringify({
-        error: `${(err as Error).name}: ${(err as Error).message}`,
+        error: `${e.name}: ${e.message}`,
       });
     }
   }
 }
 
+function isReadOnlyCall(tool: InternalTool, args: Record<string, unknown>): boolean {
+  if (tool.readOnlyCheck) {
+    try {
+      return Boolean(tool.readOnlyCheck(args as never));
+    } catch {
+      return false;
+    }
+  }
+  return tool.readOnly === true;
+}
+
 function hasDotKey(obj: Record<string, unknown>): boolean {
   for (const k of Object.keys(obj)) {
     if (k.includes(".")) return true;

src/tools/filesystem.ts

@@ -48,6 +48,88 @@ export interface FilesystemToolsOptions {
 const DEFAULT_MAX_READ_BYTES = 2 * 1024 * 1024;
 const DEFAULT_MAX_LIST_BYTES = 256 * 1024;
 
+/**
+ * Directory names skipped by `search_content` unless `include_deps:true`
+ * is passed. The intent is "user is asking about THEIR code, not the
+ * libraries they depend on" — vendored / generated trees would otherwise
+ * dominate every match list. Pass include_deps when you genuinely need
+ * to grep a dependency.
+ */
+const SKIP_DIR_NAMES: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "target", // Rust / Java
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".cache",
+  "coverage",
+]);
+
+/**
+ * Cheap binary-by-extension check for `search_content`. We err on the
+ * side of skipping so a NUL-byte content sniff is the second line of
+ * defense (handles e.g. a `.txt` that's actually a binary dump).
+ */
+const BINARY_EXTENSIONS: ReadonlySet<string> = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".ico",
+  ".webp",
+  ".tiff",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".bin",
+  ".class",
+  ".jar",
+  ".war",
+  ".o",
+  ".obj",
+  ".lib",
+  ".a",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".mp3",
+  ".mp4",
+  ".mov",
+  ".avi",
+  ".webm",
+  ".wasm",
+  ".pyc",
+  ".pyo",
+]);
+
+function isLikelyBinaryByName(name: string): boolean {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0) return false;
+  return BINARY_EXTENSIONS.has(name.slice(dot).toLowerCase());
+}
+
 export function registerFilesystemTools(
   registry: ToolRegistry,
   opts: FilesystemToolsOptions,
@@ -62,8 +144,22 @@ export function registerFilesystemTools(
     if (typeof raw !== "string" || raw.length === 0) {
       throw new Error("path must be a non-empty string");
     }
-    // Interpret relative paths against rootDir (the session's scope).
-    const resolved = pathMod.resolve(rootDir, raw);
+    // Sandbox-root semantics: a leading POSIX-style `/` (or `\` on
+    // Windows) means "from the project root", not "from the filesystem
+    // root". Models routinely write `path: "/"` or `path: "/src/foo.ts"`
+    // intending the sandbox root — without this normalization,
+    // path.resolve interprets `/` as the actual drive root (`F:\` on
+    // Windows, `/` on POSIX) and the escape check rightly rejects it,
+    // confusing the model. Strip leading separators so the rest of the
+    // resolution treats the input as relative to rootDir. Drive-letter
+    // absolutes (`C:\foo`) and Unix absolutes outside rootDir still
+    // get caught by the relative-escape check below.
+    let normalized = raw;
+    while (normalized.startsWith("/") || normalized.startsWith("\\")) {
+      normalized = normalized.slice(1);
+    }
+    if (normalized.length === 0) normalized = ".";
+    const resolved = pathMod.resolve(rootDir, normalized);
     const normRoot = pathMod.resolve(rootDir);
     // Use relative() to catch any `..` segments that escape.
     const rel = pathMod.relative(normRoot, resolved);
@@ -77,6 +173,7 @@ export function registerFilesystemTools(
     name: "read_file",
     description:
       "Read a file under the sandbox root. Returns the full contents (truncated with a notice if larger than the per-call cap). Paths may be relative to the root or absolute-under-root.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -117,6 +214,7 @@ export function registerFilesystemTools(
     name: "list_directory",
     description:
       "List entries in a directory under the sandbox root. Returns one line per entry, marking directories with a trailing slash. Not recursive — use directory_tree for that.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -138,6 +236,7 @@ export function registerFilesystemTools(
     name: "directory_tree",
     description:
       "Recursively list entries in a directory. Shows indented tree structure with directories marked '/'. Caps output so a huge tree doesn't drown the context.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -186,6 +285,7 @@ export function registerFilesystemTools(
     name: "search_files",
     description:
       "Find files whose NAME matches a substring or regex. Case-insensitive. Walks the directory recursively under the sandbox root. Returns one path per line.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -239,10 +339,144 @@ export function registerFilesystemTools(
     },
   });
 
+  registry.register({
+    name: "search_content",
+    description:
+      "Recursively grep file CONTENTS for a substring or regex. This is the right tool for 'find all places that call X', 'where is Y referenced', 'what files contain Z'. Different from search_files (which matches FILE NAMES). Returns one match per line in 'path:line: text' format. Skips dependency / VCS / build directories (node_modules, .git, dist, build, .next, target, .venv) and binary files by default.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: {
+          type: "string",
+          description: "Substring (or regex) to search file contents for.",
+        },
+        path: {
+          type: "string",
+          description: "Directory to start the search at (default: sandbox root).",
+        },
+        glob: {
+          type: "string",
+          description:
+            "Optional file-name suffix or substring filter. Examples: '.ts' (only TypeScript), 'test' (any file with 'test' in the name). Reduces noise when you know the file shape.",
+        },
+        case_sensitive: {
+          type: "boolean",
+          description: "When true, match case exactly. Default false (case-insensitive).",
+        },
+        include_deps: {
+          type: "boolean",
+          description:
+            "When true, also search inside node_modules / .git / dist / build / etc. Off by default — most exploration questions are about the user's own code.",
+        },
+      },
+      required: ["pattern"],
+    },
+    fn: async (args: {
+      pattern: string;
+      path?: string;
+      glob?: string;
+      case_sensitive?: boolean;
+      include_deps?: boolean;
+    }) => {
+      const startAbs = safePath(args.path ?? ".");
+      const caseSensitive = args.case_sensitive === true;
+      const includeDeps = args.include_deps === true;
+      const nameFilter = typeof args.glob === "string" ? args.glob.toLowerCase() : null;
+      // Try the pattern as a regex first (lets the model say `\bdispatch\(`
+      // for a word-bounded match); fall back to literal substring on
+      // invalid regex. No `g` flag — we test once per line, so global
+      // statefulness (lastIndex tracking) would just be noise.
+      let re: RegExp | null = null;
+      try {
+        re = new RegExp(args.pattern, caseSensitive ? "" : "i");
+      } catch {
+        re = null;
+      }
+      const needle = caseSensitive ? args.pattern : args.pattern.toLowerCase();
+      const matches: string[] = [];
+      let totalBytes = 0;
+      let scanned = 0;
+      let truncated = false;
+
+      const walk = async (dir: string): Promise<void> => {
+        if (truncated) return;
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        for (const e of entries) {
+          if (truncated) return;
+          if (e.isDirectory()) {
+            if (!includeDeps && SKIP_DIR_NAMES.has(e.name)) continue;
+            await walk(pathMod.join(dir, e.name));
+            continue;
+          }
+          if (!e.isFile()) continue;
+          if (nameFilter && !e.name.toLowerCase().includes(nameFilter)) continue;
+          if (isLikelyBinaryByName(e.name)) continue;
+          const full = pathMod.join(dir, e.name);
+          let stat: import("node:fs").Stats;
+          try {
+            stat = await fs.stat(full);
+          } catch {
+            continue;
+          }
+          // Per-file size cap so a 50MB log doesn't dominate the search.
+          // Anything legitimately interesting fits in 2 MB; bigger files
+          // are usually data dumps or generated bundles.
+          if (stat.size > 2 * 1024 * 1024) continue;
+          let raw: Buffer;
+          try {
+            raw = await fs.readFile(full);
+          } catch {
+            continue;
+          }
+          // Content-based binary sniff: a NUL byte in the first 8KB is
+          // a strong indicator. Catches binaries with .json or .txt
+          // extensions (yes, this happens).
+          const firstNul = raw.indexOf(0);
+          if (firstNul !== -1 && firstNul < 8 * 1024) continue;
+          const text = raw.toString("utf8");
+          const rel = pathMod.relative(rootDir, full);
+          const lines = text.split(/\r?\n/);
+          for (let li = 0; li < lines.length; li++) {
+            const line = lines[li]!;
+            const lineForCheck = caseSensitive ? line : line.toLowerCase();
+            const hit = re ? re.test(line) : lineForCheck.includes(needle);
+            if (!hit) continue;
+            // Truncate very long lines so one giant minified file
+            // doesn't blow the budget on a single match.
+            const display = line.length > 200 ? `${line.slice(0, 200)}…` : line;
+            const out = `${rel}:${li + 1}: ${display}`;
+            if (totalBytes + out.length + 1 > maxListBytes) {
+              matches.push(`[… truncated at ${maxListBytes} bytes — refine pattern or path …]`);
+              truncated = true;
+              return;
+            }
+            matches.push(out);
+            totalBytes += out.length + 1;
+          }
+          scanned++;
+        }
+      };
+      await walk(startAbs);
+      if (matches.length === 0) {
+        return scanned === 0
+          ? "(no files scanned — path empty or all files filtered out)"
+          : `(no matches across ${scanned} file${scanned === 1 ? "" : "s"})`;
+      }
+      return matches.join("\n");
+    },
+  });
+
   registry.register({
     name: "get_file_info",
     description:
       "Stat a path under the sandbox root. Returns type (file|directory|symlink), size in bytes, mtime in ISO-8601.",
+    readOnly: true,
     parameters: {
       type: "object",
       properties: {
@@ -287,7 +521,7 @@ export function registerFilesystemTools(
   registry.register({
     name: "edit_file",
     description:
-      "Apply a SEARCH/REPLACE edit to an existing file. `search` must match exactly (whitespace sensitive) — no regex. The match must be unique in the file; otherwise the edit is refused to avoid surprise rewrites. This flat-string shape replaces the `{oldText, newText}[]` JSON array form that previously triggered R1 DSML hallucinations.",
+      "Apply a SEARCH/REPLACE edit to an existing file. `search` must match exactly (whitespace sensitive) — no regex. The match must be unique in the file; otherwise the edit is refused to avoid surprise rewrites.",
     parameters: {
       type: "object",
       properties: {

src/tools/memory.ts

@@ -0,0 +1,180 @@
+/**
+ * `remember` / `forget` / `recall_memory` — tools that let the model
+ * read and write the user-memory store across sessions.
+ *
+ * Scope rules:
+ *   - `global`  — always available (no sandbox needed).
+ *   - `project` — requires a `projectRoot` on MemoryStore. In chat mode
+ *     (no sandbox), the tools still register but a `scope=project` call
+ *     returns a structured refusal so the model can try `global` instead.
+ *
+ * Memory changes are written eagerly but NOT re-loaded into the prefix
+ * mid-session (cache invariant). The user notices at `/new` or the next
+ * launch — or they can read fresh content via `recall_memory` which
+ * always hits disk.
+ */
+
+import type { ToolRegistry } from "../tools.js";
+import {
+  type MemoryScope,
+  MemoryStore,
+  type MemoryType,
+  sanitizeMemoryName,
+} from "../user-memory.js";
+
+export interface MemoryToolsOptions {
+  /** Sandbox root for the `project` scope. Omit for chat mode. */
+  projectRoot?: string;
+  /** Override `~/.reasonix` (tests). */
+  homeDir?: string;
+}
+
+export function registerMemoryTools(
+  registry: ToolRegistry,
+  opts: MemoryToolsOptions = {},
+): ToolRegistry {
+  const store = new MemoryStore({ homeDir: opts.homeDir, projectRoot: opts.projectRoot });
+  const hasProject = store.hasProjectScope();
+
+  registry.register({
+    name: "remember",
+    description:
+      "Save a memory for future sessions. Use when the user states a preference, corrects your approach, shares a non-obvious fact about this project, or explicitly asks you to remember something. Don't remember transient task state — only things worth recalling next session. The memory is written now but won't re-load into the system prompt until the next `/new` or launch.",
+    parameters: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["user", "feedback", "project", "reference"],
+          description:
+            "'user' = role/skills/prefs; 'feedback' = corrections or confirmed approaches; 'project' = facts/decisions about the current work; 'reference' = pointers to external systems the user uses.",
+        },
+        scope: {
+          type: "string",
+          enum: ["global", "project"],
+          description:
+            "'global' = applies across every project (preferences, tooling); 'project' = scoped to the current sandbox (decisions, local facts). Only available in `reasonix code`.",
+        },
+        name: {
+          type: "string",
+          description:
+            "filename-safe identifier, 3-40 chars, alnum + _ - . (no path separators, no leading dot).",
+        },
+        description: {
+          type: "string",
+          description: "One-line summary shown in MEMORY.md (under ~150 chars).",
+        },
+        content: {
+          type: "string",
+          description:
+            "Full memory body in markdown. For feedback/project types, structure as: rule/fact, then **Why:** line, then **How to apply:** line.",
+        },
+      },
+      required: ["type", "scope", "name", "description", "content"],
+    },
+    fn: async (args: {
+      type: MemoryType;
+      scope: MemoryScope;
+      name: string;
+      description: string;
+      content: string;
+    }) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error:
+            "scope='project' is unavailable in this session (no sandbox root). Retry with scope='global', or ask the user to switch to `reasonix code` for project-scoped memory.",
+        });
+      }
+      try {
+        const path = store.write({
+          name: args.name,
+          type: args.type,
+          scope: args.scope,
+          description: args.description,
+          body: args.content,
+        });
+        const key = sanitizeMemoryName(args.name);
+        // The return text is load-bearing: it's the ONLY thing keeping
+        // the fact visible within the current session, because the
+        // prefix isn't re-hashed mid-session (Pillar 1). R1 reads this
+        // on its next turn — the wording is deliberately imperative so
+        // it doesn't get ignored in favor of explore-first behavior.
+        return [
+          `✓ REMEMBERED (${args.scope}/${key}): ${args.description}`,
+          "",
+          "TREAT THIS AS ESTABLISHED FACT for the rest of this session.",
+          "The user just told you — don't re-explore the filesystem to re-derive it.",
+          `(Saved to ${path}; pins into the system prompt on next /new or launch.)`,
+        ].join("\n");
+      } catch (err) {
+        return JSON.stringify({ error: `remember failed: ${(err as Error).message}` });
+      }
+    },
+  });
+
+  registry.register({
+    name: "forget",
+    description:
+      "Delete a memory file and remove it from MEMORY.md. Use when the user explicitly asks to forget something, or when a previously-remembered fact has become wrong. Irreversible — no tombstone.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Memory name (the identifier used in `remember`)." },
+        scope: { type: "string", enum: ["global", "project"] },
+      },
+      required: ["name", "scope"],
+    },
+    fn: async (args: { name: string; scope: MemoryScope }) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error: "scope='project' is unavailable in this session (no sandbox root).",
+        });
+      }
+      try {
+        const existed = store.delete(args.scope, args.name);
+        return existed
+          ? `forgot (${args.scope}/${sanitizeMemoryName(args.name)}). Re-load on next /new or launch.`
+          : `no such memory: ${args.scope}/${args.name} (nothing to forget).`;
+      } catch (err) {
+        return JSON.stringify({ error: `forget failed: ${(err as Error).message}` });
+      }
+    },
+  });
+
+  registry.register({
+    name: "recall_memory",
+    description:
+      "Read the full body of a memory file when its MEMORY.md one-liner (already in the system prompt) isn't enough detail. Most of the time the index suffices — only call this when the user's question genuinely requires the full context.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        scope: { type: "string", enum: ["global", "project"] },
+      },
+      required: ["name", "scope"],
+    },
+    fn: async (args: { name: string; scope: MemoryScope }) => {
+      if (args.scope === "project" && !hasProject) {
+        return JSON.stringify({
+          error: "scope='project' is unavailable in this session (no sandbox root).",
+        });
+      }
+      try {
+        const entry = store.read(args.scope, args.name);
+        return [
+          `# ${entry.name}  (${entry.scope}/${entry.type}, created ${entry.createdAt || "?"})`,
+          entry.description ? `> ${entry.description}` : "",
+          "",
+          entry.body,
+        ]
+          .filter(Boolean)
+          .join("\n");
+      } catch (err) {
+        return JSON.stringify({ error: `recall failed: ${(err as Error).message}` });
+      }
+    },
+  });
+
+  return registry;
+}

src/tools/plan.ts

@@ -0,0 +1,101 @@
+/**
+ * Plan Mode — read-only exploration phase for `reasonix code`.
+ *
+ * Shape (mirrors claude-code's plan/act split, adapted for Reasonix):
+ *
+ *   1. User types `/plan` → registry switches to plan-mode enforcement
+ *      (write tools refused at dispatch; reads + allowlisted shell
+ *      still work).
+ *   2. Model explores, then calls `submit_plan` with a markdown plan.
+ *   3. `submit_plan` throws `PlanProposedError`, which the TUI renders
+ *      as a picker: Approve / Refine / Cancel.
+ *   4. Approve → registry leaves plan mode, a synthetic user message
+ *      "The plan has been approved. Implement it now." is pushed into
+ *      the loop so the next turn executes.
+ *
+ * The read-only enforcement lives in `ToolRegistry.dispatch` via
+ * `readOnly` / `readOnlyCheck`; this file only ships the `submit_plan`
+ * escape hatch and the error type that carries the plan out of the
+ * registry without stuffing it into the message.
+ *
+ * We do not change `ImmutablePrefix.toolSpecs` when plan mode toggles —
+ * that would break Pillar 1's prefix cache. Instead the same full spec
+ * list stays pinned, and the registry enforces mode at dispatch time.
+ * The refusal string teaches the model the rule; cache hits stay
+ * intact.
+ */
+
+import type { ToolRegistry } from "../tools.js";
+
+/**
+ * Thrown by `submit_plan` when plan mode is active, carrying the plan
+ * text the TUI will render for the user's approval.
+ *
+ * Implements the `toToolResult` protocol so `ToolRegistry.dispatch`
+ * serializes the full plan into the tool-result JSON (not just the
+ * error message). The TUI parses `{ error, plan }` from the tool event
+ * and mounts the `PlanConfirm` picker.
+ */
+export class PlanProposedError extends Error {
+  readonly plan: string;
+  constructor(plan: string) {
+    super(
+      "PlanProposedError: plan submitted. STOP calling tools now — the TUI has shown the plan to the user. Wait for their next message; it will either approve (you'll then implement the plan), request a refinement (you should explore more and submit an updated plan), or cancel (drop the plan and ask what they want instead). Don't call any tools in the meantime.",
+    );
+    this.name = "PlanProposedError";
+    this.plan = plan;
+  }
+
+  /**
+   * Structured tool-result shape. Consumed by the TUI to extract the
+   * plan without regex-scraping the error message.
+   */
+  toToolResult(): { error: string; plan: string } {
+    return { error: `${this.name}: ${this.message}`, plan: this.plan };
+  }
+}
+
+export interface PlanToolOptions {
+  /**
+   * Optional side-channel callback fired when the model submits a plan.
+   * The TUI uses this to preview the plan in real time (the tool-result
+   * event is also emitted; this is just earlier and friendlier to
+   * test harnesses that don't want to parse JSON).
+   */
+  onPlanSubmitted?: (plan: string) => void;
+}
+
+export function registerPlanTool(registry: ToolRegistry, opts: PlanToolOptions = {}): ToolRegistry {
+  registry.register({
+    name: "submit_plan",
+    description:
+      "Submit a concrete plan to the user for review before executing. Use this for tasks that warrant a review gate — multi-file refactors, architecture changes, anything that would be expensive or confusing to undo. Skip it for small fixes (one-line typo, obvious bug with a clear fix) — just make the change. The user will either approve (you then implement it), ask for refinement, or cancel. If the user has already enabled /plan mode, writes are blocked at dispatch and you MUST use this. Write the plan as markdown with a one-line summary, a bulleted list of files to touch and what will change, and any risks or open questions.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        plan: {
+          type: "string",
+          description:
+            "Markdown-formatted plan. Lead with a one-sentence summary. Then a file-by-file breakdown of what you'll change and why. Flag any risks or open questions at the end so the user can weigh in before you start.",
+        },
+      },
+      required: ["plan"],
+    },
+    fn: async (args: { plan: string }) => {
+      const plan = (args?.plan ?? "").trim();
+      if (!plan) {
+        throw new Error("submit_plan: empty plan — write a markdown plan and try again.");
+      }
+      // Always fire the picker, not just inside plan mode. Plan mode's
+      // role is the *stronger* constraint — it forces you into read-only
+      // until you submit. Outside plan mode, submit_plan is your own
+      // call: use it when the task is large enough to deserve a review
+      // gate (multi-file refactors, architecture changes, anything
+      // that would be expensive to undo), skip it for small fixes.
+      opts.onPlanSubmitted?.(plan);
+      throw new PlanProposedError(plan);
+    },
+  });
+  return registry;
+}

src/tools/shell.ts

@@ -0,0 +1,646 @@
+/**
+ * Native shell tool — lets the model run commands inside the sandbox
+ * root so it can actually verify its own work (run tests, check git
+ * status, inspect a lockfile, etc.). Without this the coding-mode
+ * loop is "write code, hope it works, ask the user to run it" —
+ * defeats the purpose.
+ *
+ * Safety model:
+ *   - Commands run with `cwd` pinned to the registered root. No
+ *     path traversal via the command itself is enforced (users can
+ *     `cat ../outside.txt`); the trust boundary is the directory
+ *     you opened Reasonix from.
+ *   - Commands are matched against a read-only / testing allowlist.
+ *     Allowlisted commands execute immediately and return stdout +
+ *     stderr merged. Everything else throws with a clear message —
+ *     the UI translates that into an `/apply`-style confirm gate so
+ *     the user sees the exact command before it runs.
+ *   - Default timeout: 60s. Output cap: matches tool-result budget.
+ *   - Every command that DOES run is spawned with `shell: false` and
+ *     a tokenized argv — no string-to-shell interpolation, so the
+ *     model can't accidentally construct a chained `rm` via quoting.
+ *
+ * This is intentionally narrower than what Claude Code / Aider ship:
+ * we gate more commands behind confirmation by default. Users who
+ * trust the model can widen the allowlist by instantiating their
+ * own tool registry.
+ */
+
+import { type SpawnOptions, spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import * as pathMod from "node:path";
+import type { ToolRegistry } from "../tools.js";
+
+export interface ShellToolsOptions {
+  /** Directory to run commands in. Must be an absolute path. */
+  rootDir: string;
+  /** Seconds before an individual command is killed. Default: 60. */
+  timeoutSec?: number;
+  /**
+   * Per-command stdout+stderr cap in characters. Default: 32_000 to
+   * match the tool-result budget.
+   */
+  maxOutputChars?: number;
+  /**
+   * Extra command-name prefixes the user explicitly trusts. Added on
+   * top of the built-in allowlist. Examples: `["my-ci-script", "lint"]`.
+   *
+   * Accepts either a fixed array (captured once at registration) or a
+   * getter called on every dispatch. The getter form is load-bearing:
+   * when the TUI's `ShellConfirm` writes a new prefix to config mid-
+   * session, the running `run_command` must pick it up immediately —
+   * otherwise the same command gets re-prompted until the next launch.
+   */
+  extraAllowed?: readonly string[] | (() => readonly string[]);
+  /**
+   * When true, skip the allowlist entirely and auto-run every command.
+   * Off by default — this is an escape hatch for non-interactive use
+   * (CI, benchmarks) where a human can't be in the loop to confirm.
+   */
+  allowAll?: boolean;
+}
+
+const DEFAULT_TIMEOUT_SEC = 60;
+const DEFAULT_MAX_OUTPUT_CHARS = 32_000;
+
+/**
+ * Command prefixes we consider safe to run without asking the user.
+ * Rule of thumb: read-only reports, or test runners whose failure mode
+ * is "exit 1 with output." Nothing that can rewrite state, escalate,
+ * or touch the network.
+ */
+const BUILTIN_ALLOWLIST: ReadonlyArray<string> = [
+  // Repo inspection
+  "git status",
+  "git diff",
+  "git log",
+  "git show",
+  "git blame",
+  "git branch",
+  "git remote",
+  "git rev-parse",
+  "git config --get",
+  // Filesystem inspection
+  "ls",
+  "pwd",
+  "cat",
+  "head",
+  "tail",
+  "wc",
+  "file",
+  "tree",
+  "find",
+  "grep",
+  "rg",
+  // Language version probes
+  "node --version",
+  "node -v",
+  "npm --version",
+  "npx --version",
+  "python --version",
+  "python3 --version",
+  "cargo --version",
+  "go version",
+  "rustc --version",
+  "deno --version",
+  "bun --version",
+  // Test runners (non-destructive by convention)
+  "npm test",
+  "npm run test",
+  "npx vitest run",
+  "npx vitest",
+  "npx jest",
+  "pytest",
+  "python -m pytest",
+  "cargo test",
+  "cargo check",
+  "cargo clippy",
+  "go test",
+  "go vet",
+  "deno test",
+  "bun test",
+  // Linters / typecheckers (read-only by convention)
+  "npm run lint",
+  "npm run typecheck",
+  "npx tsc --noEmit",
+  "npx biome check",
+  "npx eslint",
+  "npx prettier --check",
+  "ruff",
+  "mypy",
+];
+
+/**
+ * Tokenize a shell-ish command string into argv. Handles single/double
+ * quoting; rejects unclosed quotes. Does NOT expand env vars, globs,
+ * backticks, or `$(…)` — the goal is to prevent the model from
+ * accidentally (or not) sneaking arbitrary shells past the allowlist
+ * via concatenation. Exported for testing.
+ */
+export function tokenizeCommand(cmd: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i]!;
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else if (ch === "\\" && quote === '"' && i + 1 < cmd.length) {
+        cur += cmd[++i];
+      } else {
+        cur += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      if (cur.length > 0) {
+        out.push(cur);
+        cur = "";
+      }
+      continue;
+    }
+    cur += ch;
+  }
+  if (quote) throw new Error(`unclosed ${quote} in command`);
+  if (cur.length > 0) out.push(cur);
+  return out;
+}
+
+/**
+ * Scan `cmd` for a shell operator (`|`, `||`, `>`, `>>`, `<`, `<<`,
+ * `&`, `&&`, `2>`, `2>>`, `2>&1`, `&>`) that appears unquoted at a
+ * token boundary. Returns the operator string, or null if none.
+ *
+ * Why this exists: `run_command` documents "no shell expansion, no
+ * pipes, no redirects" (the tool spawns argv directly, not through a
+ * shell), but when the model writes `dir | findstr foo` the `|`
+ * survives tokenization as a standalone token and gets quoted as the
+ * literal string `"|"` by `quoteForCmdExe` — cmd.exe sees it as an
+ * argument, not an operator, so the pipe silently fails. Detecting
+ * operators up front lets us throw a clear error ("split into separate
+ * calls") instead of letting the command run with surprising results.
+ *
+ * Quoted operators (`grep "a|b"`) and operator characters embedded in
+ * larger tokens (`--flag=1&2`) are NOT flagged — those are literal
+ * argv bytes and are safe to pass through.
+ *
+ * Exported for testing.
+ */
+export function detectShellOperator(cmd: string): string | null {
+  const opPrefix = /^(?:2>&1|&>|\|{1,2}|&{1,2}|2>{1,2}|>{1,2}|<{1,2})/;
+  let cur = "";
+  let curQuoted = false;
+  let quote: '"' | "'" | null = null;
+  const check = (): string | null => {
+    if (cur.length === 0 && !curQuoted) return null;
+    if (!curQuoted) {
+      const m = opPrefix.exec(cur);
+      if (m) return m[0] ?? null;
+    }
+    return null;
+  };
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i]!;
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else if (ch === "\\" && quote === '"' && i + 1 < cmd.length) {
+        cur += cmd[++i];
+        curQuoted = true;
+      } else {
+        cur += ch;
+        curQuoted = true;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      curQuoted = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      const op = check();
+      if (op) return op;
+      cur = "";
+      curQuoted = false;
+      continue;
+    }
+    cur += ch;
+  }
+  if (quote) return null; // let tokenizeCommand throw the unclosed-quote error
+  return check();
+}
+
+/**
+ * Return true when `cmd` matches an allowlisted prefix. Exported for
+ * testing. Match is on the space-normalized leading tokens so
+ * `git   status  -s ` and `git status` both match `git status`.
+ */
+export function isAllowed(cmd: string, extra: readonly string[] = []): boolean {
+  const normalized = cmd.trim().replace(/\s+/g, " ");
+  const allowlist = [...BUILTIN_ALLOWLIST, ...extra];
+  for (const prefix of allowlist) {
+    if (normalized === prefix) return true;
+    if (normalized.startsWith(`${prefix} `)) return true;
+  }
+  return false;
+}
+
+export interface RunCommandResult {
+  exitCode: number | null;
+  /** Combined stdout+stderr, truncated to `maxOutputChars` with a marker. */
+  output: string;
+  /** True when the process was killed for exceeding `timeoutSec`. */
+  timedOut: boolean;
+}
+
+export async function runCommand(
+  cmd: string,
+  opts: {
+    cwd: string;
+    timeoutSec?: number;
+    maxOutputChars?: number;
+    signal?: AbortSignal;
+  },
+): Promise<RunCommandResult> {
+  const argv = tokenizeCommand(cmd);
+  if (argv.length === 0) throw new Error("run_command: empty command");
+  const operator = detectShellOperator(cmd);
+  if (operator !== null) {
+    throw new Error(
+      `run_command: shell operator "${operator}" is not supported — this tool spawns one process, no shell expansion. Split into separate run_command calls and combine the output in your reasoning (e.g. instead of \`grep foo *.ts | wc -l\`, call \`grep -c foo *.ts\` or two separate commands). To pass "${operator}" as a literal argument, wrap it in quotes.`,
+    );
+  }
+  const timeoutMs = (opts.timeoutSec ?? DEFAULT_TIMEOUT_SEC) * 1000;
+  const maxChars = opts.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+
+  const spawnOpts: SpawnOptions = {
+    cwd: opts.cwd,
+    shell: false, // no shell-expansion — see header comment
+    windowsHide: true,
+    env: process.env,
+  };
+
+  // Windows: two layered fixes on top of shell:false —
+  //   1. Resolve bare command names via PATH × PATHEXT (CreateProcess
+  //      ignores PATHEXT, so `npm` alone misses `npm.cmd`).
+  //   2. Node 21.7.3+ (CVE-2024-27980) refuses to spawn `.cmd`/`.bat`
+  //      directly even with shell:false and safe args — throws
+  //      EINVAL at invocation time. Wrap those via `cmd.exe /d /s /c`
+  //      with verbatim args + manual quoting, so shell metacharacters
+  //      in arguments stay literal.
+  // Unix path is unchanged.
+  const { bin, args, spawnOverrides } = prepareSpawn(argv);
+  const effectiveSpawnOpts = { ...spawnOpts, ...spawnOverrides };
+
+  return await new Promise<RunCommandResult>((resolve, reject) => {
+    let child: import("node:child_process").ChildProcess;
+    try {
+      child = spawn(bin, args, effectiveSpawnOpts);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let buf = "";
+    let timedOut = false;
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    const onAbort = () => child.kill("SIGKILL");
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+    const onData = (chunk: Buffer | string) => {
+      buf += chunk.toString();
+      // Soft cap: we let the process keep running (killing early could
+      // hide a real failure), but we stop growing the buffer past 2×
+      // the cap so a chatty test can't OOM us.
+      if (buf.length > maxChars * 2) buf = `${buf.slice(0, maxChars * 2)}`;
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    child.on("error", (err) => {
+      clearTimeout(killTimer);
+      opts.signal?.removeEventListener("abort", onAbort);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(killTimer);
+      opts.signal?.removeEventListener("abort", onAbort);
+      const output =
+        buf.length > maxChars
+          ? `${buf.slice(0, maxChars)}\n\n[… truncated ${buf.length - maxChars} chars …]`
+          : buf;
+      resolve({ exitCode: code, output, timedOut });
+    });
+  });
+}
+
+/**
+ * Test/override hooks for {@link resolveExecutable}. Omitting any field
+ * falls through to the real process globals — the runtime call path
+ * uses defaults; tests inject `platform` + `env` + `isFile` to exercise
+ * Windows-specific lookup from a Linux CI runner without touching
+ * actual fs.
+ */
+export interface ResolveExecutableOptions {
+  platform?: NodeJS.Platform;
+  env?: { PATH?: string; PATHEXT?: string };
+  /** Predicate swapped in by tests to avoid creating real files. */
+  isFile?: (path: string) => boolean;
+  /** Path.join used for the lookup. Defaults to Windows semantics on Windows. */
+  pathDelimiter?: string;
+}
+
+/**
+ * Resolve a bare command name (e.g. `npm`) to its on-disk path via
+ * PATH × PATHEXT on Windows. Returns the input unchanged on non-Windows
+ * platforms, when the input is already a path (contains `/`, `\`, or is
+ * absolute), or when no match is found in PATH × PATHEXT (caller gets a
+ * natural ENOENT from spawn, which surfaces cleanly).
+ *
+ * Why this exists: `child_process.spawn` with `shell: false` invokes
+ * Windows `CreateProcess`, which does not honor `PATHEXT` and does not
+ * search for `.cmd` / `.bat` wrappers. Node-ecosystem tools ship as
+ * `npm.cmd`, `npx.cmd`, `yarn.cmd`, etc., so a bare `npm` fails with
+ * ENOENT under `shell: false`. Flipping to `shell: true` would work
+ * but reintroduces shell-expansion (pipes, redirects, chained cmds)
+ * that the tool was explicitly designed to forbid. This resolver
+ * threads the needle.
+ */
+export function resolveExecutable(cmd: string, opts: ResolveExecutableOptions = {}): string {
+  const platform = opts.platform ?? process.platform;
+  if (platform !== "win32") return cmd;
+  if (!cmd) return cmd;
+  // Already a path fragment — spawn handles these natively.
+  if (cmd.includes("/") || cmd.includes("\\") || pathMod.isAbsolute(cmd)) return cmd;
+  // If the model wrote `npm.cmd` explicitly, respect that verbatim.
+  if (pathMod.extname(cmd)) return cmd;
+
+  const env = opts.env ?? process.env;
+  const pathExt = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .map((e) => e.trim())
+    .filter(Boolean);
+  const delimiter = opts.pathDelimiter ?? (platform === "win32" ? ";" : pathMod.delimiter);
+  const pathDirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  const isFile = opts.isFile ?? defaultIsFile;
+
+  for (const dir of pathDirs) {
+    for (const ext of pathExt) {
+      // Force win32 join so CI tests that pass `platform: "win32"`
+      // from a Linux runner get backslash-joined paths; the real-
+      // Windows runtime path lands here too and gets the correct
+      // separator regardless of where pathMod defaults.
+      const full = pathMod.win32.join(dir, cmd + ext);
+      if (isFile(full)) return full;
+    }
+  }
+  return cmd;
+}
+
+function defaultIsFile(full: string): boolean {
+  try {
+    return existsSync(full) && statSync(full).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Prepare `(bin, args, spawnOpts)` for the runCommand spawn call,
+ * applying Windows-specific workarounds for (a) PATHEXT lookup and
+ * (b) the CVE-2024-27980 prohibition on direct `.cmd`/`.bat` spawns.
+ *
+ * Exported so tests can assert the transformation without booting an
+ * actual child process.
+ */
+export function prepareSpawn(
+  argv: readonly string[],
+  opts: ResolveExecutableOptions = {},
+): { bin: string; args: string[]; spawnOverrides: SpawnOptions } {
+  const head = argv[0] ?? "";
+  const tail = argv.slice(1);
+  const platform = opts.platform ?? process.platform;
+  const resolved = resolveExecutable(head, opts);
+
+  if (platform !== "win32") {
+    return { bin: resolved, args: [...tail], spawnOverrides: {} };
+  }
+
+  // `.cmd` / `.bat` wrappers require cmd.exe on post-CVE Node.
+  if (/\.(cmd|bat)$/i.test(resolved)) {
+    const cmdline = [resolved, ...tail].map(quoteForCmdExe).join(" ");
+    return {
+      bin: "cmd.exe",
+      args: ["/d", "/s", "/c", withUtf8Codepage(cmdline)],
+      // windowsVerbatimArguments prevents Node from re-quoting the /c
+      // payload — we've already composed an exact cmd.exe command
+      // line. Without this Node wraps our already-quoted string in
+      // another round of quotes and cmd.exe can't parse it.
+      spawnOverrides: { windowsVerbatimArguments: true },
+    };
+  }
+
+  // Bare command names that PATH × PATHEXT couldn't resolve to an
+  // on-disk file — these are almost always cmd.exe built-ins (`dir`,
+  // `echo`, `type`, `ver`, `vol`, `where`, `help`, …) which don't
+  // exist as standalone executables. Direct spawn crashes with ENOENT;
+  // routing through cmd.exe lets the built-in resolve, and if it's
+  // genuinely unknown the user gets the standard "'foo' is not
+  // recognized" message instead of a raw spawn failure.
+  if (isBareWindowsName(resolved) && resolved === head) {
+    const cmdline = [head, ...tail].map(quoteForCmdExe).join(" ");
+    return {
+      bin: "cmd.exe",
+      args: ["/d", "/s", "/c", withUtf8Codepage(cmdline)],
+      spawnOverrides: { windowsVerbatimArguments: true },
+    };
+  }
+
+  // PowerShell variants: chcp 65001 doesn't help here because PowerShell
+  // sets its own [Console]::OutputEncoding at startup — usually system
+  // codepage (CP936/CP932/CP949 on CJK Windows) or UTF-16. The result
+  // is mojibake when our `chunk.toString()` UTF-8-decodes its stdout.
+  // Inject a UTF-8 setup prelude into the `-Command` (or `-c`) arg so
+  // any output produced thereafter is UTF-8.
+  if (isPowerShellExe(resolved)) {
+    const patched = injectPowerShellUtf8(tail);
+    if (patched) {
+      return { bin: resolved, args: patched, spawnOverrides: {} };
+    }
+  }
+
+  return { bin: resolved, args: [...tail], spawnOverrides: {} };
+}
+
+/** Resolved bin path looks like Windows PowerShell or PowerShell Core. */
+function isPowerShellExe(resolved: string): boolean {
+  return /(?:^|[\\/])(?:powershell|pwsh)(?:\.exe)?$/i.test(resolved);
+}
+
+/**
+ * Locate `-Command` / `-c` in `args` and prepend the UTF-8 setup prelude
+ * to its value. Returns the patched args, or `null` when no `-Command`
+ * arg is present (in which case we leave the invocation untouched —
+ * inline-expression and script-file modes have their own conventions
+ * we don't want to silently rewrite).
+ *
+ * Why not always wrap: PowerShell's quoting semantics are finicky enough
+ * that adding a prelude to a script file invocation could break it.
+ * `-Command` is the case the model actually uses, and where mojibake
+ * matters; targeting just it keeps the blast radius small.
+ *
+ * Exported for tests.
+ */
+export function injectPowerShellUtf8(args: readonly string[]): string[] | null {
+  const prelude =
+    "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;$OutputEncoding=[System.Text.Encoding]::UTF8;";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i] ?? "";
+    if (/^-(?:Command|c)$/i.test(a) && i + 1 < args.length) {
+      const out = [...args];
+      out[i + 1] = `${prelude}${args[i + 1] ?? ""}`;
+      return out;
+    }
+  }
+  return null;
+}
+
+/**
+ * Prefix a cmd.exe command line with `chcp 65001 >nul &` so output
+ * (from cmd.exe and any child it spawns) is UTF-8-encoded. Without
+ * this, on Chinese / Japanese / Korean Windows, `dir`, `findstr`,
+ * `where`, etc. emit text in the system codepage (CP936, CP932,
+ * CP949, …) and `chunk.toString()` — which decodes as UTF-8 — produces
+ * garbled mojibake the model then sees as poisoned input on the next
+ * turn.
+ *
+ * Scope: chcp affects ONLY this cmd.exe instance, which exits after
+ * `/c`. No global console state changes. Single `&` (not `&&`) so the
+ * command still runs even on the rare Windows builds where chcp
+ * itself returns a non-zero exit (Win7 quirks; harmless on Win10+).
+ *
+ * Exported so tests can verify the wrapping shape.
+ */
+export function withUtf8Codepage(cmdline: string): string {
+  return `chcp 65001 >nul & ${cmdline}`;
+}
+
+/**
+ * True when `s` looks like a bare executable name — no path separator,
+ * no drive letter, no extension. Such names on Windows, when absent
+ * from PATH × PATHEXT, are almost always cmd.exe built-ins.
+ */
+function isBareWindowsName(s: string): boolean {
+  if (!s) return false;
+  if (s.includes("/") || s.includes("\\")) return false;
+  if (pathMod.isAbsolute(s)) return false;
+  if (pathMod.extname(s)) return false;
+  return true;
+}
+
+/**
+ * Quote an argument so cmd.exe parses it back as a single token. We
+ * always wrap in double quotes when the arg contains whitespace or
+ * any cmd.exe metacharacter, doubling embedded quotes per cmd.exe's
+ * `""` escape rule. Bare alphanumeric args pass through unquoted for
+ * readability in logs.
+ *
+ * Exported for test coverage of the quoting semantics.
+ */
+export function quoteForCmdExe(arg: string): string {
+  if (arg === "") return '""';
+  if (!/[\s"&|<>^%(),;!]/.test(arg)) return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+
+/** Error thrown by `run_command` when the command isn't allowlisted. */
+export class NeedsConfirmationError extends Error {
+  readonly command: string;
+  constructor(command: string) {
+    super(
+      `run_command: "${command}" needs the user's approval before it runs. STOP calling tools now — the TUI has already prompted the user to press y (run) or n (deny). Wait for their next message; it will either be the command's output (if they approved) or an instruction to continue without it (if they denied). Don't retry the command or call other shell commands in the meantime.`,
+    );
+    this.name = "NeedsConfirmationError";
+    this.command = command;
+  }
+}
+
+export function registerShellTools(registry: ToolRegistry, opts: ShellToolsOptions): ToolRegistry {
+  const rootDir = pathMod.resolve(opts.rootDir);
+  const timeoutSec = opts.timeoutSec ?? DEFAULT_TIMEOUT_SEC;
+  const maxOutputChars = opts.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+  // Resolved on every dispatch so newly-persisted "always allow"
+  // prefixes take effect inside the session that added them, not just
+  // on the next launch. Static arrays are wrapped into a constant
+  // getter so the call site below is uniform.
+  const getExtraAllowed: () => readonly string[] =
+    typeof opts.extraAllowed === "function"
+      ? opts.extraAllowed
+      : (() => {
+          const snapshot = opts.extraAllowed ?? [];
+          return () => snapshot;
+        })();
+  const allowAll = opts.allowAll ?? false;
+
+  registry.register({
+    name: "run_command",
+    description:
+      "Run a shell command in the project root and return its combined stdout+stderr. Common read-only inspection and test/lint/typecheck commands run immediately; anything that could mutate state, install dependencies, or touch the network is refused until the user confirms it in the TUI. Prefer this over asking the user to run a command manually — after edits, run the project's tests to verify.",
+    // Plan-mode gate: allow allowlisted commands through (git status,
+    // cargo check, ls, grep …) so the model can actually investigate
+    // during planning. Anything that would otherwise trigger a
+    // confirmation prompt is treated as "not read-only" and bounced.
+    readOnlyCheck: (args: { command?: unknown }) => {
+      if (allowAll) return true;
+      const cmd = typeof args?.command === "string" ? args.command.trim() : "";
+      if (!cmd) return false;
+      return isAllowed(cmd, getExtraAllowed());
+    },
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description:
+            'Full command line. Tokenized with POSIX-ish quoting; no shell expansion. Pipes (`|`), redirects (`>`, `<`, `2>`), and `&&`/`||` chaining are rejected with an error — split into separate calls instead. To pass an operator character as a literal argument (e.g. a regex), wrap it in quotes: `grep "a|b" file.txt`.',
+        },
+        timeoutSec: {
+          type: "integer",
+          description: `Override the default ${timeoutSec}s timeout for a single command.`,
+        },
+      },
+      required: ["command"],
+    },
+    fn: async (args: { command: string; timeoutSec?: number }, ctx) => {
+      const cmd = args.command.trim();
+      if (!cmd) throw new Error("run_command: empty command");
+      if (!allowAll && !isAllowed(cmd, getExtraAllowed())) {
+        throw new NeedsConfirmationError(cmd);
+      }
+      const effectiveTimeout = Math.max(1, Math.min(600, args.timeoutSec ?? timeoutSec));
+      const result = await runCommand(cmd, {
+        cwd: rootDir,
+        timeoutSec: effectiveTimeout,
+        maxOutputChars,
+        signal: ctx?.signal,
+      });
+      return formatCommandResult(cmd, result);
+    },
+  });
+
+  return registry;
+}
+
+export function formatCommandResult(cmd: string, r: RunCommandResult): string {
+  const header = r.timedOut
+    ? `$ ${cmd}\n[killed after timeout]`
+    : `$ ${cmd}\n[exit ${r.exitCode ?? "?"}]`;
+  return r.output ? `${header}\n${r.output}` : header;
+}

src/tools/skills.ts

@@ -0,0 +1,147 @@
+/**
+ * `run_skill` — invoke a user-authored playbook from the Skills index.
+ *
+ * Two execution modes, picked at registration time per skill via
+ * frontmatter `runAs`:
+ *
+ *   - `inline` (default) — the skill body becomes the tool result and
+ *     enters the parent's append-only log. The model reads the
+ *     instructions and continues the normal loop, calling whatever
+ *     tools the skill prescribes. Cheap, no isolation. Best for
+ *     "load a checklist" / "load a coding style" / "load review
+ *     criteria" patterns.
+ *
+ *   - `subagent` — the skill body becomes the *system prompt* of an
+ *     isolated child loop; the user-supplied `arguments` becomes the
+ *     `task`. Only the child's final answer comes back as the tool
+ *     result. Best for big-context exploration or research playbooks
+ *     where the parent doesn't need to see the trail.
+ *
+ * Subagent dispatch is opt-in: callers must supply a `subagentRunner`
+ * at registration. When omitted (chat mode without a configured
+ * client), invoking a subagent skill returns a structured error
+ * instead of silently downgrading to inline — that would surprise the
+ * skill author.
+ *
+ * v1 deliberately ignores each skill's `allowed-tools` frontmatter:
+ * Reasonix's tool namespace doesn't align with Claude Code's so a
+ * literal pass would give wrong answers.
+ */
+
+import { type Skill, SkillStore } from "../skills.js";
+import type { ToolRegistry } from "../tools.js";
+
+/**
+ * Caller-supplied closure that knows how to spawn a subagent for the
+ * given resolved skill + task. Decoupled from `registerSkillTools` so
+ * the skills tool doesn't need to know about DeepSeekClient or the
+ * parent ToolRegistry — the App / library wiring assembles those once
+ * and hands in this function.
+ *
+ * Returns the JSON tool-result string verbatim (already serialized via
+ * `formatSubagentResult`), so the dispatch path is pure pass-through.
+ */
+export type SubagentRunner = (skill: Skill, task: string) => Promise<string>;
+
+export interface SkillToolsOptions {
+  /** Override `$HOME` — tests set this to a tmpdir. */
+  homeDir?: string;
+  /**
+   * Absolute project root — enables discovery of project-scope skills
+   * under `<projectRoot>/.reasonix/skills/`. Omit for chat mode (global
+   * scope only).
+   */
+  projectRoot?: string;
+  /**
+   * Closure that spawns a subagent for `runAs: subagent` skills. When
+   * omitted, invoking a subagent skill returns an error directing the
+   * user to wire up the runner — silent fallback to inline would be
+   * worse, since the skill author wrote the body assuming isolation.
+   */
+  subagentRunner?: SubagentRunner;
+  /** Hide built-in skills (test-only knob; production callers leave off). */
+  disableBuiltins?: boolean;
+}
+
+export function registerSkillTools(
+  registry: ToolRegistry,
+  opts: SkillToolsOptions = {},
+): ToolRegistry {
+  const store = new SkillStore({
+    homeDir: opts.homeDir,
+    projectRoot: opts.projectRoot,
+    disableBuiltins: opts.disableBuiltins,
+  });
+  const subagentRunner = opts.subagentRunner;
+
+  registry.register({
+    name: "run_skill",
+    description:
+      "Invoke a playbook from the Skills index pinned in the system prompt. Each entry is a self-contained instruction block. Skills marked with 🧬 in the index spawn an isolated subagent — only the final distilled answer comes back, the model's tool calls + reasoning during the run never enter your context. Plain skills are inlined: the body becomes a tool result you read and follow. For 🧬 subagent skills, supply 'arguments' describing the concrete task — they'll be the only context the subagent has.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description:
+            "Skill identifier as it appears in the pinned Skills index (e.g. 'explore', 'review', 'security-review'). Case-sensitive.",
+        },
+        arguments: {
+          type: "string",
+          description:
+            "Free-form arguments the skill should act on. For inline skills: appended to the body as an 'Arguments:' line; the skill's own instructions decide how to consume them. For 🧬 subagent skills: REQUIRED — becomes the entire task description the subagent receives, since it has no other context.",
+        },
+      },
+      required: ["name"],
+    },
+    fn: async (args: { name?: unknown; arguments?: unknown }) => {
+      const name = typeof args.name === "string" ? args.name.trim() : "";
+      if (!name) {
+        return JSON.stringify({ error: "run_skill requires a 'name' argument" });
+      }
+      const skill = store.read(name);
+      if (!skill) {
+        const available = store
+          .list()
+          .map((s) => s.name)
+          .join(", ");
+        return JSON.stringify({
+          error: `unknown skill: ${JSON.stringify(name)}`,
+          available: available || "(none — user has not defined any skills)",
+        });
+      }
+      const rawArgs = typeof args.arguments === "string" ? args.arguments.trim() : "";
+
+      if (skill.runAs === "subagent") {
+        if (!subagentRunner) {
+          return JSON.stringify({
+            error: `run_skill: skill ${JSON.stringify(name)} is marked runAs=subagent but no subagent runner is configured for this session. Skill authors who need isolation should run inside reasonix code (or a library setup that passes subagentRunner to registerSkillTools).`,
+          });
+        }
+        if (!rawArgs) {
+          return JSON.stringify({
+            error: `run_skill: skill ${JSON.stringify(name)} is a subagent and requires 'arguments' — the subagent has no other context, so describe the concrete task in the arguments field.`,
+          });
+        }
+        return subagentRunner(skill, rawArgs);
+      }
+
+      // inline path — body becomes the tool result.
+      const header = [
+        `# Skill: ${skill.name}`,
+        skill.description ? `> ${skill.description}` : "",
+        `(scope: ${skill.scope} · ${skill.path})`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+      const argsBlock = rawArgs ? `\n\nArguments: ${rawArgs}` : "";
+      // The body is handed to the model verbatim. No truncation — the
+      // user authored it, we trust their length choice. The append-only
+      // log pays the token cost exactly once per invocation.
+      return `${header}\n\n${skill.body}${argsBlock}`;
+    },
+  });
+
+  return registry;
+}

src/tools/subagent.ts

@@ -0,0 +1,491 @@
+/**
+ * Subagent runtime — isolated child loops for offloading exploration or
+ * self-contained subtasks.
+ *
+ * Two surfaces sit on top of the same `spawnSubagent` core:
+ *
+ *   1. `registerSubagentTool` — exposes a low-level `spawn_subagent`
+ *      function-call tool. Library API. NOT registered into the model
+ *      tool list by `reasonix code` since 0.4.26 — Skills (with
+ *      `runAs: subagent` frontmatter) became the user-facing surface.
+ *      Kept exported because library callers and tests still want
+ *      direct access to the primitive.
+ *
+ *   2. `run_skill` (in src/tools/skills.ts) — when the resolved skill
+ *      has `runAs: subagent`, it calls `spawnSubagent` with the skill
+ *      body as the system prompt and the user's `arguments` as the
+ *      task. Subagent skills are listed in the pinned Skills index
+ *      with a 🧬 marker, which gives the model a clear pattern-match
+ *      trigger without forcing it to reason about "is this task big
+ *      enough to delegate."
+ *
+ * Why R1 specifically benefits:
+ *   - R1 reasoning tokens are expensive AND inflate the parent context.
+ *     A subagent runs its own private loop, then surfaces only the
+ *     distilled final answer back to the parent — the main session
+ *     never sees the reasoning trail.
+ *
+ * Invariants common to both surfaces:
+ *   - Serial only — no parallel spawn (MVP).
+ *   - Inherits parent's tool registry MINUS `spawn_subagent` itself
+ *     (no recursion via the tool API) and MINUS `submit_plan`
+ *     (subagents don't propose plans to the user).
+ *   - No hooks, no session — runs are ephemeral.
+ *   - Lower default `maxToolIters` than the parent (16 vs 64).
+ *   - Independent prefix cache (subagent's prefix has its own
+ *     fingerprint).
+ *   - Parent registry's plan-mode state propagates: subagents can't
+ *     escape `/plan`.
+ *   - Non-streaming child loop — the parent isn't watching deltas, so
+ *     streaming would only add an SSE parser to the critical path.
+ *     Cancellation still works via the AbortSignal.
+ */
+
+import { type DeepSeekClient, Usage } from "../client.js";
+import { CacheFirstLoop } from "../loop.js";
+import { ImmutablePrefix } from "../memory.js";
+import { applyProjectMemory } from "../project-memory.js";
+import { ToolRegistry } from "../tools.js";
+
+/**
+ * Live event emitted by a running subagent. Surfaced via the optional
+ * `sink` ref the TUI attaches its handler to. Side-channel only — these
+ * events do NOT pass through the parent loop's `LoopEvent` stream
+ * because subagents run inside a tool-dispatch frame, after the parent's
+ * `step()` has already yielded `tool_start` and is awaiting the result.
+ */
+export interface SubagentEvent {
+  kind: "start" | "progress" | "end";
+  /** First ~30 chars of the task prompt — used for the TUI status row. */
+  task: string;
+  /** Skill that spawned this subagent, when applicable. Stamped on every event so the TUI/logger can attribute without extra plumbing. */
+  skillName?: string;
+  /** Model id the child loop ran on. Stamped alongside skillName. */
+  model?: string;
+  /** Iteration count inside the child loop (number of tool results so far). */
+  iter?: number;
+  /** Wall-clock ms since the subagent started. */
+  elapsedMs?: number;
+  /** First ~120 chars of the final assistant message. Set on `end`. */
+  summary?: string;
+  /** Error message if the subagent failed. Set on `end`. */
+  error?: string;
+  /** Total turns the subagent took. Set on `end`. */
+  turns?: number;
+  /** Total USD spent inside the child loop. Set on `end`. */
+  costUsd?: number;
+  /** Aggregated child-loop Usage (sum across turns). Set on `end`. */
+  usage?: Usage;
+}
+
+/**
+ * Mutable ref the registration writes through. The TUI sets `.current`
+ * to its own handler on mount; nothing receives events before that
+ * happens (and headless callers leave `.current = null`, which is the
+ * library-mode default — they read the final result from the helper's
+ * return value instead).
+ */
+export interface SubagentSink {
+  current: ((ev: SubagentEvent) => void) | null;
+}
+
+/**
+ * Per-spawn options for {@link spawnSubagent}. All but `parentRegistry`
+ * + `client` + `system` + `task` are tunables with sensible defaults.
+ */
+export interface SpawnSubagentOptions {
+  /** Shared DeepSeek client. The subagent reuses it (same auth, same retries). */
+  client: DeepSeekClient;
+  /**
+   * Parent registry — the subagent inherits a copy of its tools (minus
+   * the never-inherited set: `spawn_subagent`, `submit_plan`).
+   */
+  parentRegistry: ToolRegistry;
+  /**
+   * System prompt for the child loop. Skills' subagent path passes
+   * the skill body here; the spawn_subagent tool passes its default
+   * (or the model's `system` argument override).
+   */
+  system: string;
+  /** The task / question / instruction the subagent must address. */
+  task: string;
+  /** Model id for the child loop. Defaults to `deepseek-chat`. */
+  model?: string;
+  /** Iteration ceiling for the child loop. Defaults to 16. */
+  maxToolIters?: number;
+  /**
+   * Maximum chars of the final assistant message returned. Long answers
+   * are truncated with a notice — the parent's prompt budget shouldn't
+   * be blown out by an over-eager subagent.
+   */
+  maxResultChars?: number;
+  /** Optional sink for TUI live updates. */
+  sink?: SubagentSink;
+  /**
+   * Parent's per-tool-dispatch AbortSignal. When the parent aborts (Esc),
+   * we forward the cancel into the child loop. Omit for headless callers
+   * that don't care about cancellation.
+   */
+  parentSignal?: AbortSignal;
+  /**
+   * Skill name when this spawn is driven by a `runAs: subagent` skill.
+   * Used purely for downstream attribution (TUI summary line, usage log).
+   * Omit for raw `spawn_subagent` tool calls.
+   */
+  skillName?: string;
+}
+
+/**
+ * Structured result of a subagent run. The two convenience JSON wrappers
+ * (`spawn_subagent` tool, `run_skill` subagent path) serialize this for
+ * the model; library callers can read the typed object directly.
+ */
+export interface SubagentResult {
+  success: boolean;
+  /** Final assistant message (possibly truncated). Empty on error. */
+  output: string;
+  /** Set when the run failed (network, child-loop error, etc.). */
+  error?: string;
+  /** Turns the child loop took. */
+  turns: number;
+  /** Tool calls dispatched inside the child loop. */
+  toolIters: number;
+  /** Wall-clock ms. */
+  elapsedMs: number;
+  /** USD spent in the child loop, summed across its turns. */
+  costUsd: number;
+  /** Model id the child loop ran on. */
+  model: string;
+  /** Skill name if the spawn was driven by a `runAs: subagent` skill. */
+  skillName?: string;
+  /** Aggregated Usage across the child loop's turns. Zero-filled when no API calls landed. */
+  usage: Usage;
+}
+
+export interface SubagentToolOptions {
+  /** Shared DeepSeek client. */
+  client: DeepSeekClient;
+  /**
+   * Default system prompt used when the model doesn't pass one. Project
+   * memory (REASONIX.md) is appended automatically when `projectRoot` is
+   * set.
+   */
+  defaultSystem?: string;
+  /** Project root for `applyProjectMemory` lookup. Omit in chat mode. */
+  projectRoot?: string;
+  /** Default model. `deepseek-chat` (V3) by default. */
+  defaultModel?: string;
+  /** Iteration ceiling. Lower than the parent (16 by default). */
+  maxToolIters?: number;
+  /** Maximum chars returned in the tool result. */
+  maxResultChars?: number;
+  /** Optional sink the TUI attaches its handler to for live updates. */
+  sink?: SubagentSink;
+}
+
+const DEFAULT_SUBAGENT_SYSTEM = `You are a Reasonix subagent. The parent agent spawned you to handle one focused subtask, then return.
+
+Rules:
+- Stay on the task you were given. Do not expand scope.
+- Use tools as needed. You share the parent's sandbox + safety rules.
+- When you're done, your final assistant message is the only thing the parent will see — make it complete and self-contained. No follow-up offers, no questions, no "let me know if you need more."
+- Prefer one clear, distilled answer over a long log of what you tried.
+
+Formatting rules (the parent renders your reply in a TUI with a real markdown renderer):
+- For tabular data use GitHub-Flavored Markdown tables with ASCII pipes: \`| col | col |\` headers, \`| --- | --- |\` separator. NEVER draw tables with Unicode box-drawing characters (│ ─ ┼ ┌ ┐ └ ┘ ├ ┤). They look intentional but break terminal word-wrap and produce garbled output.
+- Keep table cells short — one short phrase per cell, not multi-line paragraphs. If a description doesn't fit in ~40 chars, use bullets below the table instead.
+- Use fenced code blocks (\`\`\`) for any code, file paths with line ranges, or shell commands.
+- NEVER draw decorative frames around content with \`┌──┐ │ └──┘\` box-drawing characters. The renderer handles code blocks and headings on its own — extra ASCII art adds noise without value and breaks at narrow terminal widths.
+- For flow charts and diagrams: use a markdown bullet list with \`→\` or \`↓\` between steps. Don't try to draw boxes-and-arrows in ASCII; it never survives word-wrap.`;
+
+const DEFAULT_MAX_RESULT_CHARS = 8000;
+const DEFAULT_MAX_ITERS = 16;
+const DEFAULT_SUBAGENT_MODEL = "deepseek-chat";
+
+const SUBAGENT_TOOL_NAME = "spawn_subagent";
+/**
+ * Tools the subagent never inherits from the parent registry:
+ *   - spawn_subagent itself: would allow unbounded recursion via the
+ *     tool API. Depth=1 hard cap by construction.
+ *   - submit_plan: only the parent talks to the user about plan
+ *     approval; a subagent submitting a plan would surface a picker
+ *     midway through the parent's turn, which the user did not ask for.
+ */
+const NEVER_INHERITED_TOOLS = new Set<string>([SUBAGENT_TOOL_NAME, "submit_plan"]);
+
+/**
+ * Run one subagent to completion. The unified primitive both
+ * `spawn_subagent` (function-call tool) and `run_skill` (subagent
+ * skills) call into.
+ *
+ * Headless: returns a `SubagentResult` regardless of success/failure.
+ * Errors are captured in the structured shape, never thrown — the
+ * caller decides how to surface them (tool result JSON, log line, etc.).
+ */
+export async function spawnSubagent(opts: SpawnSubagentOptions): Promise<SubagentResult> {
+  const model = opts.model ?? DEFAULT_SUBAGENT_MODEL;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS;
+  const sink = opts.sink;
+  const skillName = opts.skillName;
+
+  const startedAt = Date.now();
+  const taskPreview = opts.task.length > 30 ? `${opts.task.slice(0, 30)}…` : opts.task;
+  sink?.current?.({
+    kind: "start",
+    task: taskPreview,
+    skillName,
+    model,
+    iter: 0,
+    elapsedMs: 0,
+  });
+
+  const childTools = forkRegistryExcluding(opts.parentRegistry, NEVER_INHERITED_TOOLS);
+  const childPrefix = new ImmutablePrefix({
+    system: opts.system,
+    toolSpecs: childTools.specs(),
+  });
+  const childLoop = new CacheFirstLoop({
+    client: opts.client,
+    prefix: childPrefix,
+    tools: childTools,
+    model,
+    maxToolIters,
+    hooks: [],
+    stream: false,
+  });
+
+  const onParentAbort = () => childLoop.abort();
+  opts.parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+
+  let final = "";
+  let errorMessage: string | undefined;
+  let toolIter = 0;
+  try {
+    for await (const ev of childLoop.step(opts.task)) {
+      if (ev.role === "tool") {
+        toolIter++;
+        sink?.current?.({
+          kind: "progress",
+          task: taskPreview,
+          skillName,
+          model,
+          iter: toolIter,
+          elapsedMs: Date.now() - startedAt,
+        });
+      }
+      if (ev.role === "assistant_final") {
+        final = ev.content ?? "";
+      }
+      if (ev.role === "error") {
+        errorMessage = ev.error ?? "subagent error";
+      }
+    }
+  } catch (err) {
+    errorMessage = (err as Error).message;
+  } finally {
+    opts.parentSignal?.removeEventListener("abort", onParentAbort);
+  }
+  // The loop yields `done` without an `error` event when its API call
+  // is aborted mid-flight (intentional UX — see the matching catch in
+  // CacheFirstLoop.step). From a SUBAGENT consumer's perspective that
+  // still counts as a failure: no answer came back, the parent has
+  // nothing to render. Synthesize an error so `success: false` and the
+  // UI surfaces the abort instead of returning empty output.
+  if (!errorMessage && !final) {
+    errorMessage = opts.parentSignal?.aborted
+      ? "subagent aborted before producing an answer"
+      : "subagent ended without producing an answer";
+  }
+
+  const elapsedMs = Date.now() - startedAt;
+  const turns = childLoop.stats.turns.length;
+  const costUsd = childLoop.stats.totalCost;
+  const usage = aggregateChildUsage(childLoop);
+
+  const truncated =
+    final.length > maxResultChars
+      ? `${final.slice(0, maxResultChars)}\n\n[…truncated ${final.length - maxResultChars} chars; ask the subagent for a tighter summary if you need more.]`
+      : final;
+
+  sink?.current?.({
+    kind: "end",
+    task: taskPreview,
+    skillName,
+    model,
+    iter: toolIter,
+    elapsedMs,
+    summary: errorMessage ? undefined : truncated.slice(0, 120),
+    error: errorMessage,
+    turns,
+    costUsd,
+    usage,
+  });
+
+  return {
+    success: !errorMessage,
+    output: errorMessage ? "" : truncated,
+    error: errorMessage,
+    turns,
+    toolIters: toolIter,
+    elapsedMs,
+    costUsd,
+    model,
+    skillName,
+    usage,
+  };
+}
+
+/**
+ * Sum the child loop's per-turn `Usage` into one aggregate record.
+ * Zero-filled when the loop made no API calls (e.g. failed before the
+ * first request) so downstream consumers always see a valid shape.
+ */
+function aggregateChildUsage(loop: CacheFirstLoop): Usage {
+  const agg = new Usage();
+  for (const t of loop.stats.turns) {
+    agg.promptTokens += t.usage.promptTokens;
+    agg.completionTokens += t.usage.completionTokens;
+    agg.totalTokens += t.usage.totalTokens;
+    agg.promptCacheHitTokens += t.usage.promptCacheHitTokens;
+    agg.promptCacheMissTokens += t.usage.promptCacheMissTokens;
+  }
+  return agg;
+}
+
+/**
+ * Serialize a {@link SubagentResult} into the JSON tool-result shape
+ * the model consumes. Both the spawn_subagent tool and the run_skill
+ * subagent path return this string verbatim, so the schema stays
+ * stable across both surfaces.
+ */
+export function formatSubagentResult(r: SubagentResult): string {
+  if (!r.success) {
+    return JSON.stringify({
+      success: false,
+      error: r.error ?? "unknown subagent error",
+      turns: r.turns,
+      tool_iters: r.toolIters,
+      elapsed_ms: r.elapsedMs,
+    });
+  }
+  return JSON.stringify({
+    success: true,
+    output: r.output,
+    turns: r.turns,
+    tool_iters: r.toolIters,
+    elapsed_ms: r.elapsedMs,
+    cost_usd: r.costUsd,
+  });
+}
+
+/**
+ * Register the spawn_subagent tool into the parent registry. Library
+ * surface — `reasonix code` does NOT call this since 0.4.26 (Skills
+ * with `runAs: subagent` are the user-facing surface), but library
+ * consumers who want the low-level tool can opt in.
+ */
+export function registerSubagentTool(
+  parentRegistry: ToolRegistry,
+  opts: SubagentToolOptions,
+): ToolRegistry {
+  const baseSystem = opts.defaultSystem ?? DEFAULT_SUBAGENT_SYSTEM;
+  // Bake project memory into the default once — re-reading on every
+  // spawn would (a) make the child prefix unstable when REASONIX.md
+  // changes mid-session, defeating cache reuse across multiple
+  // subagent calls, and (b) cost a stat() per call. The parent itself
+  // also reads memory once at startup; matching that semantics keeps
+  // subagent and parent on the same page.
+  const defaultSystem = opts.projectRoot
+    ? applyProjectMemory(baseSystem, opts.projectRoot)
+    : baseSystem;
+  const defaultModel = opts.defaultModel ?? DEFAULT_SUBAGENT_MODEL;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS;
+  const sink = opts.sink;
+
+  parentRegistry.register({
+    name: SUBAGENT_TOOL_NAME,
+    description:
+      "Spawn an isolated subagent to handle a self-contained subtask in a fresh context, returning only its final answer. Use for: deep codebase exploration that would flood the main context, multi-step research where you only need the conclusion, or any focused subtask whose intermediate reasoning the user does not need to see. The subagent inherits all your tools (filesystem, shell, web, MCP, etc.) but runs in its own isolated message log — its tool calls and reasoning never enter your context. Only the final assistant message comes back as this tool's result. Keep tasks focused; the subagent has a stricter iter budget than you do.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description:
+            "The subtask the subagent should perform. Be specific and self-contained — the subagent has none of your conversation context, only what you write here.",
+        },
+        system: {
+          type: "string",
+          description:
+            "Optional override for the subagent's system prompt. The default tells it to stay focused and return a concise answer; override only when the subtask needs a specialized persona.",
+        },
+        model: {
+          type: "string",
+          enum: ["deepseek-chat", "deepseek-reasoner"],
+          description:
+            "Which DeepSeek model the subagent runs on. 'deepseek-chat' (V3) is the default — fast and cheap. Use 'deepseek-reasoner' (R1) only when the subtask genuinely needs planning or multi-step reasoning; it is roughly 5-10x more expensive.",
+        },
+      },
+      required: ["task"],
+    },
+    fn: async (args: { task?: unknown; system?: unknown; model?: unknown }, ctx) => {
+      const task = typeof args.task === "string" ? args.task.trim() : "";
+      if (!task) {
+        return JSON.stringify({
+          error: "spawn_subagent requires a non-empty 'task' argument.",
+        });
+      }
+      const system =
+        typeof args.system === "string" && args.system.trim().length > 0
+          ? args.system.trim()
+          : defaultSystem;
+      const model =
+        typeof args.model === "string" && args.model.startsWith("deepseek-")
+          ? args.model
+          : defaultModel;
+      const result = await spawnSubagent({
+        client: opts.client,
+        parentRegistry,
+        system,
+        task,
+        model,
+        maxToolIters,
+        maxResultChars,
+        sink,
+        parentSignal: ctx?.signal,
+      });
+      return formatSubagentResult(result);
+    },
+  });
+
+  return parentRegistry;
+}
+
+/**
+ * Build a child ToolRegistry that copies every tool from `parent` except
+ * those whose names are in `exclude`. Plan-mode state propagates so a
+ * subagent spawned while the parent is under `/plan` cannot escape it.
+ *
+ * Exported for tests + library callers who want the same fork behavior
+ * for their own nested-loop patterns.
+ */
+export function forkRegistryExcluding(
+  parent: ToolRegistry,
+  exclude: ReadonlySet<string>,
+): ToolRegistry {
+  const child = new ToolRegistry();
+  for (const spec of parent.specs()) {
+    const name = spec.function.name;
+    if (exclude.has(name)) continue;
+    const def = parent.get(name);
+    if (!def) continue;
+    // Re-register copies the public ToolDefinition fields. The child
+    // re-runs auto-flatten analysis on its own, which produces an
+    // identical flatSchema for the same input — no surprise.
+    child.register(def);
+  }
+  if (parent.planMode) child.setPlanMode(true);
+  return child;
+}

src/tools/web.ts

@@ -0,0 +1,301 @@
+/**
+ * Built-in web search + fetch tools.
+ *
+ *   - `web_search(query, topK?)` — Mojeek's public search page. No API
+ *     key, no signup. We originally shipped this backed by DuckDuckGo's
+ *     HTML endpoint, but DDG started serving anti-bot interstitials
+ *     (HTTP 202 with a challenge page) for every unauthenticated POST.
+ *     Mojeek runs its own independent index, is bot-friendly, and
+ *     returns parseable HTML.
+ *   - `web_fetch(url)` — HTTP GET + naïve HTML-to-text extraction.
+ *
+ * Both are registered by default on `reasonix chat` / `reasonix code`;
+ * set `search: false` in config (or `REASONIX_SEARCH=off`) to turn
+ * them off. The model decides when to call them based on the query —
+ * no slash command required.
+ */
+
+import type { ToolRegistry } from "../tools.js";
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export interface PageContent {
+  url: string;
+  title?: string;
+  text: string;
+  /** True when the extracted text was clipped to fit the cap. */
+  truncated: boolean;
+}
+
+export interface WebFetchOptions {
+  /** Max bytes of extracted text. Defaults to 32_000 to match tool-result cap. */
+  maxChars?: number;
+  /** Timeout in ms. Defaults to 15_000. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface WebSearchOptions {
+  topK?: number;
+  signal?: AbortSignal;
+}
+
+const DEFAULT_FETCH_MAX_CHARS = 32_000;
+const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+const DEFAULT_TOPK = 5;
+// Real-browser UA. Servers like Mojeek are bot-friendly but still gate
+// obvious scraper UAs; a stock Chrome string avoids the fast-path block.
+const USER_AGENT =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+const MOJEEK_ENDPOINT = "https://www.mojeek.com/search";
+
+/**
+ * Search the public web via Mojeek. Returns up to `topK` ranked
+ * results with title, url, snippet.
+ *
+ * Mojeek is an independent index (not a Google/Bing front-end) which
+ * means coverage on niche or very recent topics can be thinner, but
+ * it's reliable from scripts and doesn't gate on cookies or sessions.
+ * If the response has 0 results we distinguish "truly empty" from
+ * "layout changed or blocked" so the caller isn't left guessing.
+ */
+export async function webSearch(
+  query: string,
+  opts: WebSearchOptions = {},
+): Promise<SearchResult[]> {
+  const topK = Math.max(1, Math.min(10, opts.topK ?? DEFAULT_TOPK));
+  const resp = await fetch(`${MOJEEK_ENDPOINT}?q=${encodeURIComponent(query)}`, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      Accept: "text/html,application/xhtml+xml,application/xml;q=0.9",
+      "Accept-Language": "en-US,en;q=0.9",
+    },
+    signal: opts.signal,
+    redirect: "follow",
+  });
+  if (!resp.ok) throw new Error(`web_search ${resp.status}`);
+  const html = await resp.text();
+  const results = parseMojeekResults(html).slice(0, topK);
+  if (results.length === 0) {
+    if (/no results found|did not match any documents/i.test(html)) return [];
+    if (/captcha|verify you are human|access denied|forbidden/i.test(html)) {
+      throw new Error("web_search: Mojeek anti-bot page — rate-limited or blocked");
+    }
+    throw new Error(
+      `web_search: 0 results but response doesn't look like a real empty page (${html.length} chars, first 120: ${html.slice(0, 120).replace(/\s+/g, " ")})`,
+    );
+  }
+  return results;
+}
+
+/**
+ * Extract results from a Mojeek search page.
+ *
+ * Mojeek's stable shape (as of April 2026):
+ *   <a … class="ob" href="URL"> … breadcrumb … </a>
+ *   <h2><a class="title" href="URL">Title</a></h2>
+ *   <p class="s">snippet text …</p>
+ *
+ * We do two tolerant passes — title anchors, then snippet paragraphs —
+ * and pair them positionally. Attribute order inside a tag varies
+ * between versions, so each pass captures the whole element and we
+ * re-extract href / inner text with a second regex. Exported for
+ * unit testing against a fixture.
+ */
+export function parseMojeekResults(html: string): SearchResult[] {
+  const titles: string[] = [];
+  const titleAnchorRe = /<a\b[^>]*\bclass="title"[^>]*>[\s\S]*?<\/a>/g;
+  let m: RegExpExecArray | null;
+  while (true) {
+    m = titleAnchorRe.exec(html);
+    if (m === null) break;
+    titles.push(m[0]);
+  }
+
+  const snippets: string[] = [];
+  const snippetRe = /<p\b[^>]*\bclass="s"[^>]*>([\s\S]*?)<\/p>/g;
+  while (true) {
+    m = snippetRe.exec(html);
+    if (m === null) break;
+    snippets.push(m[1] ?? "");
+  }
+
+  const hrefRe = /href="([^"]+)"/;
+  const innerRe = /<a\b[^>]*>([\s\S]*?)<\/a>/;
+  const results: SearchResult[] = [];
+  for (let i = 0; i < titles.length; i++) {
+    const anchor = titles[i]!;
+    const hrefMatch = anchor.match(hrefRe);
+    const innerMatch = anchor.match(innerRe);
+    if (!hrefMatch?.[1]) continue;
+    results.push({
+      title: decodeHtmlEntities(stripHtml(innerMatch?.[1] ?? "")).trim(),
+      url: hrefMatch[1],
+      snippet: decodeHtmlEntities(stripHtml(snippets[i] ?? ""))
+        .replace(/\s+/g, " ")
+        .trim(),
+    });
+  }
+  return results;
+}
+
+/**
+ * Download a URL, strip HTML down to readable text, return it. Times
+ * out at 15s, caps extracted text at 32k chars to fit the tool-result
+ * budget.
+ */
+export async function webFetch(url: string, opts: WebFetchOptions = {}): Promise<PageContent> {
+  const maxChars = opts.maxChars ?? DEFAULT_FETCH_MAX_CHARS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  // Forward the caller's abort too so an Esc during a long fetch is respected.
+  const cancel = () => ctl.abort();
+  opts.signal?.addEventListener("abort", cancel, { once: true });
+  let resp: Response;
+  try {
+    resp = await fetch(url, {
+      headers: { "User-Agent": USER_AGENT, Accept: "text/html,text/plain,*/*" },
+      signal: ctl.signal,
+      redirect: "follow",
+    });
+  } finally {
+    clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", cancel);
+  }
+  if (!resp.ok) throw new Error(`web_fetch ${resp.status} for ${url}`);
+  const contentType = resp.headers.get("content-type") ?? "";
+  const raw = await resp.text();
+  const title = extractTitle(raw);
+  const text = contentType.includes("text/html") ? htmlToText(raw) : raw;
+  const truncated = text.length > maxChars;
+  const finalText = truncated
+    ? `${text.slice(0, maxChars)}\n\n[… truncated ${text.length - maxChars} chars …]`
+    : text;
+  return { url, title, text: finalText, truncated };
+}
+
+/**
+ * Strip HTML to readable text. Removes scripts/styles/nav/footer/aside
+ * blocks first, then tags, then collapses whitespace. Not a Readability
+ * clone — purpose-built to keep the extracted text small enough for the
+ * tool-result budget while preserving paragraph breaks.
+ */
+export function htmlToText(html: string): string {
+  let s = html;
+  s = s.replace(/<script[\s\S]*?<\/script>/gi, "");
+  s = s.replace(/<style[\s\S]*?<\/style>/gi, "");
+  s = s.replace(/<noscript[\s\S]*?<\/noscript>/gi, "");
+  s = s.replace(/<nav[\s\S]*?<\/nav>/gi, "");
+  s = s.replace(/<footer[\s\S]*?<\/footer>/gi, "");
+  s = s.replace(/<aside[\s\S]*?<\/aside>/gi, "");
+  s = s.replace(/<svg[\s\S]*?<\/svg>/gi, "");
+  // Preserve paragraph breaks by turning common block tags into newlines.
+  s = s.replace(/<\/?(p|div|br|h[1-6]|li|tr|section|article)\b[^>]*>/gi, "\n");
+  s = s.replace(/<[^>]+>/g, "");
+  s = decodeHtmlEntities(s);
+  s = s.replace(/[ \t]+/g, " ");
+  s = s.replace(/\n[ \t]+/g, "\n");
+  s = s.replace(/\n{3,}/g, "\n\n");
+  return s.trim();
+}
+
+function stripHtml(s: string): string {
+  return s.replace(/<[^>]+>/g, "");
+}
+
+function decodeHtmlEntities(s: string): string {
+  return s
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+}
+
+function extractTitle(html: string): string | undefined {
+  const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  if (!m?.[1]) return undefined;
+  return m[1].replace(/\s+/g, " ").trim() || undefined;
+}
+
+export interface WebToolsOptions {
+  /** Default top-K for `web_search` when the model doesn't specify. */
+  defaultTopK?: number;
+  /** Byte cap for `web_fetch` extracted text. */
+  maxFetchChars?: number;
+}
+
+/**
+ * Register `web_search` + `web_fetch` on a ToolRegistry. The model
+ * invokes them automatically when a question needs current info —
+ * no slash command from the user is required.
+ */
+export function registerWebTools(registry: ToolRegistry, opts: WebToolsOptions = {}): ToolRegistry {
+  const defaultTopK = opts.defaultTopK ?? DEFAULT_TOPK;
+  const maxFetchChars = opts.maxFetchChars ?? DEFAULT_FETCH_MAX_CHARS;
+
+  registry.register({
+    name: "web_search",
+    description:
+      "Search the public web. Returns ranked results with title, url, and snippet. Use this when the question needs information more current than your training data, when you're unsure of a factual detail, or when the user asks about a specific webpage/library/release you haven't seen.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural-language search query." },
+        topK: {
+          type: "integer",
+          description: `Number of results to return (1..10). Default ${defaultTopK}.`,
+        },
+      },
+      required: ["query"],
+    },
+    fn: async (args: { query: string; topK?: number }, ctx) => {
+      const results = await webSearch(args.query, {
+        topK: args.topK ?? defaultTopK,
+        signal: ctx?.signal,
+      });
+      return formatSearchResults(args.query, results);
+    },
+  });
+
+  registry.register({
+    name: "web_fetch",
+    description:
+      "Download a URL and return its visible text content (HTML pages get scripts/styles/nav stripped). Truncated at the tool-result cap. Use after web_search when a snippet isn't enough.",
+    readOnly: true,
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "Absolute http:// or https:// URL." },
+      },
+      required: ["url"],
+    },
+    fn: async (args: { url: string }, ctx) => {
+      if (!/^https?:\/\//i.test(args.url)) {
+        throw new Error("web_fetch: url must start with http:// or https://");
+      }
+      const page = await webFetch(args.url, { maxChars: maxFetchChars, signal: ctx?.signal });
+      const header = page.title ? `${page.title}\n${page.url}` : page.url;
+      return `${header}\n\n${page.text}`;
+    },
+  });
+
+  return registry;
+}
+
+export function formatSearchResults(query: string, results: SearchResult[]): string {
+  const lines: string[] = [`query: ${query}`, `\nresults (${results.length}):`];
+  results.forEach((r, i) => {
+    lines.push(`\n${i + 1}. ${r.title}`);
+    lines.push(`   ${r.url}`);
+    if (r.snippet) lines.push(`   ${r.snippet}`);
+  });
+  return lines.join("\n");
+}

src/types.ts

@@ -36,6 +36,14 @@ export interface ChatMessage {
   name?: string;
   tool_call_id?: string;
   tool_calls?: ToolCall[];
+  /**
+   * R1 `reasoning_content` captured from the assistant's thinking turn.
+   * DeepSeek's thinking mode 400s with "reasoning_content in the
+   * thinking mode must be passed back" when a tool-loop continuation
+   * omits it from the preceding assistant message. Round-tripped for
+   * deepseek-reasoner turns with tool_calls; absent for deepseek-chat.
+   */
+  reasoning_content?: string | null;
 }
 
 export interface RawUsage {

src/usage.ts

@@ -0,0 +1,347 @@
+/**
+ * Persistent per-turn usage log at `~/.reasonix/usage.jsonl`.
+ *
+ * Each line is a single `UsageRecord` — one turn's tokens + cost
+ * snapshot — appended after every `assistant_final` event. This is
+ * what drives `reasonix stats` (the dashboard, no-arg form), so the
+ * user can see how much they've spent vs what the equivalent Claude
+ * spend would have been. The Pillar 1 pitch (94–97% cost reduction
+ * vs Claude, from the v0.3 hard-number table) becomes a fact users
+ * can verify on their own machine.
+ *
+ * Format choices:
+ *   - **append-only JSONL** — one line per turn, durable, survives
+ *     abrupt exits. A corrupted tail line loses at most one record.
+ *   - **flat keys, no nesting** — readable with `jq` / `cut` / `awk`;
+ *     the model doesn't need to parse this, humans do.
+ *   - **best-effort writes** — disk errors never propagate into the
+ *     turn. We log nothing (no `console.error`) because the TUI is
+ *     rendering Ink; a silent skip is the least-worst failure mode.
+ *   - **no PII, no prompts, no completions** — the log contains
+ *     tokens and costs, that's it. Sessions are identified by the
+ *     user-chosen name (never a prompt).
+ *
+ * This file is deliberately NOT wired through project memory or
+ * skills — those are content pins. Usage is pure telemetry.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Usage } from "./client.js";
+import {
+  CLAUDE_SONNET_PRICING,
+  DEEPSEEK_PRICING,
+  claudeEquivalentCost,
+  costUsd,
+} from "./telemetry.js";
+
+/** One turn's snapshot — serialized verbatim as a JSONL line. */
+export interface UsageRecord {
+  /** Epoch millis when the record was written. */
+  ts: number;
+  /** Session name if the turn ran inside a persisted session, `null` for ephemeral. */
+  session: string | null;
+  /** Model id the turn ran against (drives the pricing lookup). */
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  cacheHitTokens: number;
+  cacheMissTokens: number;
+  /** Total cost of the turn in USD. */
+  costUsd: number;
+  /** What the same turn would have cost at Claude Sonnet 4.6 rates. */
+  claudeEquivUsd: number;
+  /**
+   * Distinguishes ordinary parent-loop turns from subagent summary rows.
+   * Absent on pre-0.5.14 records — treat as "turn" when missing.
+   */
+  kind?: "turn" | "subagent";
+  /** Present when `kind === "subagent"`. Attribution metadata for the /stats roll-up. */
+  subagent?: {
+    /** Skill that spawned it, when the spawn came from a `runAs: subagent` skill. */
+    skillName?: string;
+    /** First ~60 chars of the task prompt — enough context to recognize a run, never the full text. */
+    taskPreview: string;
+    /** Tool calls the child loop dispatched before returning. */
+    toolIters: number;
+    /** Wall-clock ms. */
+    durationMs: number;
+  };
+}
+
+/** Where the log lives. Tests override via `opts.path`. */
+export function defaultUsageLogPath(homeDirOverride?: string): string {
+  return join(homeDirOverride ?? homedir(), ".reasonix", "usage.jsonl");
+}
+
+export interface AppendUsageInput {
+  session: string | null;
+  model: string;
+  usage: Usage;
+  /** Override the timestamp (tests). */
+  now?: number;
+  /** Override the log path (tests). */
+  path?: string;
+  /** When appending a subagent summary row, set `kind: "subagent"` and populate `subagent`. */
+  kind?: "turn" | "subagent";
+  subagent?: UsageRecord["subagent"];
+}
+
+/**
+ * Append one record and return it. Swallows disk errors — the TUI
+ * should keep working even if `~/.reasonix/` is read-only.
+ *
+ * Returns the record that was written (or would have been written
+ * if the disk had cooperated) so tests / callers can assert on the
+ * computed cost fields without a round trip through the log file.
+ */
+export function appendUsage(input: AppendUsageInput): UsageRecord {
+  const record: UsageRecord = {
+    ts: input.now ?? Date.now(),
+    session: input.session,
+    model: input.model,
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    cacheHitTokens: input.usage.promptCacheHitTokens,
+    cacheMissTokens: input.usage.promptCacheMissTokens,
+    costUsd: costUsd(input.model, input.usage),
+    claudeEquivUsd: claudeEquivalentCost(input.usage),
+  };
+  if (input.kind === "subagent") record.kind = "subagent";
+  if (input.subagent) record.subagent = input.subagent;
+
+  const path = input.path ?? defaultUsageLogPath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+  } catch {
+    /* best-effort — disk failure shouldn't break the chat */
+  }
+  return record;
+}
+
+/**
+ * Read + parse the log. Malformed lines are silently skipped so a
+ * single corrupted write (half-flushed on power loss, user hand-edit)
+ * doesn't throw away the rest of the history.
+ */
+export function readUsageLog(path: string = defaultUsageLogPath()): UsageRecord[] {
+  if (!existsSync(path)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out: UsageRecord[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (isValidRecord(rec)) out.push(rec);
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return out;
+}
+
+function isValidRecord(rec: unknown): rec is UsageRecord {
+  if (!rec || typeof rec !== "object") return false;
+  const r = rec as Partial<UsageRecord>;
+  return (
+    typeof r.ts === "number" &&
+    typeof r.model === "string" &&
+    typeof r.promptTokens === "number" &&
+    typeof r.completionTokens === "number" &&
+    typeof r.cacheHitTokens === "number" &&
+    typeof r.cacheMissTokens === "number" &&
+    typeof r.costUsd === "number" &&
+    typeof r.claudeEquivUsd === "number"
+  );
+}
+
+/** One row of the `reasonix stats` dashboard — a rolled-up window. */
+export interface UsageBucket {
+  label: string;
+  /** Start of the window as epoch millis. `0` = unbounded (all-time). */
+  since: number;
+  turns: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheHitTokens: number;
+  cacheMissTokens: number;
+  costUsd: number;
+  claudeEquivUsd: number;
+}
+
+/** Cache hit ratio for a bucket — zero denominator returns 0. */
+export function bucketCacheHitRatio(b: UsageBucket): number {
+  const denom = b.cacheHitTokens + b.cacheMissTokens;
+  return denom > 0 ? b.cacheHitTokens / denom : 0;
+}
+
+/** Savings vs Claude as a fraction (0.94 = 94% savings). 0 if Claude cost is 0. */
+export function bucketSavingsFraction(b: UsageBucket): number {
+  return b.claudeEquivUsd > 0 ? 1 - b.costUsd / b.claudeEquivUsd : 0;
+}
+
+function emptyBucket(label: string, since: number): UsageBucket {
+  return {
+    label,
+    since,
+    turns: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cacheHitTokens: 0,
+    cacheMissTokens: 0,
+    costUsd: 0,
+    claudeEquivUsd: 0,
+  };
+}
+
+function addToBucket(b: UsageBucket, r: UsageRecord): void {
+  b.turns += 1;
+  b.promptTokens += r.promptTokens;
+  b.completionTokens += r.completionTokens;
+  b.cacheHitTokens += r.cacheHitTokens;
+  b.cacheMissTokens += r.cacheMissTokens;
+  b.costUsd += r.costUsd;
+  b.claudeEquivUsd += r.claudeEquivUsd;
+}
+
+export interface AggregateOptions {
+  /** Override `Date.now()` for deterministic tests. */
+  now?: number;
+}
+
+export interface UsageAggregate {
+  /** Fixed-order rolling windows: today, week, month, all-time. */
+  buckets: UsageBucket[];
+  /** Model id → turn count. Sorted descending; top entry is the "most used." */
+  byModel: Array<{ model: string; turns: number }>;
+  /** Session name → turn count. Sorted descending. Null sessions are grouped under `"(ephemeral)"`. */
+  bySession: Array<{ session: string; turns: number }>;
+  /** Earliest record's ts, or `null` when the log is empty. Drives "saved $X since <date>". */
+  firstSeen: number | null;
+  /** Latest record's ts, or `null` when the log is empty. */
+  lastSeen: number | null;
+  /**
+   * Subagent-specific rollup. Undefined when no subagent records exist
+   * in the log so consumers can cheaply skip the section. Counts reflect
+   * subagent SPAWNS (not internal child-loop turns) — one row per run.
+   */
+  subagents?: SubagentAggregate;
+}
+
+/** Rolled-up view of all `kind: "subagent"` records. */
+export interface SubagentAggregate {
+  total: number;
+  costUsd: number;
+  totalDurationMs: number;
+  /** Per-skill breakdown. Records without `skillName` (raw spawn_subagent calls) group under `"(adhoc)"`. */
+  bySkill: Array<{ skillName: string; count: number; costUsd: number; durationMs: number }>;
+}
+
+/**
+ * Fold a flat record list into the dashboard shape — rolling windows
+ * plus model / session histograms. Windows are INCLUSIVE of boundary:
+ *   - today = last 24h (rolling, not calendar-day)
+ *   - week  = last 7d
+ *   - month = last 30d
+ *   - all   = every record
+ * Rolling windows avoid "it's 00:03, 'today' is empty" surprises.
+ */
+export function aggregateUsage(
+  records: UsageRecord[],
+  opts: AggregateOptions = {},
+): UsageAggregate {
+  const now = opts.now ?? Date.now();
+  const day = 24 * 60 * 60 * 1000;
+  const today = emptyBucket("today", now - day);
+  const week = emptyBucket("week", now - 7 * day);
+  const month = emptyBucket("month", now - 30 * day);
+  const all = emptyBucket("all-time", 0);
+
+  const modelCounts = new Map<string, number>();
+  const sessionCounts = new Map<string, number>();
+  let firstSeen: number | null = null;
+  let lastSeen: number | null = null;
+  const skillCounts = new Map<string, { count: number; costUsd: number; durationMs: number }>();
+  let subagentTotal = 0;
+  let subagentCost = 0;
+  let subagentDuration = 0;
+
+  for (const r of records) {
+    addToBucket(all, r);
+    if (r.ts >= today.since) addToBucket(today, r);
+    if (r.ts >= week.since) addToBucket(week, r);
+    if (r.ts >= month.since) addToBucket(month, r);
+
+    modelCounts.set(r.model, (modelCounts.get(r.model) ?? 0) + 1);
+    const sessKey = r.session ?? "(ephemeral)";
+    sessionCounts.set(sessKey, (sessionCounts.get(sessKey) ?? 0) + 1);
+
+    if (firstSeen === null || r.ts < firstSeen) firstSeen = r.ts;
+    if (lastSeen === null || r.ts > lastSeen) lastSeen = r.ts;
+
+    if (r.kind === "subagent") {
+      subagentTotal += 1;
+      subagentCost += r.costUsd;
+      const dur = r.subagent?.durationMs ?? 0;
+      subagentDuration += dur;
+      const key = r.subagent?.skillName?.trim() || "(adhoc)";
+      const prev = skillCounts.get(key) ?? { count: 0, costUsd: 0, durationMs: 0 };
+      prev.count += 1;
+      prev.costUsd += r.costUsd;
+      prev.durationMs += dur;
+      skillCounts.set(key, prev);
+    }
+  }
+
+  const byModel = Array.from(modelCounts.entries())
+    .map(([model, turns]) => ({ model, turns }))
+    .sort((a, b) => b.turns - a.turns);
+  const bySession = Array.from(sessionCounts.entries())
+    .map(([session, turns]) => ({ session, turns }))
+    .sort((a, b) => b.turns - a.turns);
+
+  const subagents: SubagentAggregate | undefined =
+    subagentTotal > 0
+      ? {
+          total: subagentTotal,
+          costUsd: subagentCost,
+          totalDurationMs: subagentDuration,
+          bySkill: Array.from(skillCounts.entries())
+            .map(([skillName, v]) => ({ skillName, ...v }))
+            .sort((a, b) => b.count - a.count),
+        }
+      : undefined;
+
+  return {
+    buckets: [today, week, month, all],
+    byModel,
+    bySession,
+    firstSeen,
+    lastSeen,
+    subagents,
+  };
+}
+
+/** File-size helper for the stats header — "1.2 MB" etc. Returns "" if missing. */
+export function formatLogSize(path: string = defaultUsageLogPath()): string {
+  if (!existsSync(path)) return "";
+  try {
+    const s = statSync(path);
+    const bytes = s.size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  } catch {
+    return "";
+  }
+}
+
+/** Re-exports for downstream consumers that also want the pricing constants. */
+export { CLAUDE_SONNET_PRICING, DEEPSEEK_PRICING };

src/user-memory.ts

@@ -0,0 +1,395 @@
+/**
+ * User memory — `~/.reasonix/memory/` markdown notes pinned into the
+ * immutable-prefix system prompt across sessions.
+ *
+ * Two scopes:
+ *   - `global`  → `~/.reasonix/memory/global/`         (cross-project)
+ *   - `project` → `~/.reasonix/memory/<hash>/`          (per sandbox root)
+ *
+ * Each scope has an always-loaded `MEMORY.md` index plus zero-or-more
+ * `<name>.md` detail files loaded on demand via `recall_memory`.
+ *
+ * Distinct from `src/project-memory.ts` (REASONIX.md) in purpose:
+ *   REASONIX.md        is committable, team-shared project memory.
+ *   ~/.reasonix/memory is user-private memory, never committed.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { applyProjectMemory, memoryEnabled } from "./project-memory.js";
+import { applySkillsIndex } from "./skills.js";
+
+export const USER_MEMORY_DIR = "memory";
+export const MEMORY_INDEX_FILE = "MEMORY.md";
+/** Cap on the index file content loaded into the prefix, per scope. */
+export const MEMORY_INDEX_MAX_CHARS = 4000;
+
+export type MemoryType = "user" | "feedback" | "project" | "reference";
+export type MemoryScope = "global" | "project";
+
+export interface MemoryEntry {
+  name: string;
+  type: MemoryType;
+  scope: MemoryScope;
+  description: string;
+  body: string;
+  /** ISO date string (YYYY-MM-DD). */
+  createdAt: string;
+}
+
+export interface MemoryStoreOptions {
+  /** Override `~/.reasonix` — tests set this to a tmpdir. */
+  homeDir?: string;
+  /** Absolute sandbox root. Required to use `scope: "project"`. */
+  projectRoot?: string;
+}
+
+export interface WriteInput {
+  name: string;
+  type: MemoryType;
+  scope: MemoryScope;
+  description: string;
+  body: string;
+}
+
+const VALID_NAME = /^[a-zA-Z0-9_-][a-zA-Z0-9_.-]{1,38}[a-zA-Z0-9]$/;
+
+/**
+ * Throws on filename injection attempts (`../foo`, `foo/bar`, leading
+ * dots, etc.). Allowed: 3-40 chars, alnum + `_` + `-` + interior `.`.
+ */
+export function sanitizeMemoryName(raw: string): string {
+  const trimmed = String(raw ?? "").trim();
+  if (!VALID_NAME.test(trimmed)) {
+    throw new Error(
+      `invalid memory name: ${JSON.stringify(raw)} — must be 3-40 chars, alnum/_/-, no path separators`,
+    );
+  }
+  return trimmed;
+}
+
+/** Stable 16-hex-char hash of an absolute sandbox root path. */
+export function projectHash(rootDir: string): string {
+  const abs = resolve(rootDir);
+  return createHash("sha1").update(abs).digest("hex").slice(0, 16);
+}
+
+function scopeDir(opts: { homeDir: string; scope: MemoryScope; projectRoot?: string }): string {
+  if (opts.scope === "global") {
+    return join(opts.homeDir, USER_MEMORY_DIR, "global");
+  }
+  if (!opts.projectRoot) {
+    throw new Error("scope=project requires a projectRoot on MemoryStore");
+  }
+  return join(opts.homeDir, USER_MEMORY_DIR, projectHash(opts.projectRoot));
+}
+
+function ensureDir(p: string): void {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+/**
+ * Parse a `---` frontmatter block off the top of a markdown string.
+ * Tolerates missing frontmatter, returning `{}` for data and the full
+ * string as body. Only recognizes the simple `key: value` shape — no
+ * quoting, no multi-line, no YAML features. Matches what we emit.
+ */
+function parseFrontmatter(raw: string): { data: Record<string, string>; body: string } {
+  const lines = raw.split(/\r?\n/);
+  if (lines[0] !== "---") return { data: {}, body: raw };
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return { data: {}, body: raw };
+  const data: Record<string, string> = {};
+  for (let i = 1; i < end; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (m?.[1]) data[m[1]] = (m[2] ?? "").trim();
+  }
+  return {
+    data,
+    body: lines
+      .slice(end + 1)
+      .join("\n")
+      .replace(/^\n+/, ""),
+  };
+}
+
+function formatFrontmatter(e: WriteInput & { createdAt: string }): string {
+  return [
+    "---",
+    `name: ${e.name}`,
+    `description: ${e.description.replace(/\n/g, " ")}`,
+    `type: ${e.type}`,
+    `scope: ${e.scope}`,
+    `created: ${e.createdAt}`,
+    "---",
+    "",
+  ].join("\n");
+}
+
+function todayIso(): string {
+  const d = new Date();
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * A `MEMORY.md` index line for one entry. One-liner, under ~150 chars.
+ * `description` is truncated if it would push past the soft limit.
+ */
+function indexLine(e: Pick<MemoryEntry, "name" | "description">): string {
+  const safeDesc = e.description.replace(/\n/g, " ").trim();
+  const max = 130 - e.name.length;
+  const clipped = safeDesc.length > max ? `${safeDesc.slice(0, Math.max(1, max - 1))}…` : safeDesc;
+  return `- [${e.name}](${e.name}.md) — ${clipped}`;
+}
+
+export class MemoryStore {
+  private readonly homeDir: string;
+  private readonly projectRoot: string | undefined;
+
+  constructor(opts: MemoryStoreOptions = {}) {
+    this.homeDir = opts.homeDir ?? join(homedir(), ".reasonix");
+    this.projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : undefined;
+  }
+
+  /** Directory this store writes `scope` files into, creating it if needed. */
+  dir(scope: MemoryScope): string {
+    const d = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+    ensureDir(d);
+    return d;
+  }
+
+  /** Absolute path to a memory file (no existence check). */
+  pathFor(scope: MemoryScope, name: string): string {
+    return join(this.dir(scope), `${sanitizeMemoryName(name)}.md`);
+  }
+
+  /** True iff this store is configured with a project scope available. */
+  hasProjectScope(): boolean {
+    return this.projectRoot !== undefined;
+  }
+
+  /**
+   * Read the `MEMORY.md` index for a scope. Returns post-cap content
+   * (with a truncation marker if clipped), or `null` when absent / empty.
+   */
+  loadIndex(
+    scope: MemoryScope,
+  ): { content: string; originalChars: number; truncated: boolean } | null {
+    if (scope === "project" && !this.projectRoot) return null;
+    const file = join(
+      scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot }),
+      MEMORY_INDEX_FILE,
+    );
+    if (!existsSync(file)) return null;
+    let raw: string;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch {
+      return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) return null;
+    const originalChars = trimmed.length;
+    const truncated = originalChars > MEMORY_INDEX_MAX_CHARS;
+    const content = truncated
+      ? `${trimmed.slice(0, MEMORY_INDEX_MAX_CHARS)}\n… (truncated ${originalChars - MEMORY_INDEX_MAX_CHARS} chars)`
+      : trimmed;
+    return { content, originalChars, truncated };
+  }
+
+  /** Read one memory file's body (frontmatter stripped). Throws if missing. */
+  read(scope: MemoryScope, name: string): MemoryEntry {
+    const file = this.pathFor(scope, name);
+    if (!existsSync(file)) {
+      throw new Error(`memory not found: scope=${scope} name=${name}`);
+    }
+    const raw = readFileSync(file, "utf8");
+    const { data, body } = parseFrontmatter(raw);
+    return {
+      name: data.name ?? name,
+      type: (data.type as MemoryType) ?? "project",
+      scope: (data.scope as MemoryScope) ?? scope,
+      description: data.description ?? "",
+      body: body.trim(),
+      createdAt: data.created ?? "",
+    };
+  }
+
+  /**
+   * List every memory in this store. Scans both scopes (skips project
+   * scope if unconfigured). Silently skips malformed files; the index
+   * must stay queryable even if one file is hand-edited into nonsense.
+   */
+  list(): MemoryEntry[] {
+    const out: MemoryEntry[] = [];
+    const scopes: MemoryScope[] = this.projectRoot ? ["global", "project"] : ["global"];
+    for (const scope of scopes) {
+      const dir = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+      if (!existsSync(dir)) continue;
+      let entries: string[];
+      try {
+        entries = readdirSync(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (entry === MEMORY_INDEX_FILE) continue;
+        if (!entry.endsWith(".md")) continue;
+        const name = entry.slice(0, -3);
+        try {
+          out.push(this.read(scope, name));
+        } catch {
+          // malformed file — skip rather than fail the whole list
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Write a new memory (or overwrite existing). Creates the scope dir,
+   * writes the `.md` file, and regenerates `MEMORY.md`. Returns the
+   * absolute path written to.
+   */
+  write(input: WriteInput): string {
+    if (input.scope === "project" && !this.projectRoot) {
+      throw new Error("cannot write project-scoped memory: no projectRoot configured");
+    }
+    const name = sanitizeMemoryName(input.name);
+    const desc = String(input.description ?? "").trim();
+    if (!desc) throw new Error("memory description cannot be empty");
+    const body = String(input.body ?? "").trim();
+    if (!body) throw new Error("memory body cannot be empty");
+    const entry: WriteInput & { createdAt: string } = {
+      ...input,
+      name,
+      description: desc,
+      body,
+      createdAt: todayIso(),
+    };
+    const dir = this.dir(input.scope);
+    const file = join(dir, `${name}.md`);
+    const content = `${formatFrontmatter(entry)}${body}\n`;
+    writeFileSync(file, content, "utf8");
+    this.regenerateIndex(input.scope);
+    return file;
+  }
+
+  /** Delete one memory + its index line. No-op if the file is already gone. */
+  delete(scope: MemoryScope, rawName: string): boolean {
+    if (scope === "project" && !this.projectRoot) {
+      throw new Error("cannot delete project-scoped memory: no projectRoot configured");
+    }
+    const file = this.pathFor(scope, rawName);
+    if (!existsSync(file)) return false;
+    unlinkSync(file);
+    this.regenerateIndex(scope);
+    return true;
+  }
+
+  /**
+   * Rebuild `MEMORY.md` from the `.md` files currently in the scope dir.
+   * Called after every write/delete. Sorted by name for stable prefix
+   * hashing — two stores with the same set of files produce byte-identical
+   * MEMORY.md content, keeping the cache prefix reproducible.
+   */
+  private regenerateIndex(scope: MemoryScope): void {
+    const dir = scopeDir({ homeDir: this.homeDir, scope, projectRoot: this.projectRoot });
+    if (!existsSync(dir)) return;
+    let files: string[];
+    try {
+      files = readdirSync(dir);
+    } catch {
+      return;
+    }
+    const mdFiles = files
+      .filter((f) => f !== MEMORY_INDEX_FILE && f.endsWith(".md"))
+      .sort((a, b) => a.localeCompare(b));
+    const indexPath = join(dir, MEMORY_INDEX_FILE);
+    if (mdFiles.length === 0) {
+      if (existsSync(indexPath)) unlinkSync(indexPath);
+      return;
+    }
+    const lines: string[] = [];
+    for (const f of mdFiles) {
+      const name = f.slice(0, -3);
+      try {
+        const entry = this.read(scope, name);
+        lines.push(indexLine({ name: entry.name || name, description: entry.description }));
+      } catch {
+        // Malformed: still surface it in the index so the user notices.
+        lines.push(`- [${name}](${name}.md) — (malformed, check frontmatter)`);
+      }
+    }
+    writeFileSync(indexPath, `${lines.join("\n")}\n`, "utf8");
+  }
+}
+
+/**
+ * Append `MEMORY_GLOBAL` and (optionally) `MEMORY_PROJECT` blocks to
+ * `basePrompt`. Omits a block entirely when its index is absent — an
+ * empty tag would add bytes to the prefix hash without content.
+ * Respects `REASONIX_MEMORY=off` via `memoryEnabled()` from
+ * `project-memory.ts`.
+ */
+export function applyUserMemory(
+  basePrompt: string,
+  opts: { homeDir?: string; projectRoot?: string } = {},
+): string {
+  if (!memoryEnabled()) return basePrompt;
+  const store = new MemoryStore(opts);
+  const global = store.loadIndex("global");
+  const project = store.hasProjectScope() ? store.loadIndex("project") : null;
+  if (!global && !project) return basePrompt;
+  const parts: string[] = [basePrompt];
+  if (global) {
+    parts.push(
+      "",
+      "# User memory — global (~/.reasonix/memory/global/MEMORY.md)",
+      "",
+      "Cross-project facts and preferences the user has told you in prior sessions. TREAT AS AUTHORITATIVE — don't re-verify via filesystem or web. One-liners index detail files; call `recall_memory` for full bodies only when the one-liner isn't enough.",
+      "",
+      "```",
+      global.content,
+      "```",
+    );
+  }
+  if (project) {
+    parts.push(
+      "",
+      "# User memory — this project",
+      "",
+      "Per-project facts the user established in prior sessions (not committed to the repo). TREAT AS AUTHORITATIVE. Same recall pattern as global memory.",
+      "",
+      "```",
+      project.content,
+      "```",
+    );
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Compose every lazy-loaded prefix block in one call: REASONIX.md,
+ * user memory (global + project), and the skills index. Drop-in
+ * replacement for `applyProjectMemory` at CLI entry points. Stacking
+ * order is stable — the prefix hash only changes when block *content*
+ * changes, not when this helper is called a second time with the same
+ * filesystem state.
+ */
+export function applyMemoryStack(basePrompt: string, rootDir: string): string {
+  const withProject = applyProjectMemory(basePrompt, rootDir);
+  const withMemory = applyUserMemory(withProject, { projectRoot: rootDir });
+  return applySkillsIndex(withMemory, { projectRoot: rootDir });
+}

src/version.ts

@@ -0,0 +1,209 @@
+/**
+ * Version module.
+ *
+ * Two jobs:
+ *
+ *   1. Expose `VERSION` sourced from the real `package.json` so the
+ *      constant never drifts from what npm publishes. Works in dev
+ *      (`tsx src/...`) AND after `tsup` bundles to `dist/` — both
+ *      layouts sit two levels below the manifest, so a short
+ *      walk-up finds it.
+ *
+ *   2. Offer an opt-in `getLatestVersion()` that hits the npm
+ *      registry with a bounded timeout and a 24-hour on-disk
+ *      cache at `~/.reasonix/version-cache.json`. Returns `null`
+ *      on any failure — offline / restricted-network launches
+ *      should stay silent rather than nag the user.
+ *
+ * The CLI wires `getLatestVersion` asynchronously at App mount
+ * (never in a hot path) and renders the outcome in the stats
+ * panel when there's a newer published version.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** npm registry endpoint for the `latest` dist-tag of this package. */
+const REGISTRY_URL = "https://registry.npmjs.org/reasonix/latest";
+
+/** TTL for the on-disk cache entry. 24h keeps noise low; users who
+ * want a fresh check can run `reasonix update` which passes
+ * `force: true`. */
+export const LATEST_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Network timeout. Short — we never block the UI waiting on this. */
+export const LATEST_FETCH_TIMEOUT_MS = 2_000;
+
+/**
+ * Walk up from the current source file looking for the `reasonix`
+ * package.json. Works for:
+ *   - dev: `src/version.ts` → `F:/Reasonix/package.json` (2 levels up)
+ *   - built: `dist/index.js` → `F:/Reasonix/package.json` (2 levels up)
+ *   - global install: `.../node_modules/reasonix/dist/index.js` → `.../reasonix/package.json`
+ *
+ * The `name === "reasonix"` guard is a cheap safety net against
+ * picking up the nearest *other* package.json if we're ever loaded
+ * as a dependency and the layout is unusual.
+ */
+function readPackageVersion(): string {
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+      const p = join(dir, "package.json");
+      if (existsSync(p)) {
+        const pkg = JSON.parse(readFileSync(p, "utf8"));
+        if (pkg?.name === "reasonix" && typeof pkg.version === "string") {
+          return pkg.version;
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    /* fall through to fallback */
+  }
+  return "0.0.0-dev";
+}
+
+export const VERSION: string = readPackageVersion();
+
+interface VersionCacheEntry {
+  version: string;
+  /** Epoch millis the entry was written. Drives TTL comparisons. */
+  checkedAt: number;
+}
+
+function cachePath(homeDirOverride?: string): string {
+  return join(homeDirOverride ?? homedir(), ".reasonix", "version-cache.json");
+}
+
+function readCache(homeDirOverride?: string): VersionCacheEntry | null {
+  try {
+    const raw = readFileSync(cachePath(homeDirOverride), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.version === "string" && typeof parsed.checkedAt === "number") {
+      return parsed;
+    }
+  } catch {
+    /* missing or malformed → no cached entry */
+  }
+  return null;
+}
+
+function writeCache(entry: VersionCacheEntry, homeDirOverride?: string): void {
+  try {
+    const p = cachePath(homeDirOverride);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(entry), "utf8");
+  } catch {
+    /* cache is best-effort — a failed write just means we'll re-fetch
+     * next launch. No reason to surface this to the user. */
+  }
+}
+
+export interface GetLatestVersionOptions {
+  /** Ignore the cached entry and always fetch fresh. Used by `reasonix update`. */
+  force?: boolean;
+  /** Registry URL override (tests). */
+  registryUrl?: string;
+  /** Home-directory override (tests). */
+  homeDir?: string;
+  /** Fetch implementation override (tests). Defaults to `globalThis.fetch`. */
+  fetchImpl?: typeof fetch;
+  /** TTL override (tests). */
+  ttlMs?: number;
+  /** Network timeout override (tests). */
+  timeoutMs?: number;
+}
+
+/**
+ * Resolve the latest published `reasonix` version from the npm registry.
+ *
+ * Returns `null` on any network / parse failure. Callers treat `null`
+ * as "don't know, don't nag the user." The cache entry is only
+ * written on a successful fetch — a bad registry response won't
+ * poison the cache.
+ */
+export async function getLatestVersion(opts: GetLatestVersionOptions = {}): Promise<string | null> {
+  const ttl = opts.ttlMs ?? LATEST_CACHE_TTL_MS;
+  if (!opts.force) {
+    const cached = readCache(opts.homeDir);
+    if (cached && Date.now() - cached.checkedAt < ttl) return cached.version;
+  }
+
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) return null;
+  const url = opts.registryUrl ?? REGISTRY_URL;
+  const timeout = opts.timeoutMs ?? LATEST_FETCH_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { version?: unknown };
+    if (typeof body.version !== "string") return null;
+    writeCache({ version: body.version, checkedAt: Date.now() }, opts.homeDir);
+    return body.version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Semver compare. Returns a negative number when `a < b`, positive
+ * when `a > b`, zero when equal.
+ *
+ * Minimal pre-release handling: when the CORE (`x.y.z`) parts match,
+ * any version WITH a suffix (`-rc.1`, `-alpha.4`) compares LOWER
+ * than the bare version. That matches npm's dist-tag semantics —
+ * `reasonix@latest` resolves to a real release, not a pre-release.
+ *
+ * We're deliberately not pulling in `semver` (~50KB). The three
+ * cases we care about are: current > latest (future build, no
+ * prompt), current < latest (prompt), current === latest (no prompt).
+ */
+export function compareVersions(a: string, b: string): number {
+  const [aCore = "0", aPre = ""] = a.split("-", 2);
+  const [bCore = "0", bPre = ""] = b.split("-", 2);
+  const aParts = aCore.split(".").map((p) => Number.parseInt(p, 10) || 0);
+  const bParts = bCore.split(".").map((p) => Number.parseInt(p, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  if (!aPre && !bPre) return 0;
+  if (!aPre) return 1;
+  if (!bPre) return -1;
+  return aPre < bPre ? -1 : aPre > bPre ? 1 : 0;
+}
+
+/**
+ * Heuristic: did this process launch via `npx` / `pnpm dlx` instead
+ * of a global install? The update command takes different advice in
+ * each case — a global install can `npm i -g reasonix@latest`, while
+ * npx just needs its cache to roll over on next launch.
+ *
+ * Signals checked, in order:
+ *   - `process.argv[1]` contains `_npx` (npm's ephemeral dir name)
+ *   - `process.argv[1]` contains `.pnpm` + `dlx`
+ *   - `npm_config_user_agent` contains `npx/`
+ *
+ * Any one hit → npx. False negatives are safe (worst case we suggest
+ * `npm i -g` to an npx user, which is a valid way to upgrade too).
+ */
+export function isNpxInstall(): boolean {
+  const bin = process.argv[1] ?? "";
+  if (/[/\\]_npx[/\\]/.test(bin)) return true;
+  if (/[/\\]\.pnpm[/\\]/.test(bin) && /dlx/i.test(bin)) return true;
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.includes("npx/")) return true;
+  return false;
+}

tests/at-mentions.test.ts

@@ -0,0 +1,372 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  AT_MENTION_PATTERN,
+  AT_PICKER_PREFIX,
+  DEFAULT_AT_MENTION_MAX_BYTES,
+  DEFAULT_PICKER_IGNORE_DIRS,
+  detectAtPicker,
+  expandAtMentions,
+  listFilesSync,
+  rankPickerCandidates,
+} from "../src/at-mentions.js";
+
+describe("AT_MENTION_PATTERN", () => {
+  it("matches @path at start of string", () => {
+    const matches = [...".".matchAll(AT_MENTION_PATTERN)];
+    expect(matches).toHaveLength(0);
+    const m2 = [..."@src/loop.ts".matchAll(AT_MENTION_PATTERN)];
+    expect(m2).toHaveLength(1);
+    expect(m2[0]![1]).toBe("src/loop.ts");
+  });
+
+  it("matches @path after whitespace", () => {
+    const m = [..."look at @src/loop.ts please".matchAll(AT_MENTION_PATTERN)];
+    expect(m).toHaveLength(1);
+    expect(m[0]![1]).toBe("src/loop.ts");
+  });
+
+  it("does NOT match @ embedded in a word (email, social handle)", () => {
+    const m1 = [..."email [email protected]".matchAll(AT_MENTION_PATTERN)];
+    expect(m1).toHaveLength(0);
+    const m2 = [..."foo@bar".matchAll(AT_MENTION_PATTERN)];
+    expect(m2).toHaveLength(0);
+  });
+
+  it("matches multiple @paths in one string", () => {
+    const m = [..."compare @a.ts and @b.ts".matchAll(AT_MENTION_PATTERN)];
+    expect(m).toHaveLength(2);
+    expect(m[0]![1]).toBe("a.ts");
+    expect(m[1]![1]).toBe("b.ts");
+  });
+});
+
+describe("expandAtMentions", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-at-mentions-"));
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(join(root, "src", "loop.ts"), "export const x = 1;\n");
+    writeFileSync(join(root, "notes.md"), "# Notes\nhello\n");
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns text unchanged when there are no mentions", () => {
+    const r = expandAtMentions("plain prompt with no mentions", root);
+    expect(r.text).toBe("plain prompt with no mentions");
+    expect(r.expansions).toEqual([]);
+  });
+
+  it("inlines an existing file under a `Referenced files` block", () => {
+    const r = expandAtMentions("look at @src/loop.ts", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.ok).toBe(true);
+    expect(r.expansions[0]!.path).toBe("src/loop.ts");
+    expect(r.text).toContain("look at @src/loop.ts");
+    expect(r.text).toContain("[Referenced files]");
+    expect(r.text).toContain('<file path="src/loop.ts">');
+    expect(r.text).toContain("export const x = 1;");
+    expect(r.text).toContain("</file>");
+  });
+
+  it("de-duplicates repeated mentions of the same file", () => {
+    const r = expandAtMentions("compare @src/loop.ts with @src/loop.ts", root);
+    expect(r.expansions).toHaveLength(1);
+    // Only one file block in the output.
+    const fileBlocks = r.text.match(/<file path="/g) ?? [];
+    expect(fileBlocks).toHaveLength(1);
+  });
+
+  it("expands multiple different files in the same prompt", () => {
+    const r = expandAtMentions("read @src/loop.ts and @notes.md", root);
+    expect(r.expansions).toHaveLength(2);
+    expect(r.expansions.every((ex) => ex.ok)).toBe(true);
+    expect(r.text).toContain('<file path="src/loop.ts">');
+    expect(r.text).toContain('<file path="notes.md">');
+  });
+
+  it("marks missing files as skipped with a reason", () => {
+    const r = expandAtMentions("look at @src/does-not-exist.ts", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.ok).toBe(false);
+    expect(r.expansions[0]!.skip).toBe("missing");
+    expect(r.text).toContain('skipped="missing"');
+  });
+
+  it("rejects paths that escape the root directory", () => {
+    const r = expandAtMentions("peek at @../../../etc/passwd", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.skip).toBe("escape");
+    expect(r.text).not.toContain("passwd content");
+  });
+
+  it("rejects absolute paths", () => {
+    const r = expandAtMentions("look at @/etc/hosts", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.skip).toBe("escape");
+  });
+
+  it("skips files larger than maxBytes", () => {
+    const big = join(root, "big.log");
+    writeFileSync(big, "x".repeat(1000));
+    const r = expandAtMentions("inspect @big.log", root, { maxBytes: 500 });
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.ok).toBe(false);
+    expect(r.expansions[0]!.skip).toBe("too-large");
+    expect(r.expansions[0]!.bytes).toBe(1000);
+    expect(r.text).toContain('skipped="too-large"');
+  });
+
+  it("strips a trailing sentence-terminator dot from the path", () => {
+    // `@src/loop.ts.` — the trailing `.` is a sentence period, not
+    // part of the filename. The mention should resolve src/loop.ts.
+    const r = expandAtMentions("look at @src/loop.ts.", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.ok).toBe(true);
+    expect(r.expansions[0]!.path).toBe("src/loop.ts");
+  });
+
+  it("default max bytes is 64KB", () => {
+    expect(DEFAULT_AT_MENTION_MAX_BYTES).toBe(64 * 1024);
+  });
+
+  it("marks a directory mention as not-file", () => {
+    const r = expandAtMentions("look at @src", root);
+    expect(r.expansions).toHaveLength(1);
+    expect(r.expansions[0]!.ok).toBe(false);
+    expect(r.expansions[0]!.skip).toBe("not-file");
+  });
+});
+
+describe("detectAtPicker", () => {
+  it("fires when the buffer ends with `@`", () => {
+    const r = detectAtPicker("look at @");
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe("");
+    // `@` is at offset 8 (after "look at ").
+    expect(r!.atOffset).toBe(8);
+  });
+
+  it("captures the partial query after `@`", () => {
+    const r = detectAtPicker("edit @src/lo");
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe("src/lo");
+    expect(r!.atOffset).toBe(5);
+  });
+
+  it("does NOT fire when @ is embedded in a word", () => {
+    expect(detectAtPicker("[email protected]")).toBeNull();
+  });
+
+  it("does NOT fire when the buffer ends with a space after the mention", () => {
+    // Trailing space closes the picker — the user's done picking.
+    expect(detectAtPicker("@src/loop.ts ")).toBeNull();
+  });
+
+  it("does NOT fire when there's no @ at all", () => {
+    expect(detectAtPicker("just a normal message")).toBeNull();
+  });
+
+  it("fires at start of string", () => {
+    const r = detectAtPicker("@sr");
+    expect(r).not.toBeNull();
+    expect(r!.query).toBe("sr");
+    expect(r!.atOffset).toBe(0);
+  });
+});
+
+describe("AT_PICKER_PREFIX vs AT_MENTION_PATTERN (sanity)", () => {
+  it("picker captures empty partial", () => {
+    const m = AT_PICKER_PREFIX.exec("hi @");
+    expect(m).not.toBeNull();
+    expect(m![1]).toBe("");
+  });
+
+  it("expansion pattern requires a non-empty path", () => {
+    // Completed mentions for expandAtMentions need at least one char.
+    const m = [..."hi @".matchAll(AT_MENTION_PATTERN)];
+    expect(m).toHaveLength(0);
+  });
+});
+
+describe("rankPickerCandidates", () => {
+  const files = [
+    "src/loop.ts",
+    "src/at-mentions.ts",
+    "src/tokenizer.ts",
+    "src/cli/ui/App.tsx",
+    "src/cli/ui/PromptInput.tsx",
+    "tests/loop.test.ts",
+    "tests/at-mentions.test.ts",
+    "README.md",
+  ];
+
+  it("returns the first `limit` entries when query is empty", () => {
+    const r = rankPickerCandidates(files, "", 3);
+    expect(r).toHaveLength(3);
+    expect(r).toEqual(files.slice(0, 3));
+  });
+
+  it("filters by substring match (case-insensitive)", () => {
+    const r = rankPickerCandidates(files, "LOOP");
+    expect(r).toContain("src/loop.ts");
+    expect(r).toContain("tests/loop.test.ts");
+    expect(r).not.toContain("README.md");
+  });
+
+  it("ranks basename-prefix matches above substring matches", () => {
+    // `ment` appears in "at-mentions" (both src and tests). Basenames
+    // are "at-mentions.ts" and "at-mentions.test.ts" — both start
+    // with `at-m` not `ment`. Not a basename-prefix hit; both should
+    // score the same (substring).
+    const r = rankPickerCandidates(files, "at-m");
+    // `at-m` is a basename prefix for both at-mentions files:
+    expect(r[0]).toMatch(/at-mentions/);
+    expect(r[1]).toMatch(/at-mentions/);
+  });
+
+  it("ranks path-prefix above substring when basename doesn't match", () => {
+    // `tests/` is a path prefix (not basename). Both tests/* hit.
+    const r = rankPickerCandidates(files, "tests/");
+    expect(r[0]).toMatch(/^tests\//);
+  });
+
+  it("returns empty array when nothing matches", () => {
+    const r = rankPickerCandidates(files, "zzznomatch");
+    expect(r).toEqual([]);
+  });
+
+  it("respects the limit parameter", () => {
+    const r = rankPickerCandidates(files, "s", 2);
+    expect(r).toHaveLength(2);
+  });
+
+  it("sorts by mtime descending when entries carry FileWithStats and query is empty", () => {
+    const entries = [
+      { path: "a.ts", mtimeMs: 100 },
+      { path: "b.ts", mtimeMs: 300 },
+      { path: "c.ts", mtimeMs: 200 },
+    ];
+    const r = rankPickerCandidates(entries, "", 5);
+    // Newest (b, mtime 300) → middle (c, 200) → oldest (a, 100).
+    expect(r).toEqual(["b.ts", "c.ts", "a.ts"]);
+  });
+
+  it("recently-used paths float to the top on empty query regardless of mtime", () => {
+    const entries = [
+      { path: "a.ts", mtimeMs: 300 },
+      { path: "b.ts", mtimeMs: 100 },
+      { path: "c.ts", mtimeMs: 200 },
+    ];
+    const r = rankPickerCandidates(entries, "", {
+      limit: 5,
+      recentlyUsed: ["c.ts"],
+    });
+    // Recently-used c.ts comes first even though a.ts has a newer mtime.
+    expect(r[0]).toBe("c.ts");
+    // Remaining sorted by mtime descending.
+    expect(r[1]).toBe("a.ts");
+    expect(r[2]).toBe("b.ts");
+  });
+
+  it("tie-breaks query matches by recently-used, then mtime", () => {
+    const entries = [
+      { path: "src/alpha.ts", mtimeMs: 100 },
+      { path: "src/alpha2.ts", mtimeMs: 500 }, // newer
+    ];
+    const r = rankPickerCandidates(entries, "alpha", { limit: 5 });
+    // Both match with the same score (basename prefix, same hit
+    // position) — mtime tiebreak puts alpha2 first.
+    expect(r[0]).toBe("src/alpha2.ts");
+    expect(r[1]).toBe("src/alpha.ts");
+
+    // Now with recency: older alpha.ts boosted over newer alpha2.ts.
+    const r2 = rankPickerCandidates(entries, "alpha", {
+      limit: 5,
+      recentlyUsed: ["src/alpha.ts"],
+    });
+    expect(r2[0]).toBe("src/alpha.ts");
+    expect(r2[1]).toBe("src/alpha2.ts");
+  });
+
+  it("preserves input order on empty query when no mtime + no recency signal", () => {
+    // Back-compat: bare string input behaves as before.
+    const r = rankPickerCandidates(files, "", 3);
+    expect(r).toEqual(files.slice(0, 3));
+  });
+
+  it("accepts a number literal as the third arg for limit (back-compat)", () => {
+    const r = rankPickerCandidates(files, "loop", 1);
+    expect(r).toHaveLength(1);
+  });
+});
+
+describe("listFilesSync", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-listfiles-"));
+    mkdirSync(join(root, "src"), { recursive: true });
+    mkdirSync(join(root, "src", "cli"), { recursive: true });
+    mkdirSync(join(root, "node_modules", "foo"), { recursive: true });
+    mkdirSync(join(root, ".git", "objects"), { recursive: true });
+    writeFileSync(join(root, "package.json"), "{}");
+    writeFileSync(join(root, "README.md"), "# hi");
+    writeFileSync(join(root, ".gitignore"), "dist/");
+    writeFileSync(join(root, "src", "index.ts"), "");
+    writeFileSync(join(root, "src", "cli", "app.ts"), "");
+    writeFileSync(join(root, "node_modules", "foo", "index.js"), "");
+    writeFileSync(join(root, ".git", "objects", "abc"), "");
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns files recursively, with forward-slash separators", () => {
+    const files = listFilesSync(root);
+    expect(files).toContain("package.json");
+    expect(files).toContain("README.md");
+    expect(files).toContain("src/index.ts");
+    expect(files).toContain("src/cli/app.ts");
+    // All entries use forward slashes even on Windows.
+    for (const f of files) {
+      expect(f).not.toContain("\\");
+    }
+  });
+
+  it("skips ignored directories by default", () => {
+    const files = listFilesSync(root);
+    expect(files.every((f) => !f.includes("node_modules"))).toBe(true);
+    expect(files.every((f) => !f.includes(".git/"))).toBe(true);
+  });
+
+  it("includes dotfiles at the top level (e.g. .gitignore)", () => {
+    const files = listFilesSync(root);
+    expect(files).toContain(".gitignore");
+  });
+
+  it("respects custom ignoreDirs", () => {
+    const files = listFilesSync(root, { ignoreDirs: ["src"] });
+    expect(files.every((f) => !f.startsWith("src/"))).toBe(true);
+    expect(files).toContain("package.json");
+  });
+
+  it("caps the result count at maxResults", () => {
+    const files = listFilesSync(root, { maxResults: 2 });
+    expect(files.length).toBeLessThanOrEqual(2);
+  });
+
+  it("returns an empty list for an unreadable root (falls through)", () => {
+    const files = listFilesSync(join(root, "does-not-exist"));
+    expect(files).toEqual([]);
+  });
+
+  it("exposes the default ignore list", () => {
+    expect(DEFAULT_PICKER_IGNORE_DIRS).toContain("node_modules");
+    expect(DEFAULT_PICKER_IGNORE_DIRS).toContain(".git");
+    expect(DEFAULT_PICKER_IGNORE_DIRS).toContain("dist");
+  });
+});

tests/bang.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { detectBangCommand, formatBangUserMessage } from "../src/cli/ui/bang.js";
+
+describe("detectBangCommand", () => {
+  it("returns the command body for a `!`-prefixed input", () => {
+    expect(detectBangCommand("!ls src/")).toBe("ls src/");
+    expect(detectBangCommand("!git status")).toBe("git status");
+  });
+
+  it("trims whitespace after the bang", () => {
+    expect(detectBangCommand("!  ls")).toBe("ls");
+    expect(detectBangCommand("!ls  ")).toBe("ls");
+  });
+
+  it("returns null for non-bang input", () => {
+    expect(detectBangCommand("ls src/")).toBeNull();
+    expect(detectBangCommand("hello world")).toBeNull();
+    expect(detectBangCommand("/help")).toBeNull();
+    expect(detectBangCommand("")).toBeNull();
+  });
+
+  it("returns null for `!` alone (no command body)", () => {
+    expect(detectBangCommand("!")).toBeNull();
+    expect(detectBangCommand("!   ")).toBeNull();
+  });
+
+  it("does NOT trigger when `!` appears mid-string", () => {
+    // Only leading `!` counts. Otherwise commands like `cat foo!bar`
+    // would be incorrectly intercepted.
+    expect(detectBangCommand("echo !hello")).toBeNull();
+    expect(detectBangCommand("what is ! for?")).toBeNull();
+  });
+
+  it("accepts a command with embedded `!` (not leading)", () => {
+    // The bang is at position 0; the trailing ! in `echo hi!` is
+    // part of the command body and passes through intact.
+    expect(detectBangCommand("!echo hi!")).toBe("echo hi!");
+  });
+
+  it("handles multi-word commands with flags and quotes", () => {
+    expect(detectBangCommand('!grep -R "foo bar" src/')).toBe('grep -R "foo bar" src/');
+  });
+});
+
+describe("formatBangUserMessage", () => {
+  it("prepends a `[!cmd]` header so the model can distinguish bang runs from its own tool output", () => {
+    const out = formatBangUserMessage("ls", "$ ls\n[exit 0]\nfile1 file2");
+    expect(out.startsWith("[!ls]\n")).toBe(true);
+    expect(out).toContain("$ ls");
+    expect(out).toContain("[exit 0]");
+    expect(out).toContain("file1 file2");
+  });
+
+  it("preserves the output verbatim after the header", () => {
+    const rawOutput = "line1\nline2\n\n[…truncated…]";
+    const formatted = formatBangUserMessage("cmd", rawOutput);
+    expect(formatted).toBe(`[!cmd]\n${rawOutput}`);
+  });
+});

tests/bundle-smoke.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Post-build smoke test for the bundled `dist/`.
+ *
+ * Unit tests load modules from `src/`, which means path-resolution
+ * bugs that only appear AFTER tsup bundles everything into a different
+ * directory layout never surface in the regular test suite. v0.5.4
+ * shipped to npm with exactly such a bug — `src/tokenizer.ts` at
+ * `dist/cli/index.js` tried to read the tokenizer data file relative
+ * to the bundled entry, ended up at `dist/data/...` instead of the
+ * package-root `data/...`, and every `reasonix run` crashed on first
+ * turn with ENOENT.
+ *
+ * These tests spawn the bundled output and verify the two bundle
+ * layouts (`dist/index.js` library + `dist/cli/index.js` CLI) can
+ * both locate the tokenizer data file. They're skipped when the
+ * build hasn't run yet (CI always runs `npm run build` first).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const LIB_BUNDLE = resolve("dist/index.js");
+const CLI_BUNDLE = resolve("dist/cli/index.js");
+
+describe("bundled dist — tokenizer path resolution", () => {
+  const libExists = existsSync(LIB_BUNDLE);
+  const cliExists = existsSync(CLI_BUNDLE);
+
+  (libExists ? it : it.skip)(
+    "dist/index.js resolves the tokenizer data file at package-root data/",
+    () => {
+      // truncateForModelByTokens internally calls countTokens when the
+      // input exceeds the fast-path threshold, which forces the
+      // tokenizer's lazy data-file load. If resolveDataPath() lands on
+      // a non-existent path (the 0.5.4 regression) this crashes with
+      // ENOENT and the spawned process exits non-zero.
+      // ESM dynamic imports on Windows require `file://` URLs, not bare
+      // absolute paths (which Node's ESM loader rejects as an unknown
+      // protocol). pathToFileURL handles the cross-platform form.
+      const libUrl = pathToFileURL(LIB_BUNDLE).href;
+      const result = spawnSync(
+        "node",
+        [
+          "--input-type=module",
+          "-e",
+          `import { truncateForModelByTokens } from "${libUrl}";
+           const s = "hello world ".repeat(500);
+           const out = truncateForModelByTokens(s, 100);
+           console.log(JSON.stringify({ ok: true, len: out.length }));`,
+        ],
+        { encoding: "utf8", timeout: 30_000 },
+      );
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/deepseek-tokenizer\.json\.gz/);
+      expect(result.stderr).not.toMatch(/ENOENT/);
+      expect(result.stdout).toMatch(/"ok":true/);
+    },
+  );
+
+  (cliExists ? it : it.skip)("dist/cli/index.js loads tokenizer before the first API fetch", () => {
+    // Spawn the CLI pointed at a bogus local address that fails fetch
+    // fast. In step(), preflight's estimateRequestTokens runs BEFORE
+    // client.chat — so if the bundled layout can't find the
+    // tokenizer data, we see ENOENT in stderr even though the fetch
+    // never happens. If tokenizer loads fine, we see a connection
+    // error instead (and that's OK — we're not testing the network
+    // path, only that the tokenizer path resolution works from
+    // dist/cli/).
+    const result = spawnSync("node", [CLI_BUNDLE, "run", "--no-config", "hi"], {
+      encoding: "utf8",
+      timeout: 10_000,
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: "sk-smoke-test-bogus",
+        // Fail-fast fetch target: the :1 port is almost never open,
+        // so we get connection-refused within ~1ms instead of the
+        // client's 120s timeout waiting on api.deepseek.com.
+        DEEPSEEK_BASE_URL: "http://127.0.0.1:1",
+      },
+    });
+    const combined = `${result.stdout}\n${result.stderr}`;
+    // The crucial assertion: bundle must not crash on the tokenizer
+    // path. Connection errors to 127.0.0.1:1 are expected and fine.
+    expect(combined).not.toMatch(/deepseek-tokenizer\.json\.gz/);
+    // Also not a missing-module style ENOENT (network errors are
+    // ECONNREFUSED or fetch failure, never ENOENT).
+    expect(combined).not.toMatch(/ENOENT.*tokenizer/i);
+  });
+});

tests/client-models.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+
+function makeFetch(status: number, body: unknown) {
+  return vi.fn(
+    async () =>
+      new Response(typeof body === "string" ? body : JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      }),
+  ) as unknown as typeof fetch;
+}
+
+describe("DeepSeekClient.listModels", () => {
+  it("parses the OpenAI-style model list", async () => {
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: makeFetch(200, {
+        object: "list",
+        data: [
+          { id: "deepseek-chat", object: "model", owned_by: "deepseek" },
+          { id: "deepseek-reasoner", object: "model", owned_by: "deepseek" },
+        ],
+      }),
+    });
+    const list = await client.listModels();
+    expect(list).not.toBeNull();
+    expect(list!.data.map((m) => m.id)).toEqual(["deepseek-chat", "deepseek-reasoner"]);
+  });
+
+  it("returns null on non-2xx (bad key / offline)", async () => {
+    const client = new DeepSeekClient({
+      apiKey: "sk-bad",
+      fetch: makeFetch(401, { error: "unauthorized" }),
+    });
+    expect(await client.listModels()).toBeNull();
+  });
+
+  it("returns null on malformed payload", async () => {
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: makeFetch(200, { whatever: "not a list" }),
+    });
+    expect(await client.listModels()).toBeNull();
+  });
+
+  it("returns null when fetch throws (network error)", async () => {
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async () => {
+        throw new Error("ECONNREFUSED");
+      }) as unknown as typeof fetch,
+    });
+    expect(await client.listModels()).toBeNull();
+  });
+
+  it("sends the bearer token header", async () => {
+    const spy = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ object: "list", data: [] }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+    );
+    const client = new DeepSeekClient({
+      apiKey: "sk-xyz",
+      fetch: spy as unknown as typeof fetch,
+    });
+    await client.listModels();
+    const [, init] = spy.mock.calls[0]!;
+    expect((init as RequestInit).method).toBe("GET");
+    const headers = (init as RequestInit).headers as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer sk-xyz");
+  });
+});

tests/code-prompt.test.ts

@@ -18,8 +18,14 @@ describe("codeSystemPrompt", () => {
     rmSync(root, { recursive: true, force: true });
   });
 
-  it("returns the base prompt unchanged when no .gitignore exists", () => {
-    expect(codeSystemPrompt(root)).toBe(CODE_SYSTEM_PROMPT);
+  it("does not append a .gitignore section when none exists", () => {
+    // We can no longer assert raw equality with CODE_SYSTEM_PROMPT —
+    // the bundled builtin skills (`explore`, `research`) always inject
+    // a `# Skills` block via applySkillsIndex. Assert the absence of
+    // the .gitignore-specific section instead.
+    const out = codeSystemPrompt(root);
+    expect(out).not.toMatch(/# Project \.gitignore/);
+    expect(out).toContain(CODE_SYSTEM_PROMPT);
   });
 
   it("appends the .gitignore content as a fenced block", () => {
@@ -36,15 +42,16 @@ describe("codeSystemPrompt", () => {
     writeFileSync(join(root, ".gitignore"), huge, "utf8");
     const out = codeSystemPrompt(root);
     expect(out).toMatch(/truncated \d+ chars/);
-    // The prompt (base + truncated + fences) is bounded, not 5000+.
-    expect(out.length).toBeLessThan(CODE_SYSTEM_PROMPT.length + 2300);
+    // The .gitignore block (base + truncated + fences) is bounded.
+    // Allow extra slack for the builtin Skills index that applyMemoryStack
+    // also injects — that's a fixed-size addition, not unbounded.
+    expect(out.length).toBeLessThan(CODE_SYSTEM_PROMPT.length + 4500);
   });
 
-  it("still reminds the model about built-in ignores even without a .gitignore", () => {
-    // Base prompt mentions node_modules / dist / .git as "avoid listing"
-    // so new-repo users without .gitignore still get the hint.
-    expect(CODE_SYSTEM_PROMPT).toMatch(/node_modules/);
-    expect(CODE_SYSTEM_PROMPT).toMatch(/dist/);
-    expect(CODE_SYSTEM_PROMPT).toMatch(/\.git/);
+  it("reminds the model to skip dependency / build / VCS dirs", () => {
+    // We don't enumerate specific names in the prompt anymore (too
+    // ecosystem-biased); the principle is stated generically and the
+    // pinned .gitignore block is the authoritative denylist.
+    expect(CODE_SYSTEM_PROMPT).toMatch(/dependency.*build.*VCS|skip/i);
   });
 });

tests/compact-tokens.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { shrinkOversizedToolResultsByTokens } from "../src/loop.js";
+import { countTokens } from "../src/tokenizer.js";
+import type { ChatMessage } from "../src/types.js";
+
+describe("shrinkOversizedToolResultsByTokens", () => {
+  it("leaves small tool messages alone", () => {
+    const msgs: ChatMessage[] = [
+      { role: "user", content: "hi" },
+      { role: "tool", tool_call_id: "t1", content: "short" },
+    ];
+    const r = shrinkOversizedToolResultsByTokens(msgs, 1000);
+    expect(r.healedCount).toBe(0);
+    expect(r.tokensSaved).toBe(0);
+    expect(r.messages).toEqual(msgs);
+  });
+
+  it("shrinks tool messages that exceed the token budget", () => {
+    const huge = "some event detail line with words\n".repeat(1000);
+    const msgs: ChatMessage[] = [
+      { role: "user", content: "do stuff" },
+      { role: "tool", tool_call_id: "t1", content: huge },
+    ];
+    const r = shrinkOversizedToolResultsByTokens(msgs, 500);
+    expect(r.healedCount).toBe(1);
+    expect(r.tokensSaved).toBeGreaterThan(0);
+    expect(r.charsSaved).toBeGreaterThan(0);
+    const toolMsg = r.messages.find((m) => m.role === "tool");
+    const shrunk = typeof toolMsg?.content === "string" ? toolMsg.content : "";
+    // Final token count stays reasonably near the cap (plus marker
+    // overhead from truncateForModelByTokens).
+    expect(countTokens(shrunk)).toBeLessThanOrEqual(600);
+  });
+
+  it("never mutates the input array", () => {
+    const big = "line of text with content\n".repeat(800);
+    const msgs: ChatMessage[] = [{ role: "tool", tool_call_id: "t1", content: big }];
+    const original = msgs[0]!.content;
+    shrinkOversizedToolResultsByTokens(msgs, 200);
+    expect(msgs[0]!.content).toBe(original);
+  });
+
+  it("does not touch user or assistant messages even when long", () => {
+    const bigUser = "user-intent prose ".repeat(2000);
+    const msgs: ChatMessage[] = [
+      { role: "user", content: bigUser },
+      { role: "assistant", content: "ok" },
+    ];
+    const r = shrinkOversizedToolResultsByTokens(msgs, 100);
+    expect(r.healedCount).toBe(0);
+    expect(r.messages[0]!.content).toBe(bigUser);
+  });
+
+  it("caps CJK tool results at the same token budget as English", () => {
+    // Under the old char cap, CJK text slipped through at ~2× the
+    // intended token cost. With a token cap, both must converge.
+    const cjk = "错误：步骤执行失败需要复查\n".repeat(1000);
+    const msgs: ChatMessage[] = [{ role: "tool", tool_call_id: "t1", content: cjk }];
+    const r = shrinkOversizedToolResultsByTokens(msgs, 500);
+    expect(r.healedCount).toBe(1);
+    const shrunk = typeof r.messages[0]!.content === "string" ? r.messages[0]!.content : "";
+    expect(countTokens(shrunk)).toBeLessThanOrEqual(600);
+  });
+
+  it("fast-pathes tool messages whose content length is already below the budget", () => {
+    // Every token is ≥1 char, so length <= maxTokens implies tokens
+    // <= maxTokens — no tokenize call needed, message untouched.
+    const content = "x".repeat(50);
+    const msgs: ChatMessage[] = [{ role: "tool", tool_call_id: "t1", content }];
+    const r = shrinkOversizedToolResultsByTokens(msgs, 100);
+    expect(r.healedCount).toBe(0);
+    expect(r.messages[0]!.content).toBe(content);
+  });
+});

tests/config.test.ts

@@ -3,11 +3,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
+  addProjectShellAllowed,
   isPlausibleKey,
   loadApiKey,
+  loadProjectShellAllowed,
   readConfig,
   redactKey,
   saveApiKey,
+  searchEnabled,
   writeConfig,
 } from "../src/config.js";
 
@@ -15,12 +18,15 @@ describe("config", () => {
   let dir: string;
   let path: string;
   const originalEnv = process.env.DEEPSEEK_API_KEY;
+  const originalSearch = process.env.REASONIX_SEARCH;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), "reasonix-test-"));
     path = join(dir, "config.json");
     // biome-ignore lint/performance/noDelete: the string "undefined" leaks into process.env otherwise
     delete process.env.DEEPSEEK_API_KEY;
+    // biome-ignore lint/performance/noDelete: same reason
+    delete process.env.REASONIX_SEARCH;
   });
 
   afterEach(() => {
@@ -31,6 +37,12 @@ describe("config", () => {
     } else {
       process.env.DEEPSEEK_API_KEY = originalEnv;
     }
+    if (originalSearch === undefined) {
+      // biome-ignore lint/performance/noDelete: same reason
+      delete process.env.REASONIX_SEARCH;
+    } else {
+      process.env.REASONIX_SEARCH = originalSearch;
+    }
   });
 
   it("readConfig returns {} when file is missing", () => {
@@ -106,4 +118,52 @@ describe("config", () => {
     const loaded = readConfig(path);
     expect(loaded.session).toBeNull();
   });
+
+  it("searchEnabled defaults to true with no config and no env", () => {
+    expect(searchEnabled(path)).toBe(true);
+  });
+
+  it("searchEnabled honours `search: false` in the config file", () => {
+    writeConfig({ apiKey: "sk-test123abcdefghijkl", search: false }, path);
+    expect(searchEnabled(path)).toBe(false);
+  });
+
+  it("searchEnabled honours REASONIX_SEARCH=off/false/0", () => {
+    process.env.REASONIX_SEARCH = "off";
+    expect(searchEnabled(path)).toBe(false);
+    process.env.REASONIX_SEARCH = "false";
+    expect(searchEnabled(path)).toBe(false);
+    process.env.REASONIX_SEARCH = "0";
+    expect(searchEnabled(path)).toBe(false);
+  });
+
+  it("searchEnabled stays true for unrelated env values", () => {
+    process.env.REASONIX_SEARCH = "on";
+    expect(searchEnabled(path)).toBe(true);
+  });
+
+  it("env off beats config true", () => {
+    writeConfig({ apiKey: "sk-test123abcdefghijkl", search: true }, path);
+    process.env.REASONIX_SEARCH = "off";
+    expect(searchEnabled(path)).toBe(false);
+  });
+
+  it("loadProjectShellAllowed returns [] when nothing stored", () => {
+    expect(loadProjectShellAllowed("/some/project", path)).toEqual([]);
+  });
+
+  it("addProjectShellAllowed persists and dedups per project", () => {
+    addProjectShellAllowed("/a", "npm install", path);
+    addProjectShellAllowed("/a", "git commit", path);
+    addProjectShellAllowed("/a", "npm install", path); // dedup
+    addProjectShellAllowed("/b", "cargo add", path);
+    expect(loadProjectShellAllowed("/a", path)).toEqual(["npm install", "git commit"]);
+    expect(loadProjectShellAllowed("/b", path)).toEqual(["cargo add"]);
+  });
+
+  it("addProjectShellAllowed ignores empty / whitespace prefixes", () => {
+    addProjectShellAllowed("/a", "", path);
+    addProjectShellAllowed("/a", "   ", path);
+    expect(loadProjectShellAllowed("/a", path)).toEqual([]);
+  });
 });

tests/diff-preview.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { formatAllBlockDiffs, formatEditBlockDiff } from "../src/code/diff-preview.js";
+import type { EditBlock } from "../src/code/edit-blocks.js";
+
+function block(path: string, search: string, replace: string): EditBlock {
+  return { path, search, replace, offset: 0 };
+}
+
+describe("formatEditBlockDiff", () => {
+  it("shows `+` lines only for a new-file edit (empty search)", () => {
+    const b = block("src/new.ts", "", "export const x = 1;\nexport const y = 2;");
+    const out = formatEditBlockDiff(b);
+    expect(out.every((l) => /^\s+\+/.test(l))).toBe(true);
+    expect(out.join("\n")).toContain("+ export const x = 1;");
+    expect(out.join("\n")).toContain("+ export const y = 2;");
+  });
+
+  it("collapses shared leading + trailing lines into context", () => {
+    const b = block(
+      "src/foo.ts",
+      "function foo() {\n  const x = 1;\n  return x;\n}",
+      "function foo() {\n  const x = 2;\n  return x;\n}",
+    );
+    const out = formatEditBlockDiff(b);
+    const joined = out.join("\n");
+    // Context lines (prefixed with two spaces) for unchanged parts.
+    expect(joined).toContain("  function foo() {");
+    expect(joined).toContain("  return x;");
+    expect(joined).toContain("  }");
+    // The diverging middle shows as `-`/`+`.
+    expect(joined).toContain("-   const x = 1;");
+    expect(joined).toContain("+   const x = 2;");
+  });
+
+  it("truncates diff to maxLines with a footer note", () => {
+    // 30 different lines — no shared prefix/suffix so they all show.
+    const search = Array.from({ length: 30 }, (_, i) => `old ${i}`).join("\n");
+    const replace = Array.from({ length: 30 }, (_, i) => `new ${i}`).join("\n");
+    const b = block("src/big.ts", search, replace);
+    const out = formatEditBlockDiff(b, { maxLines: 10 });
+    expect(out.length).toBeLessThanOrEqual(10);
+    expect(out[out.length - 1]).toMatch(/more diff lines/);
+  });
+
+  it("notes hidden leading context lines when prefix > contextLines", () => {
+    const pre = Array.from({ length: 10 }, (_, i) => `pre ${i}`).join("\n");
+    const b = block("src/a.ts", `${pre}\nOLD`, `${pre}\nNEW`);
+    const out = formatEditBlockDiff(b, { contextLines: 2 });
+    const joined = out.join("\n");
+    // Leading context should be collapsed — we keep 2 visible and
+    // note the rest as hidden.
+    expect(joined).toMatch(/8 unchanged lines? above/);
+  });
+
+  it("notes hidden trailing context lines when suffix > contextLines", () => {
+    const post = Array.from({ length: 10 }, (_, i) => `post ${i}`).join("\n");
+    const b = block("src/a.ts", `OLD\n${post}`, `NEW\n${post}`);
+    const out = formatEditBlockDiff(b, { contextLines: 2 });
+    const joined = out.join("\n");
+    expect(joined).toMatch(/8 unchanged lines? below/);
+  });
+
+  it("handles single-line edits cleanly", () => {
+    const b = block("one.ts", "old", "new");
+    const out = formatEditBlockDiff(b);
+    expect(out).toContain("        - old");
+    expect(out).toContain("        + new");
+  });
+
+  it("respects custom indent", () => {
+    const b = block("x.ts", "a", "b");
+    const out = formatEditBlockDiff(b, { indent: ">> " });
+    expect(out.some((l) => l.startsWith(">> - a"))).toBe(true);
+    expect(out.some((l) => l.startsWith(">> + b"))).toBe(true);
+  });
+});
+
+describe("formatAllBlockDiffs", () => {
+  it("emits a path+count header before each block's diff", () => {
+    const blocks = [block("a.ts", "x", "y"), block("b.ts", "", "new content")];
+    const out = formatAllBlockDiffs(blocks);
+    const joined = out.join("\n");
+    expect(joined).toMatch(/ {4}a\.ts {2}\(-1 \+1 lines\)/);
+    expect(joined).toMatch(/NEW b\.ts {2}\(-0 \+1 lines\)/);
+  });
+
+  it("separates blocks with a blank line", () => {
+    const blocks = [block("a.ts", "x", "y"), block("b.ts", "p", "q")];
+    const out = formatAllBlockDiffs(blocks);
+    // Blank line between first block's diff and second block's header.
+    const blankIdx = out.indexOf("");
+    expect(blankIdx).toBeGreaterThan(0);
+  });
+
+  it("returns an empty array for zero blocks", () => {
+    expect(formatAllBlockDiffs([])).toEqual([]);
+  });
+});

tests/filesystem-tools.test.ts

@@ -51,9 +51,13 @@ describe("filesystem tools (built-in, sandbox-enforced)", () => {
       expect(out).toMatch(/escapes sandbox/);
     });
 
-    it("rejects absolute paths outside root", async () => {
+    it("reinterprets POSIX-absolute paths as sandbox-relative (model can't escape via /)", async () => {
+      // Sandbox-root semantics: `/etc/passwd` becomes `etc/passwd`
+      // under rootDir. Real /etc/passwd stays unreachable; the lookup
+      // just fails because <root>/etc/passwd doesn't exist.
       const out = await tools.dispatch("read_file", JSON.stringify({ path: "/etc/passwd" }));
-      expect(out).toMatch(/escapes sandbox/);
+      expect(out).not.toMatch(/escapes sandbox/);
+      expect(out).toMatch(/ENOENT|no such file/i);
     });
 
     it("returns a truncation notice when file exceeds maxReadBytes", async () => {
@@ -110,6 +114,128 @@ describe("filesystem tools (built-in, sandbox-enforced)", () => {
       const out = await tools.dispatch("search_files", JSON.stringify({ pattern: "nothing123" }));
       expect(out).toBe("(no matches)");
     });
+
+    it("treats path: '/' as the sandbox root (model's POSIX intuition)", async () => {
+      // Common model failure mode: the LLM passes path: "/" intending
+      // "search the whole project". Without sandbox-root semantics
+      // path.resolve treats "/" as the actual filesystem root, the
+      // escape check rejects it, and the model sees a confusing error.
+      const out = await tools.dispatch(
+        "search_files",
+        JSON.stringify({ path: "/", pattern: "index" }),
+      );
+      expect(out).not.toMatch(/escapes sandbox/);
+      expect(out).toContain("index.ts");
+    });
+
+    it("treats path: '/src' as <root>/src", async () => {
+      const out = await tools.dispatch(
+        "search_files",
+        JSON.stringify({ path: "/src", pattern: "util" }),
+      );
+      expect(out).not.toMatch(/escapes sandbox/);
+      expect(out).toContain("util.ts");
+    });
+  });
+
+  describe("search_content", () => {
+    it("finds a literal substring inside a file's content", async () => {
+      // src/index.ts has `export const x = 1;`
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "export const x" }),
+      );
+      // Format: path:line: text
+      expect(out).toMatch(/src[\\/]index\.ts:1: export const x = 1;/);
+    });
+
+    it("matches across multiple files and reports each line", async () => {
+      // Both src/index.ts and src/util.ts have `export const`.
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "export const" }),
+      );
+      expect(out).toContain("index.ts");
+      expect(out).toContain("util.ts");
+    });
+
+    it("supports regex patterns (word-bounded match)", async () => {
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "\\bexport\\s+const\\s+y\\b" }),
+      );
+      expect(out).toContain("util.ts");
+      expect(out).not.toContain("index.ts");
+    });
+
+    it("is case-insensitive by default", async () => {
+      const out = await tools.dispatch("search_content", JSON.stringify({ pattern: "EXPORT" }));
+      expect(out).toContain("export");
+    });
+
+    it("respects case_sensitive when set", async () => {
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "EXPORT", case_sensitive: true }),
+      );
+      expect(out).toMatch(/no matches/);
+    });
+
+    it("filters by glob substring on the file name", async () => {
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "export const", glob: "util" }),
+      );
+      expect(out).toContain("util.ts");
+      expect(out).not.toContain("index.ts");
+    });
+
+    it("skips dependency dirs by default", async () => {
+      // Drop a node_modules-style file matching the pattern.
+      await fs.mkdir(join(root, "node_modules", "junk"), { recursive: true });
+      await fs.writeFile(
+        join(root, "node_modules", "junk", "vendor.ts"),
+        "export const NEEDLE = 1;\n",
+      );
+      const out = await tools.dispatch("search_content", JSON.stringify({ pattern: "NEEDLE" }));
+      expect(out).toMatch(/no matches/);
+    });
+
+    it("includes dependency dirs when include_deps:true", async () => {
+      await fs.mkdir(join(root, "node_modules", "junk"), { recursive: true });
+      await fs.writeFile(
+        join(root, "node_modules", "junk", "vendor.ts"),
+        "export const NEEDLE = 1;\n",
+      );
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "NEEDLE", include_deps: true }),
+      );
+      expect(out).toContain("vendor.ts");
+    });
+
+    it("skips binary files by extension", async () => {
+      // A .png with searchable text inside — extension wins.
+      await fs.writeFile(join(root, "logo.png"), "this is a PNG with NEEDLE inside\n");
+      const out = await tools.dispatch("search_content", JSON.stringify({ pattern: "NEEDLE" }));
+      expect(out).not.toContain("logo.png");
+    });
+
+    it("skips binary files by content (NUL byte sniff)", async () => {
+      // A .txt that's actually binary — content sniff catches it.
+      const buf = Buffer.concat([Buffer.from("NEEDLE\0"), Buffer.from([0, 1, 2, 3])]);
+      await fs.writeFile(join(root, "data.txt"), buf);
+      const out = await tools.dispatch("search_content", JSON.stringify({ pattern: "NEEDLE" }));
+      expect(out).not.toContain("data.txt");
+    });
+
+    it("returns a clean (no matches) message when nothing matches", async () => {
+      const out = await tools.dispatch(
+        "search_content",
+        JSON.stringify({ pattern: "definitely_not_present_anywhere_zxq" }),
+      );
+      expect(out).toMatch(/no matches/);
+    });
   });
 
   describe("get_file_info", () => {

tests/hooks.test.ts

@@ -0,0 +1,354 @@
+/**
+ * Tests for the hooks module — settings loading, match patterns,
+ * outcome decisions, and the runHooks dispatcher with a stubbed
+ * spawner. No real subprocesses, no real filesystem outside tmp dirs.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  type HookSpawnInput,
+  type HookSpawnResult,
+  type ResolvedHook,
+  decideOutcome,
+  formatHookOutcomeMessage,
+  globalSettingsPath,
+  loadHooks,
+  matchesTool,
+  projectSettingsPath,
+  runHooks,
+} from "../src/hooks.js";
+
+function writeSettings(dir: string, json: unknown): string {
+  const path = join(dir, ".reasonix", "settings.json");
+  mkdirSync(join(dir, ".reasonix"), { recursive: true });
+  writeFileSync(path, JSON.stringify(json), "utf8");
+  return path;
+}
+
+function makeSpawner(
+  responses: HookSpawnResult[],
+  log?: HookSpawnInput[],
+): (input: HookSpawnInput) => Promise<HookSpawnResult> {
+  let i = 0;
+  return async (input) => {
+    log?.push(input);
+    const r = responses[i++];
+    if (!r) throw new Error("spawner exhausted — test set up too few responses");
+    return r;
+  };
+}
+
+const ok = (overrides: Partial<HookSpawnResult> = {}): HookSpawnResult => ({
+  exitCode: 0,
+  stdout: "",
+  stderr: "",
+  timedOut: false,
+  ...overrides,
+});
+
+describe("loadHooks", () => {
+  let home: string;
+  let project: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-hooks-home-"));
+    project = mkdtempSync(join(tmpdir(), "reasonix-hooks-proj-"));
+  });
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  });
+
+  it("returns [] when no settings file exists in either scope", () => {
+    expect(loadHooks({ homeDir: home, projectRoot: project })).toEqual([]);
+  });
+
+  it("loads project then global, in array order, with scope tags", () => {
+    writeSettings(home, {
+      hooks: { Stop: [{ command: "echo global1" }, { command: "echo global2" }] },
+    });
+    writeSettings(project, {
+      hooks: { Stop: [{ command: "echo proj" }] },
+    });
+    const hooks = loadHooks({ homeDir: home, projectRoot: project });
+    expect(hooks.map((h) => `${h.scope}:${h.command}`)).toEqual([
+      "project:echo proj",
+      "global:echo global1",
+      "global:echo global2",
+    ]);
+  });
+
+  it("ignores entries without a string command", () => {
+    writeSettings(home, {
+      hooks: {
+        Stop: [
+          { command: "echo good" },
+          { command: "" },
+          { description: "no command" },
+          { command: 42 } as unknown as { command: string },
+        ],
+      },
+    });
+    const hooks = loadHooks({ homeDir: home });
+    expect(hooks).toHaveLength(1);
+    expect(hooks[0]?.command).toBe("echo good");
+  });
+
+  it("tolerates malformed JSON without throwing", () => {
+    mkdirSync(join(home, ".reasonix"), { recursive: true });
+    writeFileSync(join(home, ".reasonix", "settings.json"), "{ not valid json", "utf8");
+    expect(() => loadHooks({ homeDir: home })).not.toThrow();
+    expect(loadHooks({ homeDir: home })).toEqual([]);
+  });
+
+  it("project scope is skipped when projectRoot omitted", () => {
+    writeSettings(project, { hooks: { Stop: [{ command: "echo proj" }] } });
+    const hooks = loadHooks({ homeDir: home }); // no projectRoot
+    expect(hooks).toEqual([]);
+  });
+
+  it("paths reported by *SettingsPath helpers are absolute", () => {
+    expect(globalSettingsPath(home)).toBe(join(home, ".reasonix", "settings.json"));
+    expect(projectSettingsPath(project)).toBe(join(project, ".reasonix", "settings.json"));
+  });
+});
+
+describe("matchesTool", () => {
+  const baseHook: ResolvedHook = {
+    event: "PreToolUse",
+    scope: "global",
+    source: "/tmp/x",
+    command: "true",
+  };
+
+  it("returns true when match is undefined or '*'", () => {
+    expect(matchesTool(baseHook, "edit_file")).toBe(true);
+    expect(matchesTool({ ...baseHook, match: "*" }, "edit_file")).toBe(true);
+  });
+
+  it("anchored regex matches only the full tool name", () => {
+    const hook: ResolvedHook = { ...baseHook, match: "edit_file|write_file" };
+    expect(matchesTool(hook, "edit_file")).toBe(true);
+    expect(matchesTool(hook, "write_file")).toBe(true);
+    expect(matchesTool(hook, "read_file")).toBe(false);
+    // Substring should NOT match (anchored)
+    expect(matchesTool({ ...baseHook, match: "file" }, "edit_file")).toBe(false);
+  });
+
+  it("malformed regex falls back to no-match (safer than fire-on-everything)", () => {
+    const hook: ResolvedHook = { ...baseHook, match: "[unclosed" };
+    expect(matchesTool(hook, "edit_file")).toBe(false);
+  });
+
+  it("non-tool events ignore the match field", () => {
+    const hook: ResolvedHook = {
+      ...baseHook,
+      event: "UserPromptSubmit",
+      match: "never",
+    };
+    expect(matchesTool(hook, "anything")).toBe(true);
+  });
+});
+
+describe("decideOutcome", () => {
+  it("exit 0 → pass", () => {
+    expect(decideOutcome("PreToolUse", ok())).toBe("pass");
+  });
+  it("exit 2 on PreToolUse → block", () => {
+    expect(decideOutcome("PreToolUse", ok({ exitCode: 2 }))).toBe("block");
+  });
+  it("exit 2 on PostToolUse → warn (block is meaningless after the fact)", () => {
+    expect(decideOutcome("PostToolUse", ok({ exitCode: 2 }))).toBe("warn");
+  });
+  it("any other non-zero → warn", () => {
+    expect(decideOutcome("PreToolUse", ok({ exitCode: 1 }))).toBe("warn");
+    expect(decideOutcome("Stop", ok({ exitCode: 127 }))).toBe("warn");
+  });
+  it("timeout on a blocking event → block, on a logging event → warn", () => {
+    expect(decideOutcome("PreToolUse", ok({ timedOut: true, exitCode: null }))).toBe("block");
+    expect(decideOutcome("Stop", ok({ timedOut: true, exitCode: null }))).toBe("warn");
+  });
+  it("spawn error → error, regardless of event", () => {
+    const err = ok({ exitCode: null, spawnError: new Error("ENOENT") });
+    expect(decideOutcome("PreToolUse", err)).toBe("error");
+    expect(decideOutcome("Stop", err)).toBe("error");
+  });
+});
+
+describe("runHooks", () => {
+  const hook = (overrides: Partial<ResolvedHook> = {}): ResolvedHook => ({
+    event: "PreToolUse",
+    scope: "project",
+    source: "/tmp/x",
+    command: "true",
+    ...overrides,
+  });
+
+  it("filters by event AND tool match before running", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok()], log);
+    const hooks: ResolvedHook[] = [
+      hook({ event: "Stop", command: "wrong-event" }),
+      hook({ event: "PreToolUse", match: "write_file", command: "wrong-tool" }),
+      hook({ event: "PreToolUse", match: "edit_file", command: "right" }),
+    ];
+    const report = await runHooks({
+      hooks,
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/tmp", toolName: "edit_file" },
+    });
+    expect(log).toHaveLength(1);
+    expect(log[0]?.command).toBe("right");
+    expect(report.outcomes[0]?.decision).toBe("pass");
+    expect(report.blocked).toBe(false);
+  });
+
+  it("stops at the first block on a blocking event", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok(), ok({ exitCode: 2, stderr: "denied" }), ok()], log);
+    const hooks: ResolvedHook[] = [
+      hook({ command: "first" }),
+      hook({ command: "blocker" }),
+      hook({ command: "third — should not run" }),
+    ];
+    const report = await runHooks({
+      hooks,
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/tmp", toolName: "x" },
+    });
+    expect(log.map((l) => l.command)).toEqual(["first", "blocker"]);
+    expect(report.blocked).toBe(true);
+    expect(report.outcomes[1]?.decision).toBe("block");
+  });
+
+  it("does not stop on warn — collects every outcome", async () => {
+    const spawner = makeSpawner([ok({ exitCode: 1, stderr: "noisy" }), ok()]);
+    const hooks: ResolvedHook[] = [hook({ command: "warner" }), hook({ command: "ok" })];
+    const report = await runHooks({
+      hooks,
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/tmp", toolName: "x" },
+    });
+    expect(report.outcomes.map((o) => o.decision)).toEqual(["warn", "pass"]);
+    expect(report.blocked).toBe(false);
+  });
+
+  it("stdin contains a single-line JSON envelope of the payload", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok()], log);
+    await runHooks({
+      hooks: [hook({ command: "echo" })],
+      spawner,
+      payload: {
+        event: "PreToolUse",
+        cwd: "/tmp",
+        toolName: "edit_file",
+        toolArgs: { path: "a.ts" },
+      },
+    });
+    const stdin = log[0]?.stdin ?? "";
+    const decoded = JSON.parse(stdin);
+    expect(decoded.event).toBe("PreToolUse");
+    expect(decoded.toolName).toBe("edit_file");
+    expect(decoded.toolArgs).toEqual({ path: "a.ts" });
+    expect(stdin.endsWith("\n")).toBe(true);
+  });
+
+  it("uses payload.cwd by default and per-hook cwd override when set", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok(), ok()], log);
+    await runHooks({
+      hooks: [hook({ command: "a" }), hook({ command: "b", cwd: "/special" })],
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/payload-cwd", toolName: "x" },
+    });
+    expect(log[0]?.cwd).toBe("/payload-cwd");
+    expect(log[1]?.cwd).toBe("/special");
+  });
+
+  it("default timeout is 5s for blocking events and 30s for logging events", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok(), ok()], log);
+    const h: ResolvedHook[] = [
+      hook({ event: "PreToolUse", command: "pre" }),
+      hook({ event: "Stop", command: "stop" }),
+    ];
+    await runHooks({
+      hooks: h,
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/tmp", toolName: "x" },
+    });
+    await runHooks({
+      hooks: h,
+      spawner,
+      payload: { event: "Stop", cwd: "/tmp" },
+    });
+    expect(log[0]?.timeoutMs).toBe(5_000);
+    expect(log[1]?.timeoutMs).toBe(30_000);
+  });
+
+  it("per-hook timeout overrides the default", async () => {
+    const log: HookSpawnInput[] = [];
+    const spawner = makeSpawner([ok()], log);
+    await runHooks({
+      hooks: [hook({ command: "x", timeout: 999 })],
+      spawner,
+      payload: { event: "PreToolUse", cwd: "/tmp", toolName: "x" },
+    });
+    expect(log[0]?.timeoutMs).toBe(999);
+  });
+});
+
+describe("formatHookOutcomeMessage", () => {
+  const baseHook: ResolvedHook = {
+    event: "PostToolUse",
+    scope: "global",
+    source: "/tmp/x",
+    command: "echo hi",
+  };
+
+  it("returns empty string for pass", () => {
+    expect(
+      formatHookOutcomeMessage({
+        hook: baseHook,
+        decision: "pass",
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        durationMs: 1,
+      }),
+    ).toBe("");
+  });
+
+  it("includes scope/event tag, command, decision, and stderr detail", () => {
+    const msg = formatHookOutcomeMessage({
+      hook: baseHook,
+      decision: "warn",
+      exitCode: 1,
+      stdout: "",
+      stderr: "something went sideways",
+      durationMs: 5,
+    });
+    expect(msg).toContain("global/PostToolUse");
+    expect(msg).toContain("echo hi");
+    expect(msg).toContain("warn");
+    expect(msg).toContain("something went sideways");
+  });
+
+  it("truncates very long commands at 60 chars + ellipsis", () => {
+    const long = "x".repeat(200);
+    const msg = formatHookOutcomeMessage({
+      hook: { ...baseHook, command: long },
+      decision: "warn",
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+      durationMs: 5,
+    });
+    expect(msg).toContain(`${"x".repeat(60)}…`);
+    expect(msg).not.toContain("x".repeat(61));
+  });
+});

tests/loop-hooks.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Smoke tests for hook wiring inside CacheFirstLoop. The full
+ * pass / block / warn matrix is covered in tests/hooks.test.ts with
+ * a stubbed spawner — here we just confirm the loop honors the
+ * `hooks` option and exposes a mutable list that `/hooks reload`
+ * can swap into without reconstructing the loop.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+import type { ResolvedHook } from "../src/hooks.js";
+import { CacheFirstLoop, type LoopEvent } from "../src/loop.js";
+import { ImmutablePrefix } from "../src/memory.js";
+import { ToolRegistry } from "../src/tools.js";
+import type { ChatMessage } from "../src/types.js";
+
+interface FakeResponseShape {
+  content?: string;
+  tool_calls?: unknown[];
+}
+
+function fakeFetch(responses: FakeResponseShape[]): typeof fetch {
+  let i = 0;
+  return vi.fn(async (_url: unknown, init: { body?: string } | undefined) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    const resp = responses[i++] ?? responses[responses.length - 1]!;
+    return new Response(
+      JSON.stringify({
+        _echo_messages: body.messages as ChatMessage[],
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: "assistant",
+              content: resp.content ?? "",
+              tool_calls: resp.tool_calls ?? undefined,
+            },
+            finish_reason: resp.tool_calls ? "tool_calls" : "stop",
+          },
+        ],
+        usage: {
+          prompt_tokens: 100,
+          completion_tokens: 20,
+          total_tokens: 120,
+          prompt_cache_hit_tokens: 0,
+          prompt_cache_miss_tokens: 100,
+        },
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  }) as unknown as typeof fetch;
+}
+
+function makeClient(responses: FakeResponseShape[]) {
+  return new DeepSeekClient({ apiKey: "sk-test", fetch: fakeFetch(responses) });
+}
+
+describe("CacheFirstLoop hook wiring", () => {
+  it("default hooks list is empty (zero overhead when no settings.json)", () => {
+    const loop = new CacheFirstLoop({
+      client: makeClient([{ content: "x" }]),
+      prefix: new ImmutablePrefix({ system: "s" }),
+    });
+    expect(loop.hooks).toEqual([]);
+  });
+
+  it("accepts a hooks list via options", () => {
+    const hooks: ResolvedHook[] = [
+      { event: "Stop", scope: "global", source: "/x", command: "echo done" },
+    ];
+    const loop = new CacheFirstLoop({
+      client: makeClient([{ content: "x" }]),
+      prefix: new ImmutablePrefix({ system: "s" }),
+      hooks,
+    });
+    expect(loop.hooks).toEqual(hooks);
+  });
+
+  it("hooks field is mutable so /hooks reload can swap without rebuild", () => {
+    const loop = new CacheFirstLoop({
+      client: makeClient([{ content: "x" }]),
+      prefix: new ImmutablePrefix({ system: "s" }),
+    });
+    const fresh: ResolvedHook[] = [
+      { event: "PreToolUse", scope: "project", source: "/x", command: "true" },
+    ];
+    loop.hooks = fresh;
+    expect(loop.hooks).toEqual(fresh);
+  });
+
+  it("hookCwd defaults to process.cwd() when not provided", () => {
+    const loop = new CacheFirstLoop({
+      client: makeClient([{ content: "x" }]),
+      prefix: new ImmutablePrefix({ system: "s" }),
+    });
+    expect(loop.hookCwd).toBe(process.cwd());
+  });
+
+  it("hookCwd takes the explicit override when set", () => {
+    const loop = new CacheFirstLoop({
+      client: makeClient([{ content: "x" }]),
+      prefix: new ImmutablePrefix({ system: "s" }),
+      hookCwd: "/some/sandbox/root",
+    });
+    expect(loop.hookCwd).toBe("/some/sandbox/root");
+  });
+
+  it("a no-tool-call turn never dispatches hooks (PreToolUse only fires around tools)", async () => {
+    // Sanity check: a plain text response means no PreToolUse hook
+    // would be invoked even if one were configured. We assert only
+    // through observable events here — no hook = no warning rows.
+    const client = makeClient([{ content: "just chatting" }]);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s" }),
+      stream: false,
+      hooks: [{ event: "PreToolUse", scope: "global", source: "/x", command: "noop" }],
+    });
+    const events: LoopEvent[] = [];
+    for await (const ev of loop.step("hi")) events.push(ev);
+    expect(events.find((e) => e.role === "warning")).toBeUndefined();
+    expect(events.find((e) => e.role === "assistant_final")?.content).toBe("just chatting");
+  });
+});

tests/loop-r1-reasoning.test.ts

@@ -0,0 +1,146 @@
+/**
+ * R1 thinking-mode contract: when a reasoner turn returns both
+ * `reasoning_content` and `tool_calls`, the assistant message we
+ * persist + send on the NEXT request (the tool-loop continuation)
+ * must carry `reasoning_content` back. Otherwise DeepSeek 400s with
+ * "The reasoning_content in the thinking mode must be passed back to
+ * the API." Reproduces the bug that surfaced in 0.5.14 live usage.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+import { CacheFirstLoop } from "../src/loop.js";
+import { ImmutablePrefix } from "../src/memory.js";
+import { ToolRegistry } from "../src/tools.js";
+import type { ChatMessage } from "../src/types.js";
+
+interface FakeResponseShape {
+  content?: string;
+  reasoning_content?: string;
+  tool_calls?: any[];
+  usage?: Record<string, number>;
+}
+
+function capturingFetch(responses: FakeResponseShape[]): {
+  fetch: typeof fetch;
+  bodies: Array<{ messages: ChatMessage[] }>;
+} {
+  const bodies: Array<{ messages: ChatMessage[] }> = [];
+  let i = 0;
+  const fn = vi.fn(async (_url: any, init: any) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    bodies.push({ messages: body.messages });
+    const resp = responses[i++] ?? responses[responses.length - 1]!;
+    return new Response(
+      JSON.stringify({
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: "assistant",
+              content: resp.content ?? "",
+              reasoning_content: resp.reasoning_content ?? null,
+              tool_calls: resp.tool_calls ?? undefined,
+            },
+            finish_reason: resp.tool_calls ? "tool_calls" : "stop",
+          },
+        ],
+        usage: resp.usage ?? {
+          prompt_tokens: 100,
+          completion_tokens: 20,
+          total_tokens: 120,
+          prompt_cache_hit_tokens: 0,
+          prompt_cache_miss_tokens: 100,
+        },
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  }) as unknown as typeof fetch;
+  return { fetch: fn, bodies };
+}
+
+describe("R1 reasoning_content round-trip", () => {
+  it("preserves reasoning_content on the assistant message when the turn has tool_calls", async () => {
+    const tools = new ToolRegistry();
+    tools.register({
+      name: "noop",
+      readOnly: true,
+      fn: () => "ok",
+    });
+
+    const { fetch: fakeFetch, bodies } = capturingFetch([
+      {
+        // Turn 1: model emits reasoning + tool call.
+        content: "",
+        reasoning_content: "I should call noop to check something.",
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "noop", arguments: "{}" },
+          },
+        ],
+      },
+      {
+        // Turn 2: plain text wrap-up after the tool result comes back.
+        content: "done",
+      },
+    ]);
+    const client = new DeepSeekClient({ apiKey: "sk-test", fetch: fakeFetch });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: tools.specs() }),
+      tools,
+      model: "deepseek-reasoner",
+      stream: false,
+    });
+
+    for await (const _ev of loop.step("please noop")) {
+      /* drain */
+    }
+
+    expect(bodies.length).toBe(2);
+    // Turn 2's request messages include the turn-1 assistant message;
+    // find it and verify reasoning_content landed.
+    const turn2Messages = bodies[1]!.messages;
+    const assistantWithCalls = turn2Messages.find(
+      (m) => m.role === "assistant" && (m.tool_calls?.length ?? 0) > 0,
+    );
+    expect(assistantWithCalls).toBeDefined();
+    expect(assistantWithCalls?.reasoning_content).toBe("I should call noop to check something.");
+  });
+
+  it("also preserves reasoning_content on plain-text reasoner turns", async () => {
+    // 0.5.18 regression: R1 requires reasoning_content on ANY
+    // assistant message the model produced in thinking mode, not just
+    // ones with tool_calls. 0.5.15 scoped the fix too narrowly and a
+    // plan-approval flow (submit_plan → "plan submitted" plain-text
+    // turn → approval) kept 400ing on the follow-up request.
+    const { fetch: fakeFetch, bodies } = capturingFetch([
+      {
+        content: "a plain answer",
+        reasoning_content: "reasoning attached to a plain-text turn",
+      },
+      { content: "follow-up" },
+    ]);
+    const client = new DeepSeekClient({ apiKey: "sk-test", fetch: fakeFetch });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s" }),
+      model: "deepseek-reasoner",
+      stream: false,
+    });
+
+    for await (const _ev of loop.step("hello")) {
+      /* drain */
+    }
+    for await (const _ev of loop.step("next")) {
+      /* drain */
+    }
+
+    const turn2Messages = bodies[1]!.messages;
+    const assistant = turn2Messages.find((m) => m.role === "assistant");
+    expect(assistant).toBeDefined();
+    expect(assistant?.reasoning_content).toBe("reasoning attached to a plain-text turn");
+  });
+});

tests/loop.test.ts

@@ -255,11 +255,13 @@ describe("CacheFirstLoop (non-streaming)", () => {
     for await (const ev of loop.step("go")) {
       if (ev.role === "warning") warnings.push(ev.content);
     }
-    // Exactly one warning should fire (guard against the once-per-turn flag
-    // regressing). Content must mention the X/N count and "Esc".
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]).toMatch(/\d+\/4 tool calls used/);
-    expect(warnings[0]).toMatch(/Esc/);
+    // Identical fixture calls also trip the storm breaker in 0.4.19+,
+    // which emits its own warning. Filter for the iter-budget warning
+    // specifically — that's what this test guards (once-per-turn flag).
+    const iterBudgetWarnings = warnings.filter((w) => /tool calls used/.test(w));
+    expect(iterBudgetWarnings).toHaveLength(1);
+    expect(iterBudgetWarnings[0]).toMatch(/\d+\/4 tool calls used/);
+    expect(iterBudgetWarnings[0]).toMatch(/Esc/);
   });
 
   it("abort() mid-step stops immediately without a follow-up API call", async () => {
@@ -468,11 +470,13 @@ describe("CacheFirstLoop (non-streaming)", () => {
       maxToolIters: 64,
     });
     // Put a big tool message into the log so compact has work to do.
+    // Realistic log-line content (not "Z".repeat(N)) to avoid the
+    // tokenizer's BPE O(n²) pathological path on pure-repeat inputs.
     loop.log.append({ role: "user", content: "do stuff" });
     loop.log.append({
       role: "tool",
       tool_call_id: "prior",
-      content: "Z".repeat(60_000),
+      content: "ERROR: something went wrong in module X at step Y\n".repeat(2000),
     });
 
     const events: { role: string; forcedSummary?: boolean; content?: string }[] = [];
@@ -492,6 +496,102 @@ describe("CacheFirstLoop (non-streaming)", () => {
     expect(last!.forcedSummary).toBeFalsy();
   });
 
+  it("proactively compacts oversized tool results between 60%-80% of the context window", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "probe",
+      description: "no-op",
+      parameters: { type: "object", properties: {} },
+      fn: async () => "ok",
+    });
+    const responses: FakeResponseShape[] = [
+      // 131k * 0.72 ≈ 94,320 tokens — squarely in the proactive band.
+      {
+        content: "",
+        tool_calls: [{ id: "c1", type: "function", function: { name: "probe", arguments: "{}" } }],
+        usage: {
+          prompt_tokens: 95_000,
+          completion_tokens: 10,
+          total_tokens: 95_010,
+          prompt_cache_hit_tokens: 70_000,
+          prompt_cache_miss_tokens: 25_000,
+        },
+      },
+      { content: "done." },
+    ];
+    const client = makeClient(responses);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: reg.specs() }),
+      tools: reg,
+      stream: false,
+      maxToolIters: 64,
+    });
+    // Seed an oversized tool result (>4k tokens, the proactive cap)
+    // so proactive compact has work to do. Using realistic log-line
+    // content to avoid the tokenizer's BPE O(n²) pathological path.
+    loop.log.append({ role: "user", content: "prior" });
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "prior",
+      content: "INFO: step completed with some trailing detail\n".repeat(1500),
+    });
+
+    const events: { role: string; content?: string; forcedSummary?: boolean }[] = [];
+    for await (const ev of loop.step("continue")) {
+      events.push({ role: ev.role, content: ev.content, forcedSummary: ev.forcedSummary });
+    }
+
+    const proactive = events.find(
+      (e) => e.role === "warning" && /proactively compacted/.test(e.content ?? ""),
+    );
+    expect(proactive).toBeDefined();
+    expect(proactive!.content).toMatch(/4k tokens/);
+    // 60%-80% band must NOT force a summary (that's the 80% reactive path).
+    const finals = events.filter((e) => e.role === "assistant_final");
+    expect(finals[finals.length - 1]!.forcedSummary).toBeFalsy();
+  });
+
+  it("pre-clips new tool results at dispatch so they never enter the log oversized", async () => {
+    const reg = new ToolRegistry();
+    // Tool returns ~50k chars of realistic-shape log text; the default
+    // token budget (8k) bounds the resulting log entry to a small
+    // fraction of the raw size. (Using "A".repeat(N) would hit the
+    // tokenizer's BPE O(n²) path for repeated single-char inputs —
+    // pathological enough to slow the suite by tens of seconds, and
+    // not representative of real tool output.)
+    const huge = "ERROR: repeated failure with some detail\n".repeat(1250);
+    reg.register({
+      name: "big",
+      description: "returns a lot",
+      parameters: { type: "object", properties: {} },
+      fn: async () => huge,
+    });
+    const responses: FakeResponseShape[] = [
+      {
+        content: "",
+        tool_calls: [{ id: "c1", type: "function", function: { name: "big", arguments: "{}" } }],
+      },
+      { content: "summarized." },
+    ];
+    const client = makeClient(responses);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: reg.specs() }),
+      tools: reg,
+      stream: false,
+    });
+    for await (const _ev of loop.step("go")) {
+      /* drain */
+    }
+    const toolEntry = loop.log.toMessages().find((m) => m.role === "tool");
+    expect(toolEntry).toBeDefined();
+    const content = typeof toolEntry!.content === "string" ? toolEntry!.content : "";
+    // Well under the raw 50k — pre-clip fired before append.
+    expect(content.length).toBeLessThan(40_000);
+    expect(content).toMatch(/truncated/);
+  });
+
   it("buildMessages strips a dangling assistant-with-tool_calls tail — defensive against 'insufficient tool messages' 400", async () => {
     // Craft a log where the last entry is an assistant message with
     // tool_calls but no matching tool responses. This is the shape
@@ -595,4 +695,46 @@ describe("CacheFirstLoop (streaming) — tool_call_delta emission", () => {
     expect(deltas[0]!.name).toBe("edit_file");
     expect(deltas[deltas.length - 1]!.chars).toBeGreaterThan(deltas[0]!.chars!);
   });
+
+  it("does not emit a red error event when the API call is aborted mid-flight", async () => {
+    // Reproduces the reported "error This operation was aborted" UX
+    // bug: when App.tsx calls loop.abort() to switch to a queued
+    // synthetic input (e.g. ShellConfirm "always allow"), the in-flight
+    // fetch throws AbortError. We treat that as a clean early-exit
+    // (yield `done`) instead of bubbling it up as a red error row.
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      // Slow fake fetch — never resolves on its own; only the abort
+      // signal terminates it.
+      fetch: vi.fn(async (_url: any, init: any) => {
+        const signal: AbortSignal | undefined = init?.signal;
+        return new Promise<Response>((_resolve, reject) => {
+          signal?.addEventListener("abort", () =>
+            reject(new DOMException("This operation was aborted", "AbortError")),
+          );
+        });
+      }) as any,
+      retry: { maxAttempts: 1 },
+    });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s" }),
+      stream: false,
+    });
+
+    const events: Array<{ role: string; error?: string }> = [];
+    const stepPromise = (async () => {
+      for await (const ev of loop.step("hi")) {
+        events.push({ role: ev.role, error: ev.error });
+      }
+    })();
+    // Race: fire abort before the fake fetch can resolve.
+    setTimeout(() => loop.abort(), 10);
+    await stepPromise;
+
+    // No "error" event leaked through.
+    expect(events.find((e) => e.role === "error")).toBeUndefined();
+    // Loop terminated cleanly so the TUI's busy state unsticks.
+    expect(events[events.length - 1]?.role).toBe("done");
+  });
 });

tests/markdown.test.ts

@@ -1,5 +1,17 @@
-import { describe, expect, it } from "vitest";
-import { parseBlocks, stripMath } from "../src/cli/ui/markdown.js";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  collectCitations,
+  isExternalUrl,
+  parseBlocks,
+  parseCitationUrl,
+  stripInlineMarkup,
+  stripMath,
+  validateCitation,
+  visibleWidth,
+} from "../src/cli/ui/markdown.js";
 
 describe("stripMath", () => {
   it("converts \\frac, \\dfrac, \\tfrac uniformly", () => {
@@ -222,4 +234,322 @@ describe("parseBlocks — GFM tables", () => {
       expect(t.rows[0]).toEqual(["x | y", "z"]);
     }
   });
+
+  it("recognizes Unicode box-drawing tables (│ ─ ┼) as tables too", () => {
+    // R1/V3 frequently emit this shape when asked for tabular data in
+    // Chinese — the GFM-only path treated them as plain paragraphs and
+    // Ink word-wrapped them into a tangle.
+    const md = [
+      "步骤             │ 说明",
+      "─────────────────┼─────────────────────────────────────────",
+      "**工具查找**     │ 按 `name` 查找已注册的工具",
+      "**参数解析**     │ 支持 string (JSON) 或 object 格式",
+      "",
+      "Trailing prose.",
+    ].join("\n");
+    const blocks = parseBlocks(md);
+    const table = blocks.find((b) => b.kind === "table");
+    expect(table).toBeDefined();
+    if (table && table.kind === "table") {
+      expect(table.header).toEqual(["步骤", "说明"]);
+      expect(table.rows).toHaveLength(2);
+      expect(table.rows[0]).toEqual(["**工具查找**", "按 `name` 查找已注册的工具"]);
+      expect(table.rows[1]).toEqual(["**参数解析**", "支持 string (JSON) 或 object 格式"]);
+    }
+    expect(
+      blocks.find((b) => b.kind === "paragraph" && b.text === "Trailing prose."),
+    ).toBeDefined();
+  });
+
+  it("does NOT trigger on a bare '│' in prose without a separator below", () => {
+    const md = ["The character │ is a vertical bar.", "Nothing tabular here."].join("\n");
+    expect(parseBlocks(md).find((b) => b.kind === "table")).toBeUndefined();
+  });
+
+  it("folds a continuation row (no column separator) into the last cell of the previous row", () => {
+    // Real-world LLM output: cell content too long, model wraps onto a
+    // second line without re-emitting the separator. Used to leak as
+    // a paragraph after the table; now stitched back into the cell so
+    // inline backticks / bold parse correctly.
+    const md = [
+      "文件         │ 角色",
+      "─────────────┼─────────────────────────────────────────",
+      "`src/tools.ts` │ `dispatch()` 方法定义（约第 106 行起）。签名：",
+      "                async dispatch(name: string, ...)。处理 plan-mode 拦截。",
+    ].join("\n");
+    const [t] = parseBlocks(md).filter((b) => b.kind === "table");
+    expect(t).toBeDefined();
+    if (t && t.kind === "table") {
+      expect(t.rows).toHaveLength(1);
+      expect(t.rows[0]?.[1]).toContain("dispatch()");
+      expect(t.rows[0]?.[1]).toContain("async dispatch(name");
+    }
+  });
+});
+
+describe("parseBlocks — box-drawing frames as code blocks", () => {
+  it("recognizes a single-line ┌─┐ │ └─┘ frame", () => {
+    // Models routinely wrap one line of code in a Unicode frame for
+    // emphasis. The renderer treats the frame as a code block so the
+    // inner content stays readable instead of being word-wrapped.
+    const md = [
+      "Here is the call site:",
+      "",
+      "┌──────────────────────────────────────────┐",
+      "│ result = await this.tools.dispatch(...); │",
+      "└──────────────────────────────────────────┘",
+      "",
+      "Trailing.",
+    ].join("\n");
+    const blocks = parseBlocks(md);
+    const code = blocks.find((b) => b.kind === "code");
+    expect(code).toBeDefined();
+    if (code && code.kind === "code") {
+      expect(code.text).toBe("result = await this.tools.dispatch(...);");
+    }
+    expect(blocks.find((b) => b.kind === "paragraph" && b.text === "Trailing.")).toBeDefined();
+  });
+
+  it("recognizes a multi-line ┌─┐ │…│ └─┘ frame (flow charts and diagrams)", () => {
+    const md = [
+      "┌──────────────┐",
+      "│ step 1       │",
+      "│  ↓           │",
+      "│ step 2       │",
+      "└──────────────┘",
+    ].join("\n");
+    const blocks = parseBlocks(md);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({ kind: "code" });
+    if (blocks[0]?.kind === "code") {
+      expect(blocks[0].text).toContain("step 1");
+      expect(blocks[0].text).toContain("step 2");
+      expect(blocks[0].text).toContain("↓");
+      // Outer │ characters got stripped — content reads cleanly.
+      expect(blocks[0].text).not.toContain("│");
+    }
+  });
+
+  it("falls back to paragraph when the closing └─┘ is missing", () => {
+    const md = ["┌────┐", "│ a  │", "no closing edge here"].join("\n");
+    const blocks = parseBlocks(md);
+    // No code block emitted — the open-edge line stays as paragraph.
+    expect(blocks.find((b) => b.kind === "code")).toBeUndefined();
+  });
+});
+
+describe("stripInlineMarkup + visibleWidth", () => {
+  it("strips bold markers", () => {
+    expect(stripInlineMarkup("**hello**")).toBe("hello");
+  });
+  it("strips inline code backticks", () => {
+    expect(stripInlineMarkup("call `dispatch()` now")).toBe("call dispatch() now");
+  });
+  it("strips italic markers but leaves single * inside words", () => {
+    expect(stripInlineMarkup("*emphasis*")).toBe("emphasis");
+    expect(stripInlineMarkup("a*b*c")).toBe("a*b*c");
+  });
+  it("strips triple-backtick spans + their language tag", () => {
+    expect(stripInlineMarkup("```bash echo hi```")).toBe("echo hi");
+  });
+  it("visibleWidth excludes markup chars", () => {
+    // raw is 19 chars, visible is "定义 dispatch" = 4 (CJK ×2) + 1 (space) + 8 = 13
+    expect(visibleWidth("**定义** `dispatch`")).toBe(13);
+  });
+  it("table cells with inline markup get sized by visible width, not raw", () => {
+    // Header is plain, rows have inline code. The column sized by raw
+    // length would be too wide; visibleWidth keeps things aligned to
+    // what the user actually sees.
+    const md = ["| 位置 | 角色 |", "|------|------|", "| `src/tools.ts` | 定义 dispatch |"].join(
+      "\n",
+    );
+    const [t] = parseBlocks(md).filter((b) => b.kind === "table");
+    expect(t).toBeDefined();
+    if (t && t.kind === "table") {
+      expect(t.rows[0]).toEqual(["`src/tools.ts`", "定义 dispatch"]);
+    }
+  });
+});
+
+describe("parseBlocks — fenced code blocks", () => {
+  it("recognizes a plain multi-line fence", () => {
+    const blocks = parseBlocks("```bash\necho hi\necho bye\n```");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toEqual({ kind: "code", lang: "bash", text: "echo hi\necho bye" });
+  });
+
+  it("allows up to 3 leading spaces on the fence line (GFM)", () => {
+    const blocks = parseBlocks("   ```bash\n   echo indented\n   ```");
+    const code = blocks.find((b) => b.kind === "code");
+    expect(code).toBeDefined();
+    expect(code && code.kind === "code" && code.lang).toBe("bash");
+  });
+
+  it("handles a one-line fenced code block (model puts everything on one line)", () => {
+    const blocks = parseBlocks("```bash svn commit -m hi```");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toEqual({ kind: "code", lang: "bash", text: "svn commit -m hi" });
+  });
+
+  it("handles a one-line fenced block surrounded by prose paragraphs", () => {
+    const blocks = parseBlocks("Run this:\n\n```bash svn status```\n\nOr:\n\n```bash svn log```");
+    expect(blocks).toHaveLength(4);
+    expect(blocks[0]).toMatchObject({ kind: "paragraph" });
+    expect(blocks[1]).toMatchObject({ kind: "code", text: "svn status" });
+    expect(blocks[2]).toMatchObject({ kind: "paragraph" });
+    expect(blocks[3]).toMatchObject({ kind: "code", text: "svn log" });
+  });
+
+  it("closing fence must be at least as long as the opening fence", () => {
+    // Opened with 4 backticks so body can contain 3 without closing.
+    const blocks = parseBlocks("````\nsome ``` code\n````");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toEqual({ kind: "code", lang: "", text: "some ``` code" });
+  });
+
+  it("an unclosed fence still emits a code block at EOF", () => {
+    const blocks = parseBlocks("```python\nprint('hi')");
+    const code = blocks.find((b) => b.kind === "code");
+    expect(code && code.kind === "code" && code.text).toBe("print('hi')");
+  });
+});
+
+describe("citation links — parseCitationUrl", () => {
+  it("parses bare path", () => {
+    expect(parseCitationUrl("src/foo.ts")).toEqual({ path: "src/foo.ts" });
+  });
+
+  it("parses path:line", () => {
+    expect(parseCitationUrl("src/foo.ts:42")).toEqual({ path: "src/foo.ts", startLine: 42 });
+  });
+
+  it("parses path:start-end range", () => {
+    expect(parseCitationUrl("src/foo.ts:42-58")).toEqual({
+      path: "src/foo.ts",
+      startLine: 42,
+      endLine: 58,
+    });
+  });
+
+  it("parses GitHub-style #L42 anchor", () => {
+    expect(parseCitationUrl("src/foo.ts#L42")).toEqual({ path: "src/foo.ts", startLine: 42 });
+  });
+
+  it("parses GitHub-style #L42-L58 range", () => {
+    expect(parseCitationUrl("src/foo.ts#L42-L58")).toEqual({
+      path: "src/foo.ts",
+      startLine: 42,
+      endLine: 58,
+    });
+  });
+
+  it("returns null on empty input", () => {
+    expect(parseCitationUrl("")).toBeNull();
+    expect(parseCitationUrl("   ")).toBeNull();
+  });
+});
+
+describe("citation links — isExternalUrl", () => {
+  it("recognizes http/https/ftp", () => {
+    expect(isExternalUrl("https://example.com")).toBe(true);
+    expect(isExternalUrl("http://example.com")).toBe(true);
+    expect(isExternalUrl("ftp://example.com")).toBe(true);
+  });
+
+  it("recognizes mailto and protocol-relative", () => {
+    expect(isExternalUrl("mailto:[email protected]")).toBe(true);
+    expect(isExternalUrl("//cdn.example.com/x")).toBe(true);
+  });
+
+  it("rejects local paths and bare names", () => {
+    expect(isExternalUrl("src/foo.ts")).toBe(false);
+    expect(isExternalUrl("src/foo.ts:42")).toBe(false);
+    expect(isExternalUrl("README.md")).toBe(false);
+    expect(isExternalUrl("./foo")).toBe(false);
+  });
+});
+
+describe("citation links — validateCitation + collectCitations", () => {
+  let tmp: string;
+  beforeAll(() => {
+    tmp = mkdtempSync(join(tmpdir(), "reasonix-citation-"));
+    writeFileSync(join(tmp, "real.ts"), "line1\nline2\nline3\nline4\nline5\n");
+  });
+  afterAll(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("file exists, no line → ok", () => {
+    expect(validateCitation("real.ts", tmp)).toEqual({ ok: true });
+  });
+
+  it("file exists, line in range → ok", () => {
+    expect(validateCitation("real.ts:3", tmp)).toEqual({ ok: true });
+  });
+
+  it("file exists, line out of range → broken with reason", () => {
+    const result = validateCitation("real.ts:99", tmp);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toContain("99");
+  });
+
+  it("range end out of file → broken", () => {
+    const result = validateCitation("real.ts:1-99", tmp);
+    expect(result.ok).toBe(false);
+  });
+
+  it("missing file → broken with 'file not found'", () => {
+    const result = validateCitation("ghost.ts:1", tmp);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe("file not found");
+  });
+
+  it("leading `/` is treated as project-rooted, not filesystem-absolute", () => {
+    // Models habitually write `/foo.ts` meaning "project root" (Aider /
+    // Claude-Code style). Without the strip this would be resolved
+    // against POSIX `/` or the Windows drive root and always fail —
+    // that was the symptom in 0.5.16: a real file at the project root
+    // rendered as "file not found" because the leading slash sent the
+    // validator to the wrong place.
+    expect(validateCitation("/real.ts", tmp)).toEqual({ ok: true });
+    expect(validateCitation("/real.ts:2", tmp)).toEqual({ ok: true });
+  });
+
+  it("leading `\\` is treated the same way (Windows-style)", () => {
+    expect(validateCitation("\\real.ts", tmp)).toEqual({ ok: true });
+  });
+
+  it("collectCitations validates every unique citation, skips externals", () => {
+    const text = [
+      "See [foo](real.ts:2) for details.",
+      "Compare with [bar](https://example.com).",
+      "Bogus claim [baz](ghost.ts:1).",
+      "Another [foo again](real.ts:2).",
+    ].join("\n");
+    const map = collectCitations(text, tmp);
+    expect(map.size).toBe(2);
+    expect(map.get("real.ts:2")).toEqual({ ok: true });
+    expect(map.get("ghost.ts:1")?.ok).toBe(false);
+    expect(map.has("https://example.com")).toBe(false);
+  });
+});
+
+describe("citation links — parseBlocks regression", () => {
+  it("plain markdown link inside paragraph still parses as paragraph", () => {
+    const blocks = parseBlocks("See [the docs](src/foo.ts:42) for context.");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]?.kind).toBe("paragraph");
+    if (blocks[0]?.kind === "paragraph") {
+      expect(blocks[0].text).toContain("[the docs](src/foo.ts:42)");
+    }
+  });
+
+  it("stripInlineMarkup extracts link text only", () => {
+    expect(stripInlineMarkup("see [foo](path.ts:10) here")).toBe("see foo here");
+  });
+
+  it("visibleWidth ignores link URL", () => {
+    // "see " + "foo" + " here" = 12 visible chars
+    expect(visibleWidth("see [foo](path.ts:10) here")).toBe(12);
+  });
 });

tests/mcp-browse.test.ts

@@ -0,0 +1,299 @@
+import { describe, expect, it, vi } from "vitest";
+import type { DisplayEvent } from "../src/cli/ui/EventLog.js";
+import {
+  findServerForPrompt,
+  findServerForResource,
+  formatPromptList,
+  formatPromptMessages,
+  formatResourceContents,
+  formatResourceList,
+  handleMcpBrowseSlash,
+} from "../src/cli/ui/mcp-browse.js";
+import type { McpServerSummary } from "../src/cli/ui/slash.js";
+import type { McpClient } from "../src/mcp/client.js";
+
+function server(partial: Partial<McpServerSummary> & { label: string }): McpServerSummary {
+  return {
+    spec: partial.spec ?? `fake://${partial.label}`,
+    toolCount: partial.toolCount ?? 0,
+    report: partial.report ?? {
+      protocolVersion: "2024-11-05",
+      serverInfo: { name: partial.label, version: "1.0" },
+      capabilities: {},
+      tools: { supported: true, items: [] },
+      resources: { supported: true, items: [] },
+      prompts: { supported: true, items: [] },
+    },
+    ...partial,
+  };
+}
+
+describe("formatResourceList", () => {
+  it("returns a polite message when no server exposes any resources", () => {
+    expect(formatResourceList([])).toMatch(/No resources/);
+  });
+
+  it("groups URIs by server label, shows name + mime when present", () => {
+    const out = formatResourceList([
+      server({
+        label: "fs",
+        report: {
+          protocolVersion: "2024-11-05",
+          serverInfo: { name: "fs", version: "1" },
+          capabilities: {},
+          tools: { supported: true, items: [] },
+          prompts: { supported: false, reason: "" },
+          resources: {
+            supported: true,
+            items: [{ uri: "file:///a.md", name: "a.md", mimeType: "text/markdown" }],
+          },
+        },
+      }),
+    ]);
+    expect(out).toContain("[fs] 1 resource(s):");
+    expect(out).toContain("file:///a.md");
+    expect(out).toContain("a.md");
+    expect(out).toContain("text/markdown");
+  });
+});
+
+describe("formatPromptList", () => {
+  it("returns a polite message when no server exposes any prompts", () => {
+    expect(formatPromptList([])).toMatch(/No prompts/);
+  });
+
+  it("shows argument requirement markers (*/?)", () => {
+    const out = formatPromptList([
+      server({
+        label: "p",
+        report: {
+          protocolVersion: "2024-11-05",
+          serverInfo: { name: "p", version: "1" },
+          capabilities: {},
+          tools: { supported: true, items: [] },
+          resources: { supported: false, reason: "" },
+          prompts: {
+            supported: true,
+            items: [
+              {
+                name: "summarize",
+                description: "one-line summary",
+                arguments: [
+                  { name: "topic", required: true },
+                  { name: "length", required: false },
+                ],
+              },
+            ],
+          },
+        },
+      }),
+    ]);
+    expect(out).toContain("summarize");
+    expect(out).toContain("topic*");
+    expect(out).toContain("length?");
+    expect(out).toContain("one-line summary");
+  });
+});
+
+describe("findServerForResource", () => {
+  it("returns the server that claims the URI", () => {
+    const a = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        prompts: { supported: false, reason: "" },
+        resources: { supported: true, items: [{ uri: "x://1", name: "x1" }] },
+      },
+    });
+    const b = server({
+      label: "b",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "b", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        prompts: { supported: false, reason: "" },
+        resources: { supported: true, items: [{ uri: "y://2", name: "y2" }] },
+      },
+    });
+    expect(findServerForResource([a, b], "y://2")).toBe(b);
+    expect(findServerForResource([a, b], "nope://")).toBeNull();
+  });
+
+  it("skips servers that don't support resources", () => {
+    const a = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        prompts: { supported: false, reason: "" },
+        resources: { supported: false, reason: "-32601" },
+      },
+    });
+    expect(findServerForResource([a], "x://any")).toBeNull();
+  });
+});
+
+describe("findServerForPrompt", () => {
+  it("returns the server that claims the prompt name", () => {
+    const a = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        resources: { supported: false, reason: "" },
+        prompts: { supported: true, items: [{ name: "summarize" }] },
+      },
+    });
+    expect(findServerForPrompt([a], "summarize")).toBe(a);
+    expect(findServerForPrompt([a], "missing")).toBeNull();
+  });
+});
+
+describe("formatResourceContents", () => {
+  it("renders a text block verbatim", () => {
+    const out = formatResourceContents("x://1", {
+      contents: [{ uri: "x://1", mimeType: "text/plain", text: "hello world" }],
+    });
+    expect(out).toContain("hello world");
+    expect(out).toContain("text/plain");
+  });
+
+  it("truncates extremely large text blocks with a notice", () => {
+    const big = "A".repeat(12_000);
+    const out = formatResourceContents("x://1", {
+      contents: [{ uri: "x://1", text: big }],
+    });
+    expect(out).toContain("truncated");
+    expect(out.length).toBeLessThan(big.length);
+  });
+
+  it("summarizes binary blobs rather than rendering them", () => {
+    const out = formatResourceContents("x://1", {
+      contents: [{ uri: "x://1", mimeType: "image/png", blob: "AAAA" }],
+    });
+    expect(out).toContain("binary");
+    expect(out).toContain("bytes");
+  });
+});
+
+describe("formatPromptMessages", () => {
+  it("renders role + text content for each message", () => {
+    const out = formatPromptMessages("summarize", {
+      description: "one-line summary",
+      messages: [
+        { role: "user", content: { type: "text", text: "Summarize X." } as any },
+        { role: "assistant", content: { type: "text", text: "X is …" } as any },
+      ],
+    });
+    expect(out).toContain("summarize");
+    expect(out).toContain("one-line summary");
+    expect(out).toContain("user");
+    expect(out).toContain("assistant");
+    expect(out).toContain("Summarize X.");
+    expect(out).toContain("X is …");
+  });
+});
+
+describe("handleMcpBrowseSlash", () => {
+  function makeSetter() {
+    const rows: DisplayEvent[] = [];
+    const setter = (updater: (prev: DisplayEvent[]) => DisplayEvent[]) => {
+      const next = updater(rows.slice());
+      rows.splice(0, rows.length, ...next);
+    };
+    return { rows, setter };
+  }
+
+  it("list mode: no arg writes a single info row with the list text", async () => {
+    const { rows, setter } = makeSetter();
+    await handleMcpBrowseSlash("resource", "", [], setter);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.role).toBe("info");
+    expect(rows[0]?.text).toMatch(/No resources/);
+  });
+
+  it("read mode: unknown URI emits a warning row", async () => {
+    const { rows, setter } = makeSetter();
+    await handleMcpBrowseSlash("resource", "mystery://1", [], setter);
+    expect(rows[0]?.role).toBe("warning");
+    expect(rows[0]?.text).toContain("no server exposes resource");
+  });
+
+  it("read mode: calls client.readResource and emits the formatted contents", async () => {
+    const { rows, setter } = makeSetter();
+    const readResource = vi.fn(async () => ({
+      contents: [{ uri: "x://1", text: "hello" }],
+    }));
+    const fake: McpServerSummary = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        prompts: { supported: false, reason: "" },
+        resources: { supported: true, items: [{ uri: "x://1", name: "x1" }] },
+      },
+      client: { readResource } as unknown as McpClient,
+    });
+    await handleMcpBrowseSlash("resource", "x://1", [fake], setter);
+    expect(readResource).toHaveBeenCalledWith("x://1");
+    expect(rows[0]?.role).toBe("info");
+    expect(rows[0]?.text).toContain("hello");
+  });
+
+  it("read mode: surfaces readResource rejection as a warning row", async () => {
+    const { rows, setter } = makeSetter();
+    const fake: McpServerSummary = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        prompts: { supported: false, reason: "" },
+        resources: { supported: true, items: [{ uri: "x://1", name: "x1" }] },
+      },
+      client: {
+        readResource: vi.fn(async () => {
+          throw new Error("server returned -32002 not-found");
+        }),
+      } as unknown as McpClient,
+    });
+    await handleMcpBrowseSlash("resource", "x://1", [fake], setter);
+    expect(rows[0]?.role).toBe("warning");
+    expect(rows[0]?.text).toContain("-32002");
+  });
+
+  it("prompt mode: calls client.getPrompt and emits messages", async () => {
+    const { rows, setter } = makeSetter();
+    const getPrompt = vi.fn(async () => ({
+      description: "hi",
+      messages: [{ role: "user", content: { type: "text", text: "Hello." } as any }],
+    }));
+    const fake: McpServerSummary = server({
+      label: "a",
+      report: {
+        protocolVersion: "",
+        serverInfo: { name: "a", version: "" },
+        capabilities: {},
+        tools: { supported: true, items: [] },
+        resources: { supported: false, reason: "" },
+        prompts: { supported: true, items: [{ name: "greet" }] },
+      },
+      client: { getPrompt } as unknown as McpClient,
+    });
+    await handleMcpBrowseSlash("prompt", "greet", [fake], setter);
+    expect(getPrompt).toHaveBeenCalledWith("greet");
+    expect(rows[0]?.role).toBe("info");
+    expect(rows[0]?.text).toContain("Hello.");
+  });
+});

tests/multiline-keys.test.ts

@@ -1,112 +1,245 @@
 import { describe, expect, it } from "vitest";
-import { type MultilineKey, processMultilineKey } from "../src/cli/ui/multiline-keys.js";
+import {
+  type MultilineKey,
+  lineAndColumn,
+  processMultilineKey,
+} from "../src/cli/ui/multiline-keys.js";
 
 function key(overrides: Partial<MultilineKey> = {}): MultilineKey {
   return { input: "", ...overrides };
 }
 
-describe("processMultilineKey", () => {
-  it("appends printable input at the end", () => {
-    const r = processMultilineKey("hel", key({ input: "l" }));
-    expect(r).toEqual({ next: "hell", submit: false });
+describe("processMultilineKey — inserts at cursor", () => {
+  it("inserts a printable char at the cursor (mid-string)", () => {
+    // "heo", cursor after "he" → insert "ll" in the middle
+    const r = processMultilineKey("heo", 2, key({ input: "ll" }));
+    expect(r.next).toBe("hello");
+    expect(r.cursor).toBe(4);
   });
 
-  it("appends a multi-char paste burst as-is", () => {
-    const r = processMultilineKey("", key({ input: "line1\nline2" }));
-    expect(r.next).toBe("line1\nline2");
+  it("appends when cursor is at end", () => {
+    const r = processMultilineKey("hel", 3, key({ input: "l" }));
+    expect(r.next).toBe("hell");
+    expect(r.cursor).toBe(4);
+  });
+
+  it("inserts at position 0", () => {
+    const r = processMultilineKey("bc", 0, key({ input: "a" }));
+    expect(r.next).toBe("abc");
+    expect(r.cursor).toBe(1);
+  });
+
+  it("multi-char paste burst inserts as a block", () => {
+    const r = processMultilineKey("ab", 1, key({ input: "XYZ" }));
+    expect(r.next).toBe("aXYZb");
+    expect(r.cursor).toBe(4);
+  });
+
+  it("pasted newline lands inline (not a submit)", () => {
+    const r = processMultilineKey("a", 1, key({ input: "\nmore" }));
+    expect(r.next).toBe("a\nmore");
     expect(r.submit).toBe(false);
   });
+});
 
-  it("Enter on a plain buffer submits", () => {
-    const r = processMultilineKey("hi", key({ return: true }));
+describe("processMultilineKey — submit + newline", () => {
+  it("Enter submits by default", () => {
+    const r = processMultilineKey("hi", 2, key({ return: true }));
     expect(r.submit).toBe(true);
     expect(r.submitValue).toBe("hi");
-    expect(r.next).toBeNull();
   });
 
-  it("Enter with trailing backslash converts to newline (bash-style continuation)", () => {
-    const r = processMultilineKey("line1\\", key({ return: true }));
+  it("Shift+Enter inserts a newline at the cursor", () => {
+    const r = processMultilineKey("abc", 1, key({ return: true, shift: true }));
+    expect(r.next).toBe("a\nbc");
+    expect(r.cursor).toBe(2);
+    expect(r.submit).toBe(false);
+  });
+
+  it("Ctrl+J inserts a newline at the cursor (ASCII LF form)", () => {
+    const r = processMultilineKey("abc", 2, key({ input: "\n" }));
+    expect(r.next).toBe("ab\nc");
+    expect(r.cursor).toBe(3);
+  });
+
+  it("Ctrl+J normalized as ctrl+'j' also inserts a newline", () => {
+    const r = processMultilineKey("abc", 2, key({ input: "j", ctrl: true }));
+    expect(r.next).toBe("ab\nc");
+  });
+
+  it("Enter with trailing \\\\ at end-of-buffer → bash continuation", () => {
+    const v = "line1\\";
+    const r = processMultilineKey(v, v.length, key({ return: true }));
     expect(r.submit).toBe(false);
     expect(r.next).toBe("line1\n");
+    expect(r.cursor).toBe(6);
   });
 
-  it("Shift+Enter inserts a newline without submitting", () => {
-    const r = processMultilineKey("abc", key({ return: true, shift: true }));
-    expect(r.submit).toBe(false);
-    expect(r.next).toBe("abc\n");
-  });
-
-  it("Ctrl+J (ASCII LF) inserts a newline", () => {
-    const r = processMultilineKey("abc", key({ input: "\n" }));
-    expect(r.next).toBe("abc\n");
-    expect(r.submit).toBe(false);
-  });
-
-  it("Ctrl+J reported as ctrl+'j' (normalized form) also inserts a newline", () => {
-    const r = processMultilineKey("abc", key({ input: "j", ctrl: true }));
-    expect(r.next).toBe("abc\n");
-    expect(r.submit).toBe(false);
-  });
-
-  it("Backspace drops one char from the end", () => {
-    const r = processMultilineKey("abcd", key({ backspace: true }));
-    expect(r.next).toBe("abc");
-  });
-
-  it("Backspace on empty buffer is a no-op", () => {
-    const r = processMultilineKey("", key({ backspace: true }));
-    expect(r.next).toBeNull();
-    expect(r.submit).toBe(false);
-  });
-
-  it("Backspace can delete across newlines", () => {
-    const r = processMultilineKey("a\nb", key({ backspace: true }));
-    expect(r.next).toBe("a\n");
-    const r2 = processMultilineKey(r.next!, key({ backspace: true }));
-    expect(r2.next).toBe("a");
-  });
-
-  it("Delete behaves like Backspace (cursor-at-end model)", () => {
-    const r = processMultilineKey("xyz", key({ delete: true }));
-    expect(r.next).toBe("xy");
-  });
-
-  it("Tab is ignored (parent handles slash auto-complete)", () => {
-    const r = processMultilineKey("/he", key({ tab: true, input: "" }));
-    expect(r.next).toBeNull();
-    expect(r.submit).toBe(false);
-  });
-
-  it("Tab with '\\t' in input is still ignored", () => {
-    const r = processMultilineKey("x", key({ tab: true, input: "\t" }));
+  it("Enter with \\\\ mid-buffer (cursor not at end) does NOT trigger continuation", () => {
+    // User has "foo\\bar" and hits Enter with cursor after "foo\\" — that's
+    // a real edit, not a continuation marker. Submit instead.
+    const r = processMultilineKey("foo\\bar", 4, key({ return: true }));
+    expect(r.submit).toBe(true);
     expect(r.next).toBeNull();
   });
 
-  it("Arrow keys are ignored (parent handles slash-nav + history)", () => {
-    expect(processMultilineKey("x", key({ upArrow: true })).next).toBeNull();
-    expect(processMultilineKey("x", key({ downArrow: true })).next).toBeNull();
-    expect(processMultilineKey("x", key({ leftArrow: true })).next).toBeNull();
-    expect(processMultilineKey("x", key({ rightArrow: true })).next).toBeNull();
-  });
-
-  it("Escape is ignored (parent handles abort)", () => {
-    const r = processMultilineKey("x", key({ escape: true }));
-    expect(r.next).toBeNull();
-  });
-
-  it("Ctrl+<letter> that isn't j is dropped (no accidental text insert)", () => {
-    const r = processMultilineKey("x", key({ input: "c", ctrl: true }));
-    expect(r.next).toBeNull();
-  });
-
-  it("Meta (Alt) key events are dropped", () => {
-    const r = processMultilineKey("x", key({ input: "a", meta: true }));
-    expect(r.next).toBeNull();
-  });
-
-  it("Plain return on an empty buffer still submits (empty message case handled upstream)", () => {
-    const r = processMultilineKey("", key({ return: true }));
+  it("plain Enter on an empty buffer still submits", () => {
+    const r = processMultilineKey("", 0, key({ return: true }));
     expect(r.submit).toBe(true);
     expect(r.submitValue).toBe("");
   });
 });
+
+describe("processMultilineKey — deletion", () => {
+  it("Backspace deletes the char BEFORE the cursor, cursor moves back", () => {
+    const r = processMultilineKey("abcd", 2, key({ backspace: true }));
+    expect(r.next).toBe("acd");
+    expect(r.cursor).toBe(1);
+  });
+
+  it("Backspace at cursor 0 is a no-op", () => {
+    const r = processMultilineKey("abc", 0, key({ backspace: true }));
+    expect(r.next).toBeNull();
+    expect(r.cursor).toBeNull();
+  });
+
+  it("Delete behaves like Backspace (unified — some Windows terminals report Backspace as delete)", () => {
+    const r = processMultilineKey("abcd", 2, key({ delete: true }));
+    expect(r.next).toBe("acd");
+    expect(r.cursor).toBe(1);
+  });
+
+  it("Delete at cursor 0 is a no-op (nothing before the cursor)", () => {
+    const r = processMultilineKey("abc", 0, key({ delete: true }));
+    expect(r.next).toBeNull();
+  });
+
+  it("raw DEL byte (0x7f) in key.input is treated as backspace", () => {
+    const r = processMultilineKey("abcd", 2, key({ input: "\x7f" }));
+    expect(r.next).toBe("acd");
+    expect(r.cursor).toBe(1);
+  });
+
+  it("raw BS byte (0x08) in key.input is treated as backspace", () => {
+    const r = processMultilineKey("abcd", 2, key({ input: "\b" }));
+    expect(r.next).toBe("acd");
+    expect(r.cursor).toBe(1);
+  });
+
+  it("Backspace across a newline removes the newline", () => {
+    const r = processMultilineKey("a\nb", 2, key({ backspace: true }));
+    expect(r.next).toBe("ab");
+    expect(r.cursor).toBe(1);
+  });
+});
+
+describe("processMultilineKey — cursor motion", () => {
+  it("←/→ clamp to the buffer", () => {
+    expect(processMultilineKey("abc", 2, key({ leftArrow: true })).cursor).toBe(1);
+    expect(processMultilineKey("abc", 0, key({ leftArrow: true })).cursor).toBe(0);
+    expect(processMultilineKey("abc", 2, key({ rightArrow: true })).cursor).toBe(3);
+    expect(processMultilineKey("abc", 3, key({ rightArrow: true })).cursor).toBe(3);
+  });
+
+  it("↑/↓ on a single-line non-empty buffer is a no-op (doesn't eat for history)", () => {
+    // Single-line buffer: moveCursorUp has nowhere to go. Returns NOOP so
+    // the parent can decide what to do — but parent only does history on
+    // empty buffer, so the net effect is "nothing happens."
+    const up = processMultilineKey("hello", 3, key({ upArrow: true }));
+    expect(up).toEqual({ next: null, cursor: null, submit: false });
+    const down = processMultilineKey("hello", 3, key({ downArrow: true }));
+    expect(down).toEqual({ next: null, cursor: null, submit: false });
+  });
+
+  it("↑/↓ on an empty buffer defers to the parent (history recall)", () => {
+    expect(processMultilineKey("", 0, key({ upArrow: true }))).toEqual({
+      next: null,
+      cursor: null,
+      submit: false,
+    });
+    expect(processMultilineKey("", 0, key({ downArrow: true }))).toEqual({
+      next: null,
+      cursor: null,
+      submit: false,
+    });
+  });
+
+  it("↑ moves cursor to the previous line, preserving column when possible", () => {
+    //  line 0: "hello" (cols 0-5)
+    //  line 1: "world" (cols 0-5)
+    //  cursor at col 3 on line 1 = index 5 (for "\n") + 3 + 1 = 9
+    const v = "hello\nworld";
+    const up = processMultilineKey(v, 9, key({ upArrow: true }));
+    // target: line 0 col 3 → index 3
+    expect(up.cursor).toBe(3);
+  });
+
+  it("↑ clamps column when the previous line is shorter", () => {
+    const v = "hi\nworld";
+    // cursor at line 1 col 4 = index 3 + 4 = 7
+    const up = processMultilineKey(v, 7, key({ upArrow: true }));
+    // target: line 0 col min(4, 2) = 2 → index 2
+    expect(up.cursor).toBe(2);
+  });
+
+  it("↓ moves cursor to the next line, preserving column", () => {
+    const v = "hello\nworld";
+    // cursor at line 0 col 2 = index 2
+    const down = processMultilineKey(v, 2, key({ downArrow: true }));
+    // target: line 1 col 2 → index 6 + 2 = 8
+    expect(down.cursor).toBe(8);
+  });
+
+  it("↓ clamps column when the next line is shorter", () => {
+    const v = "world\nhi";
+    // cursor at line 0 col 4 = index 4
+    const down = processMultilineKey(v, 4, key({ downArrow: true }));
+    // target: line 1 col min(4, 2) = 2 → index 6 + 2 = 8
+    expect(down.cursor).toBe(8);
+  });
+
+  it("Ctrl+A jumps to start of current line, Ctrl+E to end", () => {
+    const v = "one\ntwo\nthree";
+    // cursor mid-"two" at index 5 (o in two)
+    expect(processMultilineKey(v, 5, key({ input: "a", ctrl: true })).cursor).toBe(4);
+    expect(processMultilineKey(v, 5, key({ input: "e", ctrl: true })).cursor).toBe(7);
+  });
+});
+
+describe("processMultilineKey — parent-owned keys are ignored", () => {
+  it("Tab / Escape / PageUp / PageDown are dropped", () => {
+    expect(processMultilineKey("x", 1, key({ tab: true }))).toEqual({
+      next: null,
+      cursor: null,
+      submit: false,
+    });
+    expect(processMultilineKey("x", 1, key({ escape: true })).next).toBeNull();
+    expect(processMultilineKey("x", 1, key({ pageUp: true })).next).toBeNull();
+    expect(processMultilineKey("x", 1, key({ pageDown: true })).next).toBeNull();
+  });
+
+  it("unhandled Ctrl-<letter> chords are dropped (no accidental insert)", () => {
+    const r = processMultilineKey("x", 1, key({ input: "c", ctrl: true }));
+    expect(r.next).toBeNull();
+    expect(r.cursor).toBeNull();
+  });
+
+  it("Meta (Alt) key events are dropped", () => {
+    const r = processMultilineKey("x", 1, key({ input: "a", meta: true }));
+    expect(r.next).toBeNull();
+  });
+});
+
+describe("lineAndColumn", () => {
+  it("maps a cursor offset to {line, col}", () => {
+    expect(lineAndColumn("abc", 2)).toEqual({ line: 0, col: 2 });
+    expect(lineAndColumn("abc\ndef", 4)).toEqual({ line: 1, col: 0 });
+    expect(lineAndColumn("abc\ndef", 6)).toEqual({ line: 1, col: 2 });
+    expect(lineAndColumn("a\n\nb", 2)).toEqual({ line: 1, col: 0 });
+    expect(lineAndColumn("a\n\nb", 3)).toEqual({ line: 2, col: 0 });
+  });
+
+  it("clamps cursor values past value.length", () => {
+    expect(lineAndColumn("abc", 99)).toEqual({ line: 0, col: 3 });
+  });
+});

tests/paste-collapse.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_PASTE_CHAR_THRESHOLD,
+  DEFAULT_PASTE_HEAD_LINES,
+  DEFAULT_PASTE_LINE_THRESHOLD,
+  formatLongPaste,
+} from "../src/cli/ui/paste-collapse.js";
+
+describe("formatLongPaste", () => {
+  it("passes through short input verbatim", () => {
+    const r = formatLongPaste("hello world");
+    expect(r.collapsed).toBe(false);
+    expect(r.displayText).toBe("hello world");
+    expect(r.originalChars).toBe(11);
+    expect(r.originalLines).toBe(1);
+  });
+
+  it("passes through a multi-line but small-ish input", () => {
+    const r = formatLongPaste("line 1\nline 2\nline 3");
+    expect(r.collapsed).toBe(false);
+    expect(r.displayText).toBe("line 1\nline 2\nline 3");
+    expect(r.originalLines).toBe(3);
+  });
+
+  it("collapses when line count exceeds threshold", () => {
+    const input = Array.from({ length: 60 }, (_, i) => `line ${i + 1}`).join("\n");
+    const r = formatLongPaste(input);
+    expect(r.collapsed).toBe(true);
+    expect(r.originalLines).toBe(60);
+    expect(r.displayText).toMatch(/pasted/);
+    expect(r.displayText).toMatch(/60 lines/);
+    // Header + first 10 lines + "… (50 more lines)" footer.
+    expect(r.displayText).toContain("line 1");
+    expect(r.displayText).toContain("line 10");
+    expect(r.displayText).not.toContain("line 11");
+    expect(r.displayText).toMatch(/50 more lines/);
+  });
+
+  it("collapses when char count exceeds threshold even with few lines", () => {
+    const input = "x".repeat(3000); // 1 line, 3000 chars
+    const r = formatLongPaste(input);
+    expect(r.collapsed).toBe(true);
+    expect(r.originalChars).toBe(3000);
+    expect(r.displayText).toMatch(/pasted/);
+    expect(r.displayText).toMatch(/2\.9 KB|3 KB/);
+  });
+
+  it("renders bytes in KB when >= 1024", () => {
+    const r = formatLongPaste(Array.from({ length: 100 }, () => "x".repeat(30)).join("\n"));
+    expect(r.collapsed).toBe(true);
+    // 100 * 31 = ~3.0 KB
+    expect(r.displayText).toMatch(/(KB|MB)/);
+  });
+
+  it("handles single-line remaining — 'more line' not 'more lines'", () => {
+    const lines = Array.from({ length: DEFAULT_PASTE_HEAD_LINES + 1 }, (_, i) => `l${i}`);
+    // Still below the line threshold by default (head+1), so trigger via chars.
+    const big = `${lines.join("\n")}\n${"x".repeat(DEFAULT_PASTE_CHAR_THRESHOLD + 100)}`;
+    const r = formatLongPaste(big);
+    expect(r.collapsed).toBe(true);
+  });
+
+  it("respects custom thresholds", () => {
+    const r = formatLongPaste("line1\nline2\nline3", { lineThreshold: 2 });
+    expect(r.collapsed).toBe(true);
+    expect(r.displayText).toMatch(/3 lines/);
+  });
+
+  it("respects custom headLines", () => {
+    const lines = Array.from({ length: 100 }, (_, i) => `l${i}`);
+    const r = formatLongPaste(lines.join("\n"), { headLines: 3 });
+    expect(r.collapsed).toBe(true);
+    expect(r.displayText).toContain("l0");
+    expect(r.displayText).toContain("l2");
+    expect(r.displayText).not.toContain("l3");
+    expect(r.displayText).toMatch(/97 more lines/);
+  });
+
+  it("reports 0 'more lines' when headLines covers all", () => {
+    // Trigger collapse via chars, with very large headLines.
+    const big = `line1\n${"x".repeat(DEFAULT_PASTE_CHAR_THRESHOLD + 100)}`;
+    const r = formatLongPaste(big, { headLines: 999 });
+    expect(r.collapsed).toBe(true);
+    // When head covers everything, no footer is appended.
+    expect(r.displayText).not.toMatch(/more line/);
+  });
+
+  it("exposes default thresholds", () => {
+    expect(DEFAULT_PASTE_LINE_THRESHOLD).toBe(40);
+    expect(DEFAULT_PASTE_CHAR_THRESHOLD).toBe(2000);
+    expect(DEFAULT_PASTE_HEAD_LINES).toBe(10);
+  });
+});

tests/pending-edits.test.ts

@@ -0,0 +1,115 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { EditBlock } from "../src/code/edit-blocks.js";
+import {
+  clearPendingEdits,
+  loadPendingEdits,
+  pendingEditsPath,
+  savePendingEdits,
+} from "../src/code/pending-edits.js";
+import { appendSessionMessage, deleteSession, sessionPath } from "../src/session.js";
+
+function block(overrides: Partial<EditBlock> = {}): EditBlock {
+  return {
+    path: "src/a.ts",
+    search: "foo",
+    replace: "bar",
+    offset: 0,
+    ...overrides,
+  };
+}
+
+describe("pending-edits checkpoint", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "reasonix-pending-"));
+    vi.stubEnv("USERPROFILE", tmp);
+    vi.stubEnv("HOME", tmp);
+    vi.spyOn(require("node:os"), "homedir").mockReturnValue(tmp);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+    if (existsSync(tmp)) rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("pendingEditsPath is a .pending.json sibling of the session file", () => {
+    const p = pendingEditsPath("demo");
+    expect(p).toContain("sessions");
+    expect(p.endsWith("demo.pending.json")).toBe(true);
+  });
+
+  it("save → load round-trips the queue", () => {
+    const blocks = [block({ path: "a.ts" }), block({ path: "b.ts", search: "x", replace: "y" })];
+    savePendingEdits("s1", blocks);
+    const loaded = loadPendingEdits("s1");
+    expect(loaded).toEqual(blocks);
+  });
+
+  it("save with an empty array deletes the file", () => {
+    savePendingEdits("s2", [block()]);
+    expect(existsSync(pendingEditsPath("s2"))).toBe(true);
+    savePendingEdits("s2", []);
+    expect(existsSync(pendingEditsPath("s2"))).toBe(false);
+  });
+
+  it("load returns null when the file doesn't exist", () => {
+    expect(loadPendingEdits("ghost")).toBeNull();
+  });
+
+  it("load returns null for a corrupt file rather than throwing", () => {
+    // First create a real checkpoint, then trash its contents.
+    savePendingEdits("corrupt", [block()]);
+    const path = pendingEditsPath("corrupt");
+    writeFileSync(path, "{ not json", "utf8");
+    expect(loadPendingEdits("corrupt")).toBeNull();
+  });
+
+  it("load drops malformed entries but keeps valid neighbors", () => {
+    const path = pendingEditsPath("mixed");
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify([
+        block({ path: "good.ts" }),
+        { path: "bad", search: "", replace: "" }, // missing offset
+        { totally: "wrong" },
+        block({ path: "also-good.ts" }),
+      ]),
+      "utf8",
+    );
+    const loaded = loadPendingEdits("mixed");
+    expect(loaded?.map((b) => b.path)).toEqual(["good.ts", "also-good.ts"]);
+  });
+
+  it("clearPendingEdits removes the checkpoint file", () => {
+    savePendingEdits("clr", [block()]);
+    expect(existsSync(pendingEditsPath("clr"))).toBe(true);
+    clearPendingEdits("clr");
+    expect(existsSync(pendingEditsPath("clr"))).toBe(false);
+  });
+
+  it("clearPendingEdits is a no-op when the file is already missing", () => {
+    expect(() => clearPendingEdits("ghost")).not.toThrow();
+  });
+
+  it("save / load / clear are all no-ops when sessionName is null (ephemeral)", () => {
+    expect(() => savePendingEdits(null, [block()])).not.toThrow();
+    expect(loadPendingEdits(null)).toBeNull();
+    expect(() => clearPendingEdits(null)).not.toThrow();
+  });
+
+  it("deleteSession removes the pending-edits sidecar too", () => {
+    appendSessionMessage("combo", { role: "user", content: "hi" });
+    savePendingEdits("combo", [block()]);
+    expect(existsSync(pendingEditsPath("combo"))).toBe(true);
+    expect(existsSync(sessionPath("combo"))).toBe(true);
+    deleteSession("combo");
+    expect(existsSync(sessionPath("combo"))).toBe(false);
+    expect(existsSync(pendingEditsPath("combo"))).toBe(false);
+  });
+});

tests/plan-confirm.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { clampBodyByLines } from "../src/cli/ui/PlanConfirm.js";
+
+describe("clampBodyByLines", () => {
+  it("returns text unchanged when already within the row budget", () => {
+    const text = "line 1\nline 2\nline 3";
+    expect(clampBodyByLines(text, 10)).toBe(text);
+  });
+
+  it("trims to the first N lines and appends a truncation marker", () => {
+    const lines = Array.from({ length: 40 }, (_, i) => `line ${i + 1}`);
+    const out = clampBodyByLines(lines.join("\n"), 10);
+    expect(out.split("\n").slice(0, 10)).toEqual(lines.slice(0, 10));
+    expect(out).toContain("30 more lines truncated");
+  });
+
+  it("shows the dropped-line count for the truncation hint", () => {
+    const text = Array.from({ length: 25 }, (_, i) => `row${i}`).join("\n");
+    expect(clampBodyByLines(text, 5)).toContain("20 more lines truncated");
+  });
+
+  it("handles an empty body without throwing", () => {
+    expect(clampBodyByLines("", 5)).toBe("");
+  });
+
+  it("does not trim when exactly at the budget", () => {
+    const text = "a\nb\nc";
+    expect(clampBodyByLines(text, 3)).toBe(text);
+  });
+});

tests/plan.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Plan Mode — the dispatch-level enforcement (ToolRegistry read-only
+ * gate) and the submit_plan tool (PlanProposedError + toToolResult
+ * protocol).
+ */
+
+import { describe, expect, it } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import { PlanProposedError, registerPlanTool } from "../src/tools/plan.js";
+
+describe("ToolRegistry plan mode", () => {
+  it("starts with plan mode off by default", () => {
+    const reg = new ToolRegistry();
+    expect(reg.planMode).toBe(false);
+  });
+
+  it("setPlanMode toggles the flag", () => {
+    const reg = new ToolRegistry();
+    reg.setPlanMode(true);
+    expect(reg.planMode).toBe(true);
+    reg.setPlanMode(false);
+    expect(reg.planMode).toBe(false);
+  });
+
+  it("blocks non-readOnly tools when plan mode is on", async () => {
+    const reg = new ToolRegistry();
+    let ran = false;
+    reg.register({
+      name: "mutate",
+      // readOnly: undefined → treated as write
+      fn: () => {
+        ran = true;
+        return "ok";
+      },
+    });
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("mutate", "{}");
+    expect(ran).toBe(false);
+    const payload = JSON.parse(out);
+    expect(payload.error).toMatch(/unavailable in plan mode/);
+    expect(payload.error).toMatch(/submit_plan/);
+  });
+
+  it("allows readOnly tools when plan mode is on", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "read_thing",
+      readOnly: true,
+      fn: () => "the-thing",
+    });
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("read_thing", "{}");
+    expect(out).toBe("the-thing");
+  });
+
+  it("honors readOnlyCheck taking the actual arguments into account", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "maybe_read",
+      readOnlyCheck: (args: { kind?: string }) => args.kind === "read",
+      fn: (args: { kind?: string }) => `did-${args.kind}`,
+    });
+    reg.setPlanMode(true);
+    // Read call: allowed.
+    const readOut = await reg.dispatch("maybe_read", '{"kind":"read"}');
+    expect(readOut).toBe("did-read");
+    // Write call: refused.
+    const writeOut = await reg.dispatch("maybe_read", '{"kind":"write"}');
+    expect(JSON.parse(writeOut).error).toMatch(/unavailable in plan mode/);
+  });
+
+  it("readOnlyCheck takes precedence over readOnly when both are set", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "mixed",
+      readOnly: false,
+      readOnlyCheck: () => true,
+      fn: () => "ran",
+    });
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("mixed", "{}");
+    expect(out).toBe("ran");
+  });
+
+  it("with plan mode off, readOnly flags don't interfere", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "normal",
+      fn: () => "ran",
+    });
+    expect(reg.planMode).toBe(false);
+    const out = await reg.dispatch("normal", "{}");
+    expect(out).toBe("ran");
+  });
+
+  it("serializes errors via toToolResult when the thrown error implements it", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "structured_err",
+      fn: () => {
+        const err = new Error("oops") as Error & { toToolResult?: () => unknown };
+        err.name = "StructuredError";
+        err.toToolResult = () => ({ error: "StructuredError: oops", extra: "pinned-out-of-band" });
+        throw err;
+      },
+    });
+    const out = await reg.dispatch("structured_err", "{}");
+    const parsed = JSON.parse(out);
+    expect(parsed.error).toBe("StructuredError: oops");
+    expect(parsed.extra).toBe("pinned-out-of-band");
+  });
+
+  it("falls back to the default error shape when toToolResult throws", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "broken_serializer",
+      fn: () => {
+        const err = new Error("base-message") as Error & { toToolResult?: () => unknown };
+        err.name = "Broken";
+        err.toToolResult = () => {
+          throw new Error("serialization failed");
+        };
+        throw err;
+      },
+    });
+    const out = await reg.dispatch("broken_serializer", "{}");
+    expect(JSON.parse(out).error).toBe("Broken: base-message");
+  });
+});
+
+describe("PlanProposedError", () => {
+  it("carries the plan on the instance and in toToolResult()", () => {
+    const err = new PlanProposedError("# Plan\n- step 1\n- step 2");
+    expect(err.name).toBe("PlanProposedError");
+    expect(err.plan).toBe("# Plan\n- step 1\n- step 2");
+    const payload = err.toToolResult();
+    expect(payload.plan).toBe("# Plan\n- step 1\n- step 2");
+    expect(payload.error).toMatch(/^PlanProposedError:/);
+    // Message tells the model to STOP so it doesn't keep calling tools.
+    expect(payload.error).toMatch(/STOP/);
+  });
+});
+
+describe("registerPlanTool + submit_plan", () => {
+  it("registers submit_plan as readOnly so it passes the plan-mode gate", () => {
+    const reg = new ToolRegistry();
+    registerPlanTool(reg);
+    expect(reg.has("submit_plan")).toBe(true);
+    expect(reg.get("submit_plan")?.readOnly).toBe(true);
+  });
+
+  it("throws PlanProposedError when called with a plan (plan mode ON)", async () => {
+    const reg = new ToolRegistry();
+    const submitted: string[] = [];
+    registerPlanTool(reg, { onPlanSubmitted: (p) => submitted.push(p) });
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("submit_plan", JSON.stringify({ plan: "# Plan\n- A" }));
+    const parsed = JSON.parse(out);
+    expect(parsed.plan).toBe("# Plan\n- A");
+    expect(parsed.error).toMatch(/PlanProposedError/);
+    expect(submitted).toEqual(["# Plan\n- A"]);
+  });
+
+  it("also fires the picker when plan mode is OFF — autonomous proposals", async () => {
+    const reg = new ToolRegistry();
+    const submitted: string[] = [];
+    registerPlanTool(reg, { onPlanSubmitted: (p) => submitted.push(p) });
+    // Plan mode intentionally NOT enabled.
+    const out = await reg.dispatch("submit_plan", JSON.stringify({ plan: "big refactor plan" }));
+    const parsed = JSON.parse(out);
+    expect(parsed.plan).toBe("big refactor plan");
+    expect(parsed.error).toMatch(/PlanProposedError/);
+    expect(submitted).toEqual(["big refactor plan"]);
+  });
+
+  it("rejects an empty plan with a helpful message", async () => {
+    const reg = new ToolRegistry();
+    registerPlanTool(reg);
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("submit_plan", JSON.stringify({ plan: "   \n\n  " }));
+    const parsed = JSON.parse(out);
+    expect(parsed.error).toMatch(/empty plan/);
+    // Empty-plan is a regular Error, not PlanProposedError — so there's
+    // no `plan` field.
+    expect(parsed.plan).toBeUndefined();
+  });
+
+  it("trims surrounding whitespace from the plan", async () => {
+    const reg = new ToolRegistry();
+    registerPlanTool(reg);
+    reg.setPlanMode(true);
+    const out = await reg.dispatch("submit_plan", JSON.stringify({ plan: "\n\n  trimmed  \n" }));
+    expect(JSON.parse(out).plan).toBe("trimmed");
+  });
+});

tests/preflight.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Preflight context-size check tests.
+ *
+ * Reactive auto-compact keys off the PREVIOUS turn's prompt_tokens —
+ * too late to save a fresh request whose buildMessages already exceeds
+ * the model's context window. The preflight estimates locally before
+ * sending and compacts first.
+ *
+ * We set a tiny context budget on a synthetic model id so modestly-
+ * sized test content can trip the 95% threshold without churning
+ * through ~120k tokens of fake text.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+import { CacheFirstLoop } from "../src/loop.js";
+import { ImmutablePrefix } from "../src/memory.js";
+import { DEEPSEEK_CONTEXT_TOKENS } from "../src/telemetry.js";
+import type { ChatMessage } from "../src/types.js";
+
+interface FakeResponseShape {
+  content?: string;
+  usage?: Record<string, number>;
+}
+
+function fakeFetch(responses: FakeResponseShape[]): typeof fetch {
+  let i = 0;
+  return vi.fn(async () => {
+    const resp = responses[i++] ?? responses[responses.length - 1]!;
+    return new Response(
+      JSON.stringify({
+        choices: [
+          {
+            index: 0,
+            message: { role: "assistant", content: resp.content ?? "", tool_calls: undefined },
+            finish_reason: "stop",
+          },
+        ],
+        usage: resp.usage ?? {
+          prompt_tokens: 100,
+          completion_tokens: 10,
+          total_tokens: 110,
+          prompt_cache_hit_tokens: 0,
+          prompt_cache_miss_tokens: 100,
+        },
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  }) as unknown as typeof fetch;
+}
+
+function makeClient(responses: FakeResponseShape[]) {
+  return new DeepSeekClient({ apiKey: "sk-test", fetch: fakeFetch(responses) });
+}
+
+describe("preflight context-size check", () => {
+  const TEST_MODEL = "test-tiny-ctx";
+  afterEach(() => {
+    delete DEEPSEEK_CONTEXT_TOKENS[TEST_MODEL];
+  });
+
+  it("auto-compacts when the estimated request exceeds 95% of the context window", async () => {
+    // Tiny 1000-token budget so modest content can overflow.
+    DEEPSEEK_CONTEXT_TOKENS[TEST_MODEL] = 1000;
+
+    const client = makeClient([{ content: "ack" }]);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "be brief" }),
+      stream: false,
+      model: TEST_MODEL,
+    });
+
+    // Seed the log with a PROPERLY paired (assistant.tool_calls ↔
+    // tool) turn so buildMessages doesn't strip the tool result as
+    // an orphan. The tool result is oversized enough to push the
+    // preflight estimate past 95% of the 1000-token budget. Realistic
+    // log-line content to avoid the tokenizer's BPE O(n²) pathological
+    // path on pure-repeat inputs.
+    loop.log.append({ role: "user", content: "prior request" });
+    loop.log.append({
+      role: "assistant",
+      content: "",
+      tool_calls: [{ id: "prior", type: "function", function: { name: "probe", arguments: "{}" } }],
+    });
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "prior",
+      content: "ERROR: step failed with trailing detail\n".repeat(500),
+    });
+
+    const events: { role: string; content?: string }[] = [];
+    for await (const ev of loop.step("follow-up")) {
+      events.push({ role: ev.role, content: ev.content });
+    }
+
+    // Preflight fires BEFORE the request — expect a warning that names
+    // the preflight path and reports tokens saved from compaction.
+    const warn = events.find((e) => e.role === "warning" && /^preflight:/.test(e.content ?? ""));
+    expect(warn).toBeDefined();
+    expect(warn!.content).toMatch(/pre-compacted \d+ tool result/);
+    expect(warn!.content).toMatch(/saved [\d,]+ tokens/);
+
+    // Loop still completed normally (no forced summary, no error).
+    expect(events.find((e) => e.role === "error")).toBeUndefined();
+    const finals = events.filter((e) => e.role === "assistant_final");
+    expect(finals.length).toBe(1);
+  });
+
+  it("does NOT fire when the estimate is comfortably under 95%", async () => {
+    // Keep the real 131k budget — a normal conversation won't trip.
+    const client = makeClient([{ content: "ok" }]);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "be brief" }),
+      stream: false,
+    });
+
+    const events: { role: string; content?: string }[] = [];
+    for await (const ev of loop.step("hi")) {
+      events.push({ role: ev.role, content: ev.content });
+    }
+
+    const anyPreflight = events.find(
+      (e) => e.role === "warning" && /^preflight:/.test(e.content ?? ""),
+    );
+    expect(anyPreflight).toBeUndefined();
+  });
+
+  it("warns (but does not block) when over 95% with nothing to compact", async () => {
+    // Tiny budget AND a system prompt that alone overwhelms it. No
+    // tool messages exist, so compact has nothing to shrink — the
+    // preflight should still surface a warning so the failure isn't
+    // mysterious; the request goes out regardless and DeepSeek decides.
+    DEEPSEEK_CONTEXT_TOKENS[TEST_MODEL] = 500;
+    const bulkyPrompt = "You are a careful assistant. ".repeat(300);
+
+    const client = makeClient([{ content: "ack" }]);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: bulkyPrompt }),
+      stream: false,
+      model: TEST_MODEL,
+    });
+
+    const events: { role: string; content?: string }[] = [];
+    for await (const ev of loop.step("hi")) {
+      events.push({ role: ev.role, content: ev.content });
+    }
+
+    const warn = events.find((e) => e.role === "warning" && /^preflight:/.test(e.content ?? ""));
+    expect(warn).toBeDefined();
+    expect(warn!.content).toMatch(/nothing to auto-compact/);
+    // Run still reaches the final step — the user sees the warning
+    // and can react, but we don't short-circuit on our own.
+    const finals = events.filter((e) => e.role === "assistant_final");
+    expect(finals.length).toBe(1);
+  });
+});

tests/project-memory.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Tests for the `REASONIX.md` project-memory loader. Pure I/O at the
+ * edge, so filesystem-backed tests using a temp dir.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { CODE_SYSTEM_PROMPT, codeSystemPrompt } from "../src/code/prompt.js";
+import {
+  PROJECT_MEMORY_FILE,
+  PROJECT_MEMORY_MAX_CHARS,
+  applyProjectMemory,
+  memoryEnabled,
+  readProjectMemory,
+} from "../src/project-memory.js";
+
+const BASE = "You are a test assistant.";
+
+describe("project-memory", () => {
+  let root: string;
+  const originalEnv = process.env.REASONIX_MEMORY;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-mem-"));
+    // biome-ignore lint/performance/noDelete: avoid leaking "undefined" into env
+    delete process.env.REASONIX_MEMORY;
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+    if (originalEnv === undefined) {
+      // biome-ignore lint/performance/noDelete: same reason
+      delete process.env.REASONIX_MEMORY;
+    } else {
+      process.env.REASONIX_MEMORY = originalEnv;
+    }
+  });
+
+  describe("readProjectMemory", () => {
+    it("returns null when REASONIX.md is absent", () => {
+      expect(readProjectMemory(root)).toBeNull();
+    });
+
+    it("returns null when REASONIX.md is empty / whitespace-only", () => {
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), "   \n\n\t  \n", "utf8");
+      expect(readProjectMemory(root)).toBeNull();
+    });
+
+    it("returns trimmed content + correct metadata for a normal file", () => {
+      const body = "# Notes\nAlways prefer tabs over spaces in this repo.\n";
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), `\n\n${body}\n\n`, "utf8");
+      const mem = readProjectMemory(root);
+      expect(mem).not.toBeNull();
+      expect(mem?.content).toBe(body.trim());
+      expect(mem?.truncated).toBe(false);
+      expect(mem?.originalChars).toBe(body.trim().length);
+      expect(mem?.path.endsWith(PROJECT_MEMORY_FILE)).toBe(true);
+    });
+
+    it("truncates with a visible marker when over PROJECT_MEMORY_MAX_CHARS", () => {
+      const huge = "x".repeat(PROJECT_MEMORY_MAX_CHARS + 1500);
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), huge, "utf8");
+      const mem = readProjectMemory(root);
+      expect(mem?.truncated).toBe(true);
+      expect(mem?.originalChars).toBe(PROJECT_MEMORY_MAX_CHARS + 1500);
+      expect(mem?.content).toMatch(/truncated 1500 chars/);
+      // Content is bounded: first MAX chars + the marker line.
+      expect(mem?.content.length).toBeLessThan(PROJECT_MEMORY_MAX_CHARS + 64);
+    });
+  });
+
+  describe("memoryEnabled", () => {
+    it("defaults to true when env is unset", () => {
+      expect(memoryEnabled()).toBe(true);
+    });
+
+    it.each(["off", "false", "0"])("returns false for REASONIX_MEMORY=%s", (val) => {
+      process.env.REASONIX_MEMORY = val;
+      expect(memoryEnabled()).toBe(false);
+    });
+
+    it("returns true for unrelated env values (on, 1, truthy, etc.)", () => {
+      for (const val of ["on", "1", "true", "yes"]) {
+        process.env.REASONIX_MEMORY = val;
+        expect(memoryEnabled()).toBe(true);
+      }
+    });
+  });
+
+  describe("applyProjectMemory", () => {
+    it("returns the base prompt unchanged when no memory file exists", () => {
+      expect(applyProjectMemory(BASE, root)).toBe(BASE);
+    });
+
+    it("appends a '# Project memory' fenced block when the file exists", () => {
+      writeFileSync(
+        join(root, PROJECT_MEMORY_FILE),
+        "# Notes\nTreat snake_case as the house style.\n",
+        "utf8",
+      );
+      const out = applyProjectMemory(BASE, root);
+      expect(out.length).toBeGreaterThan(BASE.length);
+      expect(out).toMatch(/# Project memory \(REASONIX\.md\)/);
+      expect(out).toContain("snake_case");
+      // Fenced block present.
+      expect(out).toMatch(/```\n[\s\S]*```/);
+    });
+
+    it("no-ops when REASONIX_MEMORY=off, even with a file present", () => {
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), "content\n", "utf8");
+      process.env.REASONIX_MEMORY = "off";
+      expect(applyProjectMemory(BASE, root)).toBe(BASE);
+    });
+
+    it("is deterministic for identical inputs (cache-prefix-safe)", () => {
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), "stable content\n", "utf8");
+      const a = applyProjectMemory(BASE, root);
+      const b = applyProjectMemory(BASE, root);
+      expect(a).toBe(b);
+    });
+  });
+
+  describe("codeSystemPrompt integration", () => {
+    it("stacks base → memory → .gitignore when both files exist", () => {
+      writeFileSync(
+        join(root, PROJECT_MEMORY_FILE),
+        "## House rules\nAlways write tests alongside new tools.\n",
+        "utf8",
+      );
+      writeFileSync(join(root, ".gitignore"), "node_modules/\ndist/\n", "utf8");
+      const out = codeSystemPrompt(root);
+      const memIdx = out.indexOf("# Project memory");
+      const gitIdx = out.indexOf("# Project .gitignore");
+      expect(memIdx).toBeGreaterThan(CODE_SYSTEM_PROMPT.length - 1);
+      expect(gitIdx).toBeGreaterThan(memIdx);
+      expect(out).toContain("Always write tests");
+      expect(out).toContain("node_modules/");
+    });
+
+    it("memory alone (no .gitignore) still appends only the memory block", () => {
+      writeFileSync(join(root, PROJECT_MEMORY_FILE), "memory-only content\n", "utf8");
+      const out = codeSystemPrompt(root);
+      expect(out).toContain("memory-only content");
+      expect(out).not.toMatch(/# Project \.gitignore/);
+    });
+  });
+});

tests/repair/pipeline.test.ts

@@ -76,4 +76,22 @@ describe("ToolCallRepair pipeline", () => {
     expect(calls.length).toBe(1);
     expect(report.scavenged).toBe(1);
   });
+
+  it("resetStorm clears the repeat-window so post-reset calls aren't suppressed", () => {
+    const repair = new ToolCallRepair({
+      allowedToolNames: new Set(["x"]),
+      stormWindow: 6,
+      stormThreshold: 3,
+    });
+    // Build up to the storm threshold — third identical call would be suppressed.
+    for (let i = 0; i < 2; i++) {
+      repair.process([call(`c${i}`, "x", "{}")], null);
+    }
+    // Mid-turn reset (what step() does on each new user message).
+    repair.resetStorm();
+    // With a fresh window the next call passes through — no suppression.
+    const { calls, report } = repair.process([call("c-after", "x", "{}")], null);
+    expect(calls.length).toBe(1);
+    expect(report.stormsBroken).toBe(0);
+  });
 });

tests/session.test.ts

@@ -2,6 +2,9 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+import { CacheFirstLoop } from "../src/loop.js";
+import { ImmutablePrefix } from "../src/memory.js";
 import {
   appendSessionMessage,
   deleteSession,
@@ -103,4 +106,22 @@ describe("session persistence", () => {
     expect(existsSync(sessionsDir())).toBe(true);
     expect(existsSync(dirname(sessionPath("s")))).toBe(true);
   });
+
+  it("loop.appendAndPersist writes bang-style messages to the session file", () => {
+    // Regression: before 0.5.14 the bang handler called loop.log.append which
+    // only touched memory, so `!cmd` output was lost on session resume.
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: (async () => new Response()) as any,
+    });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s" }),
+      stream: false,
+      session: "bang-persist",
+    });
+    loop.appendAndPersist({ role: "user", content: "[!ls]\n$ ls\n[exit 0]\nfile1 file2" });
+    const reloaded = loadSessionMessages("bang-persist");
+    expect(reloaded).toEqual([{ role: "user", content: "[!ls]\n$ ls\n[exit 0]\nfile1 file2" }]);
+  });
 });

tests/shell-confirm.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { derivePrefix } from "../src/cli/ui/ShellConfirm.js";
+
+describe("derivePrefix", () => {
+  it("returns the sole token for single-word commands", () => {
+    expect(derivePrefix("ls")).toBe("ls");
+    expect(derivePrefix("pytest")).toBe("pytest");
+  });
+
+  it("uses the first two tokens for well-known wrappers", () => {
+    expect(derivePrefix("npm install lodash")).toBe("npm install");
+    expect(derivePrefix("git commit -m hi")).toBe("git commit");
+    expect(derivePrefix("cargo add serde")).toBe("cargo add");
+    expect(derivePrefix("docker run --rm foo")).toBe("docker run");
+    expect(derivePrefix("python3 -m pytest tests/")).toBe("python3 -m");
+  });
+
+  it("falls back to the first token for non-wrapper commands", () => {
+    // `node script.js` — the script name is specific to this invocation,
+    // so "node" alone is the useful prefix to persist.
+    expect(derivePrefix("node script.js")).toBe("node");
+    expect(derivePrefix("curl https://api.example.com")).toBe("curl");
+  });
+
+  it("normalizes whitespace and returns empty on empty input", () => {
+    expect(derivePrefix("   npm   install  ")).toBe("npm install");
+    expect(derivePrefix("")).toBe("");
+    expect(derivePrefix("   ")).toBe("");
+  });
+});

tests/shell-tools.test.ts

@@ -0,0 +1,638 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import {
+  NeedsConfirmationError,
+  detectShellOperator,
+  formatCommandResult,
+  injectPowerShellUtf8,
+  isAllowed,
+  prepareSpawn,
+  quoteForCmdExe,
+  registerShellTools,
+  resolveExecutable,
+  runCommand,
+  tokenizeCommand,
+} from "../src/tools/shell.js";
+
+describe("tokenizeCommand", () => {
+  it("splits on whitespace", () => {
+    expect(tokenizeCommand("git status -s")).toEqual(["git", "status", "-s"]);
+  });
+
+  it("keeps double-quoted spans as single tokens", () => {
+    expect(tokenizeCommand('grep "hello world" src')).toEqual(["grep", "hello world", "src"]);
+  });
+
+  it("keeps single-quoted spans as single tokens (literal, no backslash escapes)", () => {
+    expect(tokenizeCommand("echo 'a \\\\ b'")).toEqual(["echo", "a \\\\ b"]);
+  });
+
+  it("supports \\ escapes inside double quotes", () => {
+    expect(tokenizeCommand('echo "a \\"b\\" c"')).toEqual(["echo", 'a "b" c']);
+  });
+
+  it("rejects unclosed quotes", () => {
+    expect(() => tokenizeCommand('grep "unclosed')).toThrow(/unclosed/);
+    expect(() => tokenizeCommand("grep 'unclosed")).toThrow(/unclosed/);
+  });
+
+  it("collapses runs of whitespace", () => {
+    expect(tokenizeCommand("   git   status   ")).toEqual(["git", "status"]);
+  });
+
+  it("returns an empty array for an empty command", () => {
+    expect(tokenizeCommand("")).toEqual([]);
+    expect(tokenizeCommand("   ")).toEqual([]);
+  });
+});
+
+describe("detectShellOperator", () => {
+  it("flags a standalone pipe", () => {
+    expect(detectShellOperator("dir /b *.ts | findstr foo")).toBe("|");
+  });
+
+  it("flags standalone redirects (>, >>, <, <<)", () => {
+    expect(detectShellOperator("echo hi > out.txt")).toBe(">");
+    expect(detectShellOperator("echo hi >> out.txt")).toBe(">>");
+    expect(detectShellOperator("sort < in.txt")).toBe("<");
+    expect(detectShellOperator("cat << EOF")).toBe("<<");
+  });
+
+  it("flags &&, ||, and single &", () => {
+    expect(detectShellOperator("a && b")).toBe("&&");
+    expect(detectShellOperator("a || b")).toBe("||");
+    expect(detectShellOperator("long_task &")).toBe("&");
+  });
+
+  it("flags fd-prefixed redirects", () => {
+    expect(detectShellOperator("cmd 2> err.log")).toBe("2>");
+    expect(detectShellOperator("cmd 2>> err.log")).toBe("2>>");
+    expect(detectShellOperator("cmd 2>&1")).toBe("2>&1");
+    expect(detectShellOperator("cmd &> all.log")).toBe("&>");
+  });
+
+  it("flags redirects stuck to the next token", () => {
+    expect(detectShellOperator("echo hi >out.txt")).toBe(">");
+    expect(detectShellOperator("sort <in.txt")).toBe("<");
+  });
+
+  it("does NOT flag operators inside double quotes", () => {
+    expect(detectShellOperator('grep "a|b" file.txt')).toBeNull();
+    expect(detectShellOperator('echo "a > b"')).toBeNull();
+    expect(detectShellOperator('git commit -m "feat & fix"')).toBeNull();
+  });
+
+  it("does NOT flag operators inside single quotes", () => {
+    expect(detectShellOperator("grep 'a|b' file.txt")).toBeNull();
+    expect(detectShellOperator("awk '{print $1 > $2}' file")).toBeNull();
+  });
+
+  it("does NOT flag operator characters embedded in larger unquoted tokens", () => {
+    // `--flag=1&2` is a single token; the `&` is a literal byte, not a
+    // shell operator. Same for regex-style args passed without quotes.
+    expect(detectShellOperator("cargo run -- --flag=1&2")).toBeNull();
+    expect(detectShellOperator("grep a|b file")).toBeNull();
+  });
+
+  it("returns null for plain commands", () => {
+    expect(detectShellOperator("git status")).toBeNull();
+    expect(detectShellOperator("ls -la")).toBeNull();
+    expect(detectShellOperator("")).toBeNull();
+  });
+
+  it("returns the FIRST operator when multiple are present", () => {
+    expect(detectShellOperator("a | b > c")).toBe("|");
+  });
+});
+
+describe("runCommand pipe/redirect rejection", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "reasonix-shell-pipe-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("rejects a pipe command with a helpful error", async () => {
+    await expect(runCommand("echo hi | cat", { cwd: tmp })).rejects.toThrow(
+      /shell operator "\|" is not supported/,
+    );
+  });
+
+  it("rejects a redirect command with a helpful error", async () => {
+    await expect(runCommand("echo hi > out.txt", { cwd: tmp })).rejects.toThrow(
+      /shell operator ">" is not supported/,
+    );
+  });
+
+  it("error message points the model at splitting the call", async () => {
+    try {
+      await runCommand("a && b", { cwd: tmp });
+    } catch (err) {
+      expect((err as Error).message).toMatch(/Split into separate run_command calls/i);
+      return;
+    }
+    throw new Error("expected runCommand to reject");
+  });
+});
+
+describe("isAllowed", () => {
+  it("matches exact prefix and prefix+args", () => {
+    expect(isAllowed("git status")).toBe(true);
+    expect(isAllowed("git status -s")).toBe(true);
+    expect(isAllowed("git statuses")).toBe(false); // no trailing space → not a prefix match
+  });
+
+  it("normalizes internal whitespace", () => {
+    expect(isAllowed("git   status   -s")).toBe(true);
+  });
+
+  it("rejects mutating operations not on the list", () => {
+    expect(isAllowed("git commit -m hi")).toBe(false);
+    expect(isAllowed("npm install lodash")).toBe(false);
+    expect(isAllowed("rm -rf dist")).toBe(false);
+    expect(isAllowed("curl http://example.com")).toBe(false);
+  });
+
+  it("accepts test-runner commands", () => {
+    expect(isAllowed("pytest tests/")).toBe(true);
+    expect(isAllowed("cargo test --release")).toBe(true);
+    expect(isAllowed("npm test")).toBe(true);
+  });
+
+  it("respects extra allowed prefixes", () => {
+    expect(isAllowed("my-lint src/")).toBe(false);
+    expect(isAllowed("my-lint src/", ["my-lint"])).toBe(true);
+  });
+});
+
+describe("runCommand", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "reasonix-shell-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("captures stdout and reports exit 0 on success", async () => {
+    // `node -e '...'` is cross-platform; avoids cmd/bash differences.
+    const r = await runCommand("node -e \"process.stdout.write('hello')\"", { cwd: tmp });
+    expect(r.exitCode).toBe(0);
+    expect(r.output).toContain("hello");
+    expect(r.timedOut).toBe(false);
+  });
+
+  it("captures stderr and reports non-zero exit on failure", async () => {
+    const r = await runCommand("node -e \"process.stderr.write('oops'); process.exit(2)\"", {
+      cwd: tmp,
+    });
+    expect(r.exitCode).toBe(2);
+    expect(r.output).toContain("oops");
+  });
+
+  it("runs inside the given cwd, not the test's cwd", async () => {
+    writeFileSync(join(tmp, "marker.txt"), "present");
+    const r = await runCommand(
+      "node -e \"const fs=require('fs');process.stdout.write(fs.readFileSync('marker.txt','utf8'))\"",
+      { cwd: tmp },
+    );
+    expect(r.output).toContain("present");
+  });
+
+  it("kills a command that exceeds the timeout", async () => {
+    // Sleep longer than timeout; 500ms sleep, 100ms timeout.
+    const r = await runCommand('node -e "setTimeout(()=>{},5000)"', {
+      cwd: tmp,
+      timeoutSec: 0.1 as unknown as number, // cast: the function accepts seconds; 0.1s = 100ms
+    });
+    expect(r.timedOut).toBe(true);
+  });
+
+  it("truncates long output with a marker", async () => {
+    const r = await runCommand("node -e \"process.stdout.write('x'.repeat(50000))\"", {
+      cwd: tmp,
+      maxOutputChars: 1000,
+    });
+    expect(r.output).toMatch(/\[… truncated \d+ chars …\]$/);
+  });
+
+  it("rejects empty commands", async () => {
+    await expect(runCommand("", { cwd: tmp })).rejects.toThrow(/empty command/);
+  });
+
+  it("rejects commands with unclosed quotes", async () => {
+    await expect(runCommand('echo "unclosed', { cwd: tmp })).rejects.toThrow(/unclosed/);
+  });
+});
+
+describe("registerShellTools — dispatch integration", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "reasonix-shell-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("registers run_command", () => {
+    const registry = new ToolRegistry();
+    registerShellTools(registry, { rootDir: tmp });
+    expect(registry.size).toBe(1);
+  });
+
+  it("auto-runs allowlisted commands and returns formatted output", async () => {
+    const registry = new ToolRegistry();
+    registerShellTools(registry, { rootDir: tmp, extraAllowed: ["node"] });
+    const out = await registry.dispatch(
+      "run_command",
+      JSON.stringify({ command: "node --version" }),
+    );
+    expect(out).toMatch(/\$ node --version/);
+    expect(out).toMatch(/\[exit 0\]/);
+  });
+
+  it("refuses non-allowlisted commands with NeedsConfirmationError", async () => {
+    const registry = new ToolRegistry();
+    registerShellTools(registry, { rootDir: tmp });
+    const out = await registry.dispatch(
+      "run_command",
+      JSON.stringify({ command: "rm -rf node_modules" }),
+    );
+    expect(out).toMatch(/NeedsConfirmationError/);
+    expect(out).toMatch(/rm -rf node_modules/);
+  });
+
+  it("allowAll:true bypasses the allowlist entirely", async () => {
+    const registry = new ToolRegistry();
+    registerShellTools(registry, { rootDir: tmp, allowAll: true, extraAllowed: [] });
+    const out = await registry.dispatch(
+      "run_command",
+      JSON.stringify({ command: "node -e \"process.stdout.write('ok')\"" }),
+    );
+    expect(out).toMatch(/\[exit 0\]/);
+    expect(out).toContain("ok");
+  });
+
+  it("extraAllowed as a getter is re-read on every dispatch", async () => {
+    // Regression: picking "always allow" in ShellConfirm wrote to disk
+    // but the running run_command captured a stale snapshot, so the
+    // same command got re-prompted until the next launch. Getter form
+    // fixes this by re-resolving the allowlist on each call.
+    //
+    // `node -e` is deliberately NOT in BUILTIN_ALLOWLIST — only
+    // `node --version` / `node -v` are — so the "before" call must go
+    // through the extraAllowed path to succeed.
+    const cmd = "node -e \"process.stdout.write('ok')\"";
+    const registry = new ToolRegistry();
+    const list: string[] = [];
+    registerShellTools(registry, { rootDir: tmp, extraAllowed: () => list });
+
+    const before = await registry.dispatch("run_command", JSON.stringify({ command: cmd }));
+    expect(before).toMatch(/NeedsConfirmationError/);
+
+    // Simulate the TUI's "always allow" click — mutate the source the
+    // getter reads. No re-registration; the live tool instance picks
+    // it up.
+    list.push("node -e");
+
+    const after = await registry.dispatch("run_command", JSON.stringify({ command: cmd }));
+    expect(after).not.toMatch(/NeedsConfirmationError/);
+    expect(after).toMatch(/\[exit 0\]/);
+    expect(after).toContain("ok");
+  });
+});
+
+describe("formatCommandResult", () => {
+  it("marks the exit code on success", () => {
+    expect(formatCommandResult("ls", { exitCode: 0, output: "a\nb", timedOut: false })).toBe(
+      "$ ls\n[exit 0]\na\nb",
+    );
+  });
+
+  it("marks a killed-on-timeout run", () => {
+    expect(formatCommandResult("sleep 10", { exitCode: null, output: "", timedOut: true })).toBe(
+      "$ sleep 10\n[killed after timeout]",
+    );
+  });
+
+  it("elides the body when output is empty", () => {
+    expect(formatCommandResult("true", { exitCode: 0, output: "", timedOut: false })).toBe(
+      "$ true\n[exit 0]",
+    );
+  });
+});
+
+describe("resolveExecutable", () => {
+  it("returns the input unchanged on non-Windows platforms", () => {
+    expect(resolveExecutable("npm", { platform: "linux" })).toBe("npm");
+    expect(resolveExecutable("pytest", { platform: "darwin" })).toBe("pytest");
+  });
+
+  it("returns empty input unchanged", () => {
+    expect(resolveExecutable("", { platform: "win32" })).toBe("");
+  });
+
+  it("walks PATH × PATHEXT on Windows and returns the first hit", () => {
+    // PATHEXT case is preserved into the joined path, so the mock
+    // "filesystem" keys must match that case verbatim.
+    const hits = new Set(["C:\\tools\\npm.CMD"]);
+    const out = resolveExecutable("npm", {
+      platform: "win32",
+      env: { PATH: "C:\\nope;C:\\tools", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out).toBe("C:\\tools\\npm.CMD");
+  });
+
+  it("honors PATHEXT ordering (.EXE beats .CMD when both exist)", () => {
+    const hits = new Set(["C:\\bin\\foo.EXE", "C:\\bin\\foo.CMD"]);
+    const out = resolveExecutable("foo", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".EXE;.CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out).toBe("C:\\bin\\foo.EXE");
+  });
+
+  it("falls back to the raw cmd when PATH × PATHEXT yields nothing", () => {
+    const out = resolveExecutable("doesnotexist", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".EXE" },
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out).toBe("doesnotexist");
+  });
+
+  it("skips lookup for absolute paths (\\ or /)", () => {
+    const called: string[] = [];
+    const out1 = resolveExecutable("C:\\tools\\npm.cmd", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".CMD" },
+      isFile: (p) => {
+        called.push(p);
+        return true;
+      },
+    });
+    expect(out1).toBe("C:\\tools\\npm.cmd");
+    const out2 = resolveExecutable("src/tool.js", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".CMD" },
+      isFile: () => true,
+    });
+    expect(out2).toBe("src/tool.js");
+    expect(called).toEqual([]);
+  });
+
+  it("skips lookup when the cmd already has an extension", () => {
+    const called: string[] = [];
+    const out = resolveExecutable("npm.cmd", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".CMD" },
+      isFile: (p) => {
+        called.push(p);
+        return true;
+      },
+    });
+    expect(out).toBe("npm.cmd");
+    expect(called).toEqual([]);
+  });
+
+  it("tolerates missing PATH / PATHEXT — returns cmd unchanged", () => {
+    const out = resolveExecutable("npm", {
+      platform: "win32",
+      env: {},
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out).toBe("npm");
+  });
+
+  it("handles whitespace inside PATHEXT entries (' .CMD ' → '.CMD')", () => {
+    const hits = new Set(["C:\\bin\\npm.CMD"]);
+    const out = resolveExecutable("npm", {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: " .CMD ; .EXE " },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out).toBe("C:\\bin\\npm.CMD");
+  });
+});
+
+describe("quoteForCmdExe", () => {
+  it("leaves simple identifiers alone", () => {
+    expect(quoteForCmdExe("install")).toBe("install");
+    expect(quoteForCmdExe("foo-bar_123")).toBe("foo-bar_123");
+  });
+
+  it("double-quotes whitespace and cmd metacharacters", () => {
+    expect(quoteForCmdExe("hello world")).toBe('"hello world"');
+    expect(quoteForCmdExe("a&b")).toBe('"a&b"');
+    expect(quoteForCmdExe("a|b")).toBe('"a|b"');
+    expect(quoteForCmdExe("a>b")).toBe('"a>b"');
+    expect(quoteForCmdExe("a<b")).toBe('"a<b"');
+    expect(quoteForCmdExe("a^b")).toBe('"a^b"');
+    expect(quoteForCmdExe("a;b")).toBe('"a;b"');
+  });
+
+  it("doubles embedded quotes (cmd.exe escape rule)", () => {
+    expect(quoteForCmdExe('say "hi"')).toBe('"say ""hi"""');
+  });
+
+  it("empty string becomes an explicit empty-pair", () => {
+    expect(quoteForCmdExe("")).toBe('""');
+  });
+
+  it("round-trips `npm install foo` safely", () => {
+    const argv = ["C:\\Program Files\\nodejs\\npm.cmd", "install", "foo"];
+    const cmdline = argv.map(quoteForCmdExe).join(" ");
+    expect(cmdline).toBe('"C:\\Program Files\\nodejs\\npm.cmd" install foo');
+  });
+});
+
+describe("prepareSpawn", () => {
+  it("passes through unchanged on non-Windows", () => {
+    const out = prepareSpawn(["npm", "install"], { platform: "linux" });
+    expect(out.bin).toBe("npm");
+    expect(out.args).toEqual(["install"]);
+    expect(out.spawnOverrides).toEqual({});
+  });
+
+  it("wraps .cmd files through cmd.exe on Windows (post-CVE-2024-27980)", () => {
+    // Real-world install path with a space → quoting required.
+    const hits = new Set(["C:\\Program Files\\nodejs\\npm.CMD"]);
+    const out = prepareSpawn(["npm", "install", "foo"], {
+      platform: "win32",
+      env: { PATH: "C:\\Program Files\\nodejs", PATHEXT: ".EXE;.CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out.bin).toBe("cmd.exe");
+    expect(out.args).toEqual([
+      "/d",
+      "/s",
+      "/c",
+      'chcp 65001 >nul & "C:\\Program Files\\nodejs\\npm.CMD" install foo',
+    ]);
+    expect(out.spawnOverrides.windowsVerbatimArguments).toBe(true);
+  });
+
+  it("wraps .cmd files without quoting when the resolved path has no metacharacters", () => {
+    const hits = new Set(["C:\\tools\\npm.CMD"]);
+    const out = prepareSpawn(["npm", "install"], {
+      platform: "win32",
+      env: { PATH: "C:\\tools", PATHEXT: ".EXE;.CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    // No spaces in the path ⇒ no surrounding quotes; cmd.exe parses
+    // backslashes literally. UTF-8 codepage prefix is always inserted.
+    expect(out.args[3]).toBe("chcp 65001 >nul & C:\\tools\\npm.CMD install");
+  });
+
+  it("wraps .bat files too", () => {
+    const hits = new Set(["C:\\bin\\gradle.BAT"]);
+    const out = prepareSpawn(["gradle", "build"], {
+      platform: "win32",
+      env: { PATH: "C:\\bin", PATHEXT: ".BAT" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out.bin).toBe("cmd.exe");
+    expect(out.args[3]).toMatch(/^chcp 65001 >nul & .*gradle\.BAT/);
+  });
+
+  it("spawns .exe directly (no cmd.exe wrapping)", () => {
+    const hits = new Set(["C:\\Program Files\\nodejs\\node.EXE"]);
+    const out = prepareSpawn(["node", "--version"], {
+      platform: "win32",
+      env: { PATH: "C:\\Program Files\\nodejs", PATHEXT: ".EXE;.CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out.bin).toBe("C:\\Program Files\\nodejs\\node.EXE");
+    expect(out.args).toEqual(["--version"]);
+    expect(out.spawnOverrides).toEqual({});
+  });
+
+  it("cmd.exe-wrapping quotes args containing metacharacters", () => {
+    const hits = new Set(["C:\\tools\\tool.CMD"]);
+    const out = prepareSpawn(["tool", "a&b", "c|d"], {
+      platform: "win32",
+      env: { PATH: "C:\\tools", PATHEXT: ".CMD" },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out.args[3]).toBe('chcp 65001 >nul & C:\\tools\\tool.CMD "a&b" "c|d"');
+  });
+
+  it("routes bare unresolved Windows commands through cmd.exe (builtins)", () => {
+    // `dir`, `echo`, `type`, `ver`, … are cmd.exe built-ins — they
+    // don't exist as standalone exes, so PATHEXT lookup misses and a
+    // direct spawn ENOENTs. Wrapping in cmd.exe lets them resolve,
+    // and gives unknown commands a proper "'x' is not recognized"
+    // exit code instead of a raw spawn failure.
+    const out = prepareSpawn(["dir", ".reasonix"], {
+      platform: "win32",
+      env: { PATH: "C:\\nope", PATHEXT: ".EXE" },
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out.bin).toBe("cmd.exe");
+    expect(out.args).toEqual(["/d", "/s", "/c", "chcp 65001 >nul & dir .reasonix"]);
+    expect(out.spawnOverrides.windowsVerbatimArguments).toBe(true);
+  });
+
+  it("cmd.exe builtin wrapping quotes metacharacter args", () => {
+    const out = prepareSpawn(["echo", "a & b"], {
+      platform: "win32",
+      env: { PATH: "C:\\nope", PATHEXT: ".EXE" },
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out.bin).toBe("cmd.exe");
+    expect(out.args[3]).toBe('chcp 65001 >nul & echo "a & b"');
+  });
+
+  it("does not wrap paths-with-separators through cmd.exe", () => {
+    // Absolute or slash-containing inputs are NOT bare names; they're
+    // explicit disk paths — if the user points at a nonexistent one
+    // we want the spawn to ENOENT plainly, not through cmd.exe.
+    const out = prepareSpawn(["C:\\missing\\tool.exe", "arg"], {
+      platform: "win32",
+      env: { PATH: "", PATHEXT: ".EXE" },
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out.bin).toBe("C:\\missing\\tool.exe");
+    expect(out.args).toEqual(["arg"]);
+  });
+
+  it("injects UTF-8 prelude into powershell -Command invocations", () => {
+    // Uppercase .EXE in the hit set so resolveExecutable's PATHEXT
+    // probe finds it (matches existing .CMD test convention).
+    const hits = new Set(["C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.EXE"]);
+    const out = prepareSpawn(["powershell", "-Command", "Get-ChildItem -Path tests"], {
+      platform: "win32",
+      env: {
+        PATH: "C:\\Windows\\System32\\WindowsPowerShell\\v1.0",
+        PATHEXT: ".EXE",
+      },
+      pathDelimiter: ";",
+      isFile: (p) => hits.has(p),
+    });
+    expect(out.bin).toMatch(/powershell\.exe$/i);
+    // args = [-Command, "<prelude>Get-ChildItem -Path tests"]
+    expect(out.args[0]).toBe("-Command");
+    expect(out.args[1]).toMatch(/^\[Console\]::OutputEncoding=/);
+    expect(out.args[1]).toContain("Get-ChildItem -Path tests");
+    // No cmd.exe wrapping for powershell — direct spawn.
+    expect(out.spawnOverrides).toEqual({});
+  });
+
+  it("injectPowerShellUtf8 leaves unrelated invocations untouched", () => {
+    // No -Command flag → can't safely inject; we leave it alone.
+    expect(injectPowerShellUtf8(["-File", "script.ps1"])).toBeNull();
+    // -c (alias) still gets the prelude.
+    const out = injectPowerShellUtf8(["-c", "Write-Host hi"]);
+    expect(out).not.toBeNull();
+    expect(out![1]).toMatch(/^\[Console\]::OutputEncoding=.*Write-Host hi$/);
+  });
+
+  it("does not wrap already-extensioned commands", () => {
+    // `node.exe` with no PATH hit → user passed an explicit name;
+    // pass it straight to spawn (will ENOENT if truly absent).
+    const out = prepareSpawn(["node.exe", "-v"], {
+      platform: "win32",
+      env: { PATH: "", PATHEXT: ".EXE" },
+      pathDelimiter: ";",
+      isFile: () => false,
+    });
+    expect(out.bin).toBe("node.exe");
+    expect(out.args).toEqual(["-v"]);
+  });
+});
+
+describe("NeedsConfirmationError", () => {
+  it("carries the rejected command on the instance", () => {
+    const e = new NeedsConfirmationError("rm -rf /");
+    expect(e.command).toBe("rm -rf /");
+    expect(e.name).toBe("NeedsConfirmationError");
+    expect(e.message).toMatch(/rm -rf \//);
+  });
+
+  it("tells the model to stop and wait, not to retry", () => {
+    const e = new NeedsConfirmationError("npm install");
+    expect(e.message).toMatch(/STOP calling tools/i);
+    expect(e.message).toMatch(/y.*run.*n.*deny/i);
+    expect(e.message).not.toMatch(/apply-shell/);
+  });
+});

tests/skills.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Tests for the Skills store + prefix-index composer. Every test runs
+ * against a temp `homeDir` (global scope) and a temp `projectRoot`
+ * (project scope) so we never touch the developer's real skill dirs.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { SkillStore, applySkillsIndex } from "../src/skills.js";
+
+const BASE = "You are a test assistant.";
+
+type SkillRoot = "project" | "global";
+
+function writeSkillDir(
+  root: string,
+  which: SkillRoot,
+  name: string,
+  frontmatter: Record<string, string>,
+  body: string,
+  homeOrProject: string,
+): string {
+  const parent =
+    which === "global"
+      ? join(homeOrProject, ".reasonix", "skills")
+      : join(root, ".reasonix", "skills");
+  const dir = join(parent, name);
+  mkdirSync(dir, { recursive: true });
+  const fmLines = ["---"];
+  for (const [k, v] of Object.entries(frontmatter)) fmLines.push(`${k}: ${v}`);
+  fmLines.push("---", "");
+  const path = join(dir, "SKILL.md");
+  writeFileSync(path, `${fmLines.join("\n")}${body}\n`, "utf8");
+  return path;
+}
+
+function writeFlatSkill(
+  dir: string,
+  name: string,
+  frontmatter: Record<string, string>,
+  body: string,
+): string {
+  const skills = join(dir, ".reasonix", "skills");
+  mkdirSync(skills, { recursive: true });
+  const fmLines = ["---"];
+  for (const [k, v] of Object.entries(frontmatter)) fmLines.push(`${k}: ${v}`);
+  fmLines.push("---", "");
+  const path = join(skills, `${name}.md`);
+  writeFileSync(path, `${fmLines.join("\n")}${body}\n`, "utf8");
+  return path;
+}
+
+describe("SkillStore", () => {
+  let home: string;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-skills-home-"));
+    projectRoot = mkdtempSync(join(tmpdir(), "reasonix-skills-proj-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it("returns an empty list when no skill dirs exist", () => {
+    const store = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true });
+    expect(store.list()).toEqual([]);
+  });
+
+  it("hasProjectScope reflects constructor argument", () => {
+    expect(new SkillStore({ homeDir: home, disableBuiltins: true }).hasProjectScope()).toBe(false);
+    expect(
+      new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true }).hasProjectScope(),
+    ).toBe(true);
+  });
+
+  it("parses a SKILL.md dir-layout entry from the global scope", () => {
+    writeSkillDir(
+      projectRoot,
+      "global",
+      "review",
+      { name: "review", description: "Review a pull request" },
+      "Run `git diff` and summarize risks.",
+      home,
+    );
+    const skills = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true }).list();
+    expect(skills).toHaveLength(1);
+    expect(skills[0]?.name).toBe("review");
+    expect(skills[0]?.scope).toBe("global");
+    expect(skills[0]?.body).toContain("git diff");
+  });
+
+  it("reads flat <name>.md files as well", () => {
+    writeFlatSkill(home, "ship-it", { description: "Commit and push changes" }, "body");
+    const skills = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true }).list();
+    expect(skills.map((s) => s.name)).toEqual(["ship-it"]);
+    expect(skills[0]?.description).toBe("Commit and push changes");
+  });
+
+  it("surfaces project-scope skills from <projectRoot>/.reasonix/skills", () => {
+    writeSkillDir(
+      projectRoot,
+      "project",
+      "deploy",
+      { description: "Deploy to staging" },
+      "Run the staging pipeline.",
+      home,
+    );
+    const list = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true }).list();
+    expect(list).toHaveLength(1);
+    expect(list[0]?.scope).toBe("project");
+    expect(list[0]?.path).toContain(projectRoot);
+  });
+
+  it("project scope wins on a name collision with global", () => {
+    writeSkillDir(projectRoot, "global", "review", { description: "global one" }, "G", home);
+    writeSkillDir(projectRoot, "project", "review", { description: "project one" }, "P", home);
+    const store = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true });
+    const list = store.list();
+    expect(list).toHaveLength(1);
+    expect(list[0]?.scope).toBe("project");
+    expect(list[0]?.description).toBe("project one");
+    expect(store.read("review")?.body).toBe("P");
+  });
+
+  it("without projectRoot the store only reads the global scope", () => {
+    // Put a skill in the project dir and a skill in the global dir.
+    writeSkillDir(projectRoot, "project", "deploy", { description: "proj" }, "P", home);
+    writeSkillDir(projectRoot, "global", "review", { description: "glob" }, "G", home);
+    const store = new SkillStore({ homeDir: home, disableBuiltins: true }); // no projectRoot
+    const names = store.list().map((s) => s.name);
+    expect(names).toEqual(["review"]);
+    expect(store.hasProjectScope()).toBe(false);
+  });
+
+  it("rejects invalid skill names on read()", () => {
+    const store = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true });
+    expect(store.read("../etc/passwd")).toBeNull();
+    expect(store.read("foo/bar")).toBeNull();
+    expect(store.read("")).toBeNull();
+  });
+
+  it("skips dotfiles that would masquerade as skills", () => {
+    writeSkillDir(projectRoot, "global", "ok", { description: "fine" }, "body", home);
+    const dotDir = join(home, ".reasonix", "skills");
+    writeFileSync(join(dotDir, ".hidden.md"), "---\ndescription: x\n---\nbody\n", "utf8");
+    const list = new SkillStore({ homeDir: home, projectRoot, disableBuiltins: true }).list();
+    expect(list.map((s) => s.name)).toEqual(["ok"]);
+  });
+});
+
+describe("applySkillsIndex", () => {
+  let home: string;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-skills-idx-"));
+    projectRoot = mkdtempSync(join(tmpdir(), "reasonix-skills-idx-proj-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it("returns the prompt unchanged when no skills exist", () => {
+    const out = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(out).toBe(BASE);
+  });
+
+  it("emits a Skills section with one-liners but not bodies", () => {
+    writeSkillDir(
+      projectRoot,
+      "global",
+      "review",
+      { description: "Review a pull request" },
+      "BODY-THAT-MUST-NOT-APPEAR",
+      home,
+    );
+    writeSkillDir(
+      projectRoot,
+      "global",
+      "init",
+      { description: "Initialize a CLAUDE.md" },
+      "ALSO-SECRET",
+      home,
+    );
+    const out = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(out).toContain("# Skills");
+    expect(out).toContain("- init — Initialize a CLAUDE.md");
+    expect(out).toContain("- review — Review a pull request");
+    expect(out).not.toContain("BODY-THAT-MUST-NOT-APPEAR");
+    expect(out).not.toContain("ALSO-SECRET");
+  });
+
+  it("merges project + global skills into a single index", () => {
+    writeSkillDir(projectRoot, "global", "hello", { description: "global hello" }, "x", home);
+    writeSkillDir(projectRoot, "project", "deploy", { description: "project deploy" }, "y", home);
+    const out = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(out).toContain("- deploy — project deploy");
+    expect(out).toContain("- hello — global hello");
+  });
+
+  it("omits skills with blank descriptions from the pinned index", () => {
+    writeSkillDir(projectRoot, "global", "has-desc", { description: "I have one" }, "body", home);
+    writeSkillDir(projectRoot, "global", "no-desc", {}, "body", home);
+    const out = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(out).toContain("- has-desc —");
+    expect(out).not.toContain("- no-desc");
+  });
+
+  it("is byte-stable across two calls with the same filesystem state", () => {
+    writeSkillDir(projectRoot, "global", "a", { description: "one" }, "x", home);
+    writeSkillDir(projectRoot, "global", "b", { description: "two" }, "y", home);
+    const first = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    const second = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(first).toBe(second);
+  });
+
+  it("marks subagent-runAs skills with the 🧬 prefix in the index", () => {
+    writeSkillDir(
+      projectRoot,
+      "global",
+      "lookup",
+      { description: "Look something up", runAs: "subagent" },
+      "body",
+      home,
+    );
+    writeSkillDir(
+      projectRoot,
+      "global",
+      "fmt",
+      { description: "Format the codebase", runAs: "inline" },
+      "body",
+      home,
+    );
+    const out = applySkillsIndex(BASE, { homeDir: home, projectRoot, disableBuiltins: true });
+    expect(out).toContain("- 🧬 lookup — Look something up");
+    expect(out).toContain("- fmt — Format the codebase");
+    expect(out).not.toContain("- 🧬 fmt");
+  });
+});
+
+describe("Skill frontmatter — runAs", () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-skills-runas-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it("defaults runAs to inline when frontmatter omits it", () => {
+    writeSkillDir(home, "global", "plain", { description: "plain skill" }, "body", home);
+    const skill = new SkillStore({ homeDir: home, disableBuiltins: true }).read("plain");
+    expect(skill?.runAs).toBe("inline");
+  });
+
+  it("parses runAs: subagent from frontmatter", () => {
+    writeSkillDir(
+      home,
+      "global",
+      "deep",
+      { description: "deep dive", runAs: "subagent" },
+      "body",
+      home,
+    );
+    const skill = new SkillStore({ homeDir: home, disableBuiltins: true }).read("deep");
+    expect(skill?.runAs).toBe("subagent");
+  });
+
+  it("falls back to inline for any unknown runAs value", () => {
+    writeSkillDir(home, "global", "weird", { description: "?", runAs: "parallel" }, "body", home);
+    const skill = new SkillStore({ homeDir: home, disableBuiltins: true }).read("weird");
+    expect(skill?.runAs).toBe("inline");
+  });
+
+  it("captures a deepseek-* model override and ignores anything else", () => {
+    writeSkillDir(
+      home,
+      "global",
+      "rsr",
+      { description: "...", runAs: "subagent", model: "deepseek-reasoner" },
+      "body",
+      home,
+    );
+    writeSkillDir(
+      home,
+      "global",
+      "wrong",
+      { description: "...", runAs: "subagent", model: "gpt-4" },
+      "body",
+      home,
+    );
+    const store = new SkillStore({ homeDir: home, disableBuiltins: true });
+    expect(store.read("rsr")?.model).toBe("deepseek-reasoner");
+    expect(store.read("wrong")?.model).toBeUndefined();
+  });
+});
+
+describe("Built-in skills", () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-skills-builtins-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  it("ships explore + research as subagent-runAs builtins", () => {
+    const store = new SkillStore({ homeDir: home }); // builtins ON
+    const names = store.list().map((s) => s.name);
+    expect(names).toContain("explore");
+    expect(names).toContain("research");
+    const explore = store.read("explore");
+    expect(explore?.runAs).toBe("subagent");
+    expect(explore?.scope).toBe("builtin");
+    const research = store.read("research");
+    expect(research?.runAs).toBe("subagent");
+  });
+
+  it("user-authored skills override a builtin with the same name", () => {
+    writeSkillDir(home, "global", "explore", { description: "my own" }, "custom body", home);
+    const store = new SkillStore({ homeDir: home });
+    const explore = store.read("explore");
+    expect(explore?.scope).toBe("global");
+    expect(explore?.body).toBe("custom body");
+  });
+
+  it("disableBuiltins hides them entirely", () => {
+    const store = new SkillStore({ homeDir: home, disableBuiltins: true });
+    expect(store.read("explore")).toBeNull();
+    expect(store.list()).toEqual([]);
+  });
+
+  it("builtins surface with the 🧬 marker in applySkillsIndex", () => {
+    const out = applySkillsIndex(BASE, { homeDir: home }); // builtins ON
+    expect(out).toContain("# Skills");
+    expect(out).toContain("🧬 explore");
+    expect(out).toContain("🧬 research");
+  });
+});

tests/slash.test.ts

@@ -1,6 +1,10 @@
-import { describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   SLASH_COMMANDS,
+  detectSlashArgContext,
   handleSlash,
   parseSlash,
   suggestSlashCommands,
@@ -8,6 +12,7 @@ import {
 import { DeepSeekClient, Usage } from "../src/client.js";
 import { CacheFirstLoop } from "../src/loop.js";
 import { ImmutablePrefix } from "../src/memory.js";
+import { VERSION } from "../src/version.js";
 
 function makeLoop() {
   const client = new DeepSeekClient({
@@ -99,6 +104,43 @@ describe("handleSlash", () => {
     expect(loop.model).toBe("deepseek-reasoner");
   });
 
+  it("/model soft-warns when id is not in the fetched catalog but still switches", () => {
+    const loop = makeLoop();
+    const r = handleSlash("model", ["deepseek-made-up"], loop, {
+      models: ["deepseek-chat", "deepseek-reasoner"],
+    });
+    expect(loop.model).toBe("deepseek-made-up");
+    expect(r.info).toMatch(/not in the fetched catalog/);
+    expect(r.info).toMatch(/\/models/);
+  });
+
+  it("/model with no arg and loaded list hints at available ids", () => {
+    const loop = makeLoop();
+    const r = handleSlash("model", [], loop, {
+      models: ["deepseek-chat", "deepseek-reasoner"],
+    });
+    expect(r.info).toMatch(/deepseek-chat \| deepseek-reasoner/);
+  });
+
+  it("/models renders the fetched catalog and marks the current one", () => {
+    const loop = makeLoop();
+    loop.configure({ model: "deepseek-reasoner" });
+    const r = handleSlash("models", [], loop, {
+      models: ["deepseek-chat", "deepseek-reasoner"],
+    });
+    expect(r.info).toMatch(/deepseek-chat/);
+    expect(r.info).toMatch(/▸ deepseek-reasoner\s+\(current\)/);
+    expect(r.info).toMatch(/\/model <id>/);
+  });
+
+  it("/models triggers a refresh and reports fetching when the list hasn't loaded yet", () => {
+    const loop = makeLoop();
+    const refresh = vi.fn();
+    const r = handleSlash("models", [], loop, { models: null, refreshModels: refresh });
+    expect(refresh).toHaveBeenCalledOnce();
+    expect(r.info).toMatch(/fetching \/models/);
+  });
+
   it("/harvest on/off toggles", () => {
     const loop = makeLoop();
     handleSlash("harvest", ["on"], loop);
@@ -185,29 +227,43 @@ describe("handleSlash", () => {
     loop.log.append({ role: "tool", tool_call_id: "t1", content: "short result" });
     const r = handleSlash("compact", [], loop);
     expect(r.info).toMatch(/nothing to compact/);
+    expect(r.info).toMatch(/tokens/);
   });
 
-  it("/compact shrinks oversized tool results and reports chars saved", () => {
+  it("/compact shrinks oversized tool results and reports tokens saved", () => {
     const loop = makeLoop();
     loop.log.append({ role: "user", content: "read a big file" });
-    loop.log.append({ role: "tool", tool_call_id: "t1", content: "Z".repeat(20_000) });
+    // Realistic log-shape content — avoids the BPE O(n²) pathological
+    // path on pure-repeat inputs while still tokenizing well over the
+    // default 4000-token cap.
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "t1",
+      content: "ERROR: line failed with detail and context\n".repeat(2000),
+    });
     const r = handleSlash("compact", [], loop);
     expect(r.info).toMatch(/compacted 1 tool result/);
-    expect(r.info).toMatch(/saved/);
-    // After compaction the tool message length should be below the default 4k cap + envelope.
+    expect(r.info).toMatch(/saved [\d,]+ tokens/);
+    // After compaction the tool content should be much smaller than
+    // the original 84KB, comfortably under the cap's char worst-case.
     const toolEntry = loop.log.entries.find((m) => m.role === "tool");
     expect(typeof toolEntry?.content).toBe("string");
-    expect((toolEntry?.content as string).length).toBeLessThan(5_000);
+    expect((toolEntry?.content as string).length).toBeLessThan(20_000);
   });
 
-  it("/compact honors a custom cap argument", () => {
+  it("/compact honors a custom token cap argument", () => {
     const loop = makeLoop();
-    loop.log.append({ role: "tool", tool_call_id: "t1", content: "A".repeat(10_000) });
-    // 2000-char cap should shrink the 10k message
-    const r = handleSlash("compact", ["2000"], loop);
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "t1",
+      content: "INFO: event ok\n".repeat(1500),
+    });
+    // 500-token cap should shrink the message hard.
+    const r = handleSlash("compact", ["500"], loop);
     expect(r.info).toMatch(/compacted 1/);
+    expect(r.info).toMatch(/500 tokens each/);
     const toolEntry = loop.log.entries.find((m) => m.role === "tool");
-    expect((toolEntry?.content as string).length).toBeLessThan(2_500);
+    expect((toolEntry?.content as string).length).toBeLessThan(3_000);
   });
 
   it("/help mentions /compact", () => {
@@ -445,6 +501,111 @@ describe("handleSlash", () => {
     expect(r.info).toMatch(/\/tool/);
   });
 
+  describe("/keys", () => {
+    it("lists the major keyboard shortcuts", () => {
+      const r = handleSlash("keys", [], makeLoop());
+      expect(r.info).toMatch(/Enter\s+submit/);
+      expect(r.info).toMatch(/Shift\+Enter/);
+      expect(r.info).toMatch(/Ctrl\+J/);
+      expect(r.info).toMatch(/Esc\s+abort/);
+    });
+
+    it("documents the three prompt prefixes", () => {
+      const r = handleSlash("keys", [], makeLoop());
+      expect(r.info).toMatch(/\/<name>/);
+      expect(r.info).toMatch(/@<path>/);
+      expect(r.info).toMatch(/!<cmd>/);
+    });
+
+    it("mentions the pickers", () => {
+      const r = handleSlash("keys", [], makeLoop());
+      expect(r.info).toMatch(/[Pp]icker/);
+      expect(r.info).toMatch(/Tab/);
+    });
+  });
+
+  it("/help mentions /keys", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/keys/);
+  });
+
+  describe("detectSlashArgContext", () => {
+    it("returns null before the user commits to a slash name", () => {
+      expect(detectSlashArgContext("/pr")).toBeNull();
+      expect(detectSlashArgContext("/preset")).toBeNull();
+    });
+
+    it("returns null when the command doesn't exist", () => {
+      expect(detectSlashArgContext("/nope foo")).toBeNull();
+    });
+
+    it("returns null on plain prose (no slash at all)", () => {
+      expect(detectSlashArgContext("just some text")).toBeNull();
+    });
+
+    it("activates enum picker for /preset", () => {
+      const ctx = detectSlashArgContext("/preset fa");
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("picker");
+      expect(ctx!.spec.argCompleter).toEqual(["fast", "smart", "max"]);
+      expect(ctx!.partial).toBe("fa");
+      // Offset is the char index where the partial starts in the buffer.
+      expect(ctx!.partialOffset).toBe("/preset ".length);
+    });
+
+    it("activates model picker for /model", () => {
+      const ctx = detectSlashArgContext("/model deep");
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("picker");
+      expect(ctx!.spec.argCompleter).toBe("models");
+    });
+
+    it("activates enum picker for /plan in code mode", () => {
+      const ctx = detectSlashArgContext("/plan o", true);
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("picker");
+      expect(ctx!.spec.argCompleter).toEqual(["on", "off"]);
+    });
+
+    it("hides /plan outside code mode (command is contextual)", () => {
+      expect(detectSlashArgContext("/plan on", false)).toBeNull();
+    });
+
+    it("surfaces a hint-only row once the user types a space inside the partial", () => {
+      // "/preset fast foo" — typed past the one enum slot.
+      const ctx = detectSlashArgContext("/preset fast foo");
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("hint");
+    });
+
+    it("returns picker with empty partial when the user just hit space", () => {
+      const ctx = detectSlashArgContext("/preset ");
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("picker");
+      expect(ctx!.partial).toBe("");
+    });
+
+    it("returns hint for commands without a completer", () => {
+      // `/commit "msg"` — free-form argument, no picker data.
+      const ctx = detectSlashArgContext('/commit "', true);
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("hint");
+      expect(ctx!.spec.cmd).toBe("commit");
+    });
+
+    it("still surfaces picker kind when partial exactly matches an enum value", () => {
+      // Detector itself is kind-only — it doesn't know whether the
+      // partial is a complete match. The App's slashArgMatches memo
+      // is responsible for hiding the picker on exact match so Enter
+      // submits; this test documents that the detector's contract is
+      // "we're in picker mode" regardless of match state.
+      const ctx = detectSlashArgContext("/preset smart");
+      expect(ctx).not.toBeNull();
+      expect(ctx!.kind).toBe("picker");
+      expect(ctx!.partial).toBe("smart");
+    });
+  });
+
   it("SLASH_COMMANDS registry contains every handler switch case", () => {
     // Spot-check a handful so the registry doesn't silently drift
     // from `handleSlash`. If a new case lands in handleSlash, it
@@ -459,6 +620,7 @@ describe("handleSlash", () => {
       "branch",
       "mcp",
       "tool",
+      "memory",
       "think",
       "retry",
       "compact",
@@ -469,19 +631,64 @@ describe("handleSlash", () => {
       "discard",
       "undo",
       "commit",
+      "plan",
+      "apply-plan",
+      "keys",
     ]) {
       expect(names, `registry missing /${required}`).toContain(required);
     }
   });
 
   it("suggestSlashCommands filters by prefix", () => {
-    expect(suggestSlashCommands("h").map((s) => s.cmd)).toEqual(["help", "harvest"]);
+    expect(suggestSlashCommands("h").map((s) => s.cmd)).toEqual(["help", "harvest", "hooks"]);
     // Case-insensitive.
     expect(suggestSlashCommands("HE").map((s) => s.cmd)).toEqual(["help"]);
     // Empty prefix returns everything (non-contextual).
     expect(suggestSlashCommands("").length).toBeGreaterThan(5);
   });
 
+  describe("/update", () => {
+    it("reports pending check when latestVersion is null (offline / in flight)", () => {
+      const r = handleSlash("update", [], makeLoop(), { latestVersion: null });
+      expect(r.info).toMatch(/current: reasonix/);
+      expect(r.info).toMatch(/not yet resolved/);
+      expect(r.info).toMatch(/reasonix update/);
+    });
+
+    it("reports up-to-date when current matches latest", () => {
+      const r = handleSlash("update", [], makeLoop(), { latestVersion: VERSION });
+      expect(r.info).toMatch(/on the latest/);
+      expect(r.info).not.toMatch(/npm install/);
+    });
+
+    it("prints shell command when latest is newer than current", () => {
+      const r = handleSlash("update", [], makeLoop(), { latestVersion: "99.99.99" });
+      expect(r.info).toMatch(/99\.99\.99/);
+      expect(r.info).toMatch(/reasonix update/);
+      expect(r.info).toMatch(/npm install -g reasonix@latest/);
+    });
+
+    it("is surfaced by suggestSlashCommands", () => {
+      const names = suggestSlashCommands("up").map((s) => s.cmd);
+      expect(names).toContain("update");
+    });
+  });
+
+  describe("/stats", () => {
+    it("prints a how-to when the usage log is empty / missing", () => {
+      // Use the real ~ here — if a real log exists (developer machine),
+      // this test would see real data. We assert only on a substring
+      // that's present either way: the path is always mentioned.
+      const r = handleSlash("stats", [], makeLoop());
+      expect(r.info).toMatch(/usage\.jsonl|turns/);
+    });
+
+    it("is surfaced by suggestSlashCommands", () => {
+      const names = suggestSlashCommands("sta").map((s) => s.cmd);
+      expect(names).toContain("stats");
+    });
+  });
+
   it("suggestSlashCommands hides code-mode-only entries when codeMode=false", () => {
     const names = suggestSlashCommands("", false).map((s) => s.cmd);
     expect(names).not.toContain("apply");
@@ -543,12 +750,52 @@ describe("handleSlash", () => {
       pendingEditCount: 3,
     });
     expect(r.info).toMatch(/model\s+deepseek-/);
-    expect(r.info).toMatch(/ctx\s+\d+\.?\d*k?\/\d+k/);
+    expect(r.info).toMatch(/ctx\s+\d+\.?\d*K?\/\d+K/);
     expect(r.info).toMatch(/mcp\s+2 server\(s\)/);
     expect(r.info).toMatch(/session.*\(ephemeral|session\s+"/);
     expect(r.info).toMatch(/edits\s+3 pending/);
   });
 
+  it("/context breaks down tokens across system / tools / log, and flags the heaviest tool results", () => {
+    const loop = makeLoop();
+    // Seed a realistic log: two turns, one with a large tool result.
+    loop.log.append({ role: "user", content: "list me the files" });
+    loop.log.append({
+      role: "assistant",
+      content: "",
+      tool_calls: [
+        {
+          id: "c1",
+          type: "function",
+          function: { name: "list_directory", arguments: '{"path":"."}' },
+        },
+      ],
+    });
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "c1",
+      name: "list_directory",
+      content: "README.md\npackage.json\nsrc/\n".repeat(200),
+    });
+    loop.log.append({ role: "assistant", content: "here are the files" });
+    loop.log.append({ role: "user", content: "now read package.json" });
+
+    const r = handleSlash("context", [], loop);
+    expect(r.info).toMatch(/Next-request estimate/);
+    expect(r.info).toMatch(/system prompt/);
+    expect(r.info).toMatch(/tool specs/);
+    expect(r.info).toMatch(/log \(all turns\)/);
+    // Heaviest-tool section must surface the list_directory result.
+    expect(r.info).toMatch(/Top tool results/);
+    expect(r.info).toMatch(/list_directory/);
+  });
+
+  it("/context handles an empty log without crashing", () => {
+    const r = handleSlash("context", [], makeLoop());
+    expect(r.info).toMatch(/Next-request estimate/);
+    expect(r.info).not.toMatch(/Top tool results/);
+  });
+
   it("/status with pendingEditCount=0 hides the edits line", () => {
     const r = handleSlash("status", [], makeLoop(), { pendingEditCount: 0 });
     expect(r.info).not.toMatch(/pending/);
@@ -578,4 +825,148 @@ describe("handleSlash", () => {
     const r = handleSlash("forget", [], loop);
     expect(r.info).toMatch(/nothing to forget/);
   });
+
+  describe("/memory", () => {
+    let root: string;
+    const originalEnv = process.env.REASONIX_MEMORY;
+
+    beforeEach(() => {
+      root = mkdtempSync(join(tmpdir(), "reasonix-mem-slash-"));
+      // biome-ignore lint/performance/noDelete: avoid "undefined" in env
+      delete process.env.REASONIX_MEMORY;
+    });
+    afterEach(() => {
+      rmSync(root, { recursive: true, force: true });
+      if (originalEnv === undefined) {
+        // biome-ignore lint/performance/noDelete: same reason
+        delete process.env.REASONIX_MEMORY;
+      } else {
+        process.env.REASONIX_MEMORY = originalEnv;
+      }
+    });
+
+    it("prints a how-to when no memory (REASONIX.md or ~/.reasonix/memory) exists", () => {
+      const r = handleSlash("memory", [], makeLoop(), { memoryRoot: root });
+      expect(r.info).toMatch(/no memory pinned/);
+      expect(r.info).toMatch(/REASONIX\.md/);
+    });
+
+    it("prints the REASONIX.md contents + path when present", () => {
+      writeFileSync(
+        join(root, "REASONIX.md"),
+        "# House rules\nSnake case only in this repo.\n",
+        "utf8",
+      );
+      const r = handleSlash("memory", [], makeLoop(), { memoryRoot: root });
+      expect(r.info).toMatch(/▸ REASONIX\.md:/);
+      expect(r.info).toContain("Snake case only");
+      expect(r.info).toMatch(/chars/);
+    });
+
+    it("says memory is disabled when REASONIX_MEMORY=off, even with a file present", () => {
+      writeFileSync(join(root, "REASONIX.md"), "content", "utf8");
+      process.env.REASONIX_MEMORY = "off";
+      const r = handleSlash("memory", [], makeLoop(), { memoryRoot: root });
+      expect(r.info).toMatch(/memory is disabled/);
+    });
+
+    it("refuses to guess a root when memoryRoot is absent", () => {
+      const r = handleSlash("memory", [], makeLoop());
+      expect(r.info).toMatch(/no working directory/);
+    });
+  });
+
+  describe("/plan + /apply-plan", () => {
+    it("/plan replies 'only in code mode' when setPlanMode callback is missing", () => {
+      const r = handleSlash("plan", [], makeLoop());
+      expect(r.info).toMatch(/only available inside `reasonix code`/);
+    });
+
+    it("/plan toggles when called with no args", () => {
+      const calls: boolean[] = [];
+      const r1 = handleSlash("plan", [], makeLoop(), {
+        planMode: false,
+        setPlanMode: (on) => calls.push(on),
+      });
+      expect(calls).toEqual([true]);
+      expect(r1.info).toMatch(/plan mode ON/);
+
+      const r2 = handleSlash("plan", [], makeLoop(), {
+        planMode: true,
+        setPlanMode: (on) => calls.push(on),
+      });
+      expect(calls).toEqual([true, false]);
+      expect(r2.info).toMatch(/plan mode OFF/);
+    });
+
+    it("/plan on / off / true / false / 0 / 1 parse correctly", () => {
+      const check = (arg: string, expected: boolean) => {
+        const calls: boolean[] = [];
+        handleSlash("plan", [arg], makeLoop(), {
+          planMode: !expected, // start from the opposite
+          setPlanMode: (on) => calls.push(on),
+        });
+        expect(calls, `arg=${arg}`).toEqual([expected]);
+      };
+      check("on", true);
+      check("true", true);
+      check("1", true);
+      check("off", false);
+      check("false", false);
+      check("0", false);
+    });
+
+    it("/plan explains the stronger-constraint relationship with autonomous submit_plan", () => {
+      const r = handleSlash("plan", ["on"], makeLoop(), {
+        setPlanMode: () => {},
+        planMode: false,
+      });
+      // The info text should be explicit that submit_plan can also fire
+      // outside plan mode (autonomous) — plan mode is the *stronger*
+      // constraint, not the only path.
+      expect(r.info).toMatch(/stronger/);
+      expect(r.info).toMatch(/submit_plan/);
+    });
+
+    it("/apply-plan replies 'only in code mode' when setPlanMode is missing", () => {
+      const r = handleSlash("apply-plan", [], makeLoop());
+      expect(r.info).toMatch(/only available inside `reasonix code`/);
+    });
+
+    it("/apply-plan flips plan mode off, clears pending, and resubmits the implement-now synthetic", () => {
+      const setCalls: boolean[] = [];
+      const clearCalls: number[] = [];
+      const r = handleSlash("apply-plan", [], makeLoop(), {
+        setPlanMode: (on) => setCalls.push(on),
+        clearPendingPlan: () => {
+          clearCalls.push(1);
+        },
+      });
+      expect(setCalls).toEqual([false]);
+      expect(clearCalls).toEqual([1]);
+      expect(r.info).toMatch(/plan approved/);
+      expect(r.resubmit).toMatch(/Implement it now/);
+      expect(r.resubmit).toMatch(/out of plan mode/);
+    });
+
+    it("/apply-plan works without a clearPendingPlan callback (only setPlanMode required)", () => {
+      const setCalls: boolean[] = [];
+      const r = handleSlash("apply-plan", [], makeLoop(), {
+        setPlanMode: (on) => setCalls.push(on),
+        // clearPendingPlan omitted — /apply-plan must still work
+      });
+      expect(setCalls).toEqual([false]);
+      expect(r.resubmit).toMatch(/Implement it now/);
+    });
+
+    it("/status surfaces plan mode when it's on", () => {
+      const r = handleSlash("status", [], makeLoop(), { planMode: true });
+      expect(r.info).toMatch(/plan\s+ON/);
+    });
+
+    it("/status hides the plan line when plan mode is off", () => {
+      const r = handleSlash("status", [], makeLoop(), { planMode: false });
+      expect(r.info).not.toMatch(/plan\s+ON/);
+    });
+  });
 });

tests/subagent.test.ts

@@ -0,0 +1,373 @@
+/**
+ * Subagent tool — registration, child-loop isolation, fork-registry
+ * exclusion rules, error path, abort propagation, plan-mode inheritance.
+ *
+ * The DeepSeek client is faked so we never hit the network. Same shape
+ * as `tests/loop.test.ts` so the wire-level expectations stay aligned
+ * with the loop's real behavior.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { DeepSeekClient } from "../src/client.js";
+import { ToolRegistry } from "../src/tools.js";
+import {
+  type SubagentEvent,
+  type SubagentSink,
+  forkRegistryExcluding,
+  registerSubagentTool,
+} from "../src/tools/subagent.js";
+
+interface FakeResponseShape {
+  content?: string;
+  reasoning_content?: string;
+  tool_calls?: any[];
+  usage?: Record<string, number>;
+}
+
+function fakeFetch(responses: FakeResponseShape[]): typeof fetch {
+  let i = 0;
+  return vi.fn(async (_url: any, init: any) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    const resp = responses[i++] ?? responses[responses.length - 1]!;
+    return new Response(
+      JSON.stringify({
+        _echo_messages: body.messages,
+        choices: [
+          {
+            index: 0,
+            message: {
+              role: "assistant",
+              content: resp.content ?? "",
+              reasoning_content: resp.reasoning_content ?? null,
+              tool_calls: resp.tool_calls ?? undefined,
+            },
+            finish_reason: resp.tool_calls ? "tool_calls" : "stop",
+          },
+        ],
+        usage: resp.usage ?? {
+          prompt_tokens: 100,
+          completion_tokens: 20,
+          total_tokens: 120,
+          prompt_cache_hit_tokens: 0,
+          prompt_cache_miss_tokens: 100,
+        },
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  }) as unknown as typeof fetch;
+}
+
+function makeClient(responses: FakeResponseShape[]) {
+  return new DeepSeekClient({
+    apiKey: "sk-test",
+    fetch: fakeFetch(responses),
+  });
+}
+
+function makeSink(): { sink: SubagentSink; events: SubagentEvent[] } {
+  const events: SubagentEvent[] = [];
+  const sink: SubagentSink = {
+    current: (ev) => {
+      events.push(ev);
+    },
+  };
+  return { sink, events };
+}
+
+describe("registerSubagentTool", () => {
+  it("registers spawn_subagent into the parent registry", () => {
+    const parent = new ToolRegistry();
+    const client = makeClient([{ content: "ok" }]);
+    registerSubagentTool(parent, { client });
+    expect(parent.has("spawn_subagent")).toBe(true);
+  });
+
+  it("returns a structured success payload with the subagent's final answer", async () => {
+    const parent = new ToolRegistry();
+    const client = makeClient([{ content: "the answer is 42" }]);
+    registerSubagentTool(parent, { client });
+    const out = await parent.dispatch(
+      "spawn_subagent",
+      JSON.stringify({ task: "what is the answer?" }),
+    );
+    const parsed = JSON.parse(out);
+    expect(parsed.success).toBe(true);
+    expect(parsed.output).toBe("the answer is 42");
+    expect(parsed.turns).toBe(1);
+    expect(parsed.tool_iters).toBe(0);
+    expect(typeof parsed.elapsed_ms).toBe("number");
+  });
+
+  it("rejects an empty task with a structured error", async () => {
+    const parent = new ToolRegistry();
+    const client = makeClient([{ content: "won't be called" }]);
+    registerSubagentTool(parent, { client });
+    const out = await parent.dispatch("spawn_subagent", JSON.stringify({ task: "   \n  " }));
+    const parsed = JSON.parse(out);
+    expect(parsed.error).toMatch(/non-empty 'task'/);
+  });
+
+  it("emits start → end events through the sink", async () => {
+    const parent = new ToolRegistry();
+    const client = makeClient([{ content: "done" }]);
+    const { sink, events } = makeSink();
+    registerSubagentTool(parent, { client, sink });
+    await parent.dispatch(
+      "spawn_subagent",
+      JSON.stringify({ task: "this task is over thirty characters long" }),
+    );
+    expect(events[0]?.kind).toBe("start");
+    expect(events[events.length - 1]?.kind).toBe("end");
+    // task preview truncated to 30 chars + ellipsis
+    expect(events[0]?.task).toMatch(/…$/);
+    expect(events[0]?.task.length).toBeLessThanOrEqual(31);
+    // end event carries the summary + turn count
+    const end = events[events.length - 1]!;
+    expect(end.summary).toBe("done");
+    expect(end.turns).toBe(1);
+    expect(end.error).toBeUndefined();
+    // 0.5.14: end event also carries cost, model, and aggregate usage
+    // so the sink can write a subagent row to the usage log without
+    // recomputing anything.
+    expect(end.model).toBeTruthy();
+    expect(end.usage).toBeDefined();
+    expect(end.usage?.promptTokens).toBeGreaterThan(0);
+    expect(end.costUsd).toBeGreaterThan(0);
+  });
+
+  it("emits a progress event for each tool result inside the child loop", async () => {
+    const parent = new ToolRegistry();
+    parent.register({
+      name: "noop",
+      readOnly: true,
+      fn: () => "noop-result",
+    });
+    const client = makeClient([
+      {
+        content: "",
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "noop", arguments: "{}" },
+          },
+        ],
+      },
+      { content: "all done" },
+    ]);
+    const { sink, events } = makeSink();
+    registerSubagentTool(parent, { client, sink });
+    await parent.dispatch("spawn_subagent", JSON.stringify({ task: "use noop" }));
+    const progress = events.filter((e) => e.kind === "progress");
+    expect(progress.length).toBe(1);
+    expect(progress[0]?.iter).toBe(1);
+  });
+
+  it("surfaces a child-loop error in the structured result + end event", async () => {
+    const parent = new ToolRegistry();
+    // 401 from the fake fetch → DeepSeekClient throws inside the child step()
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async () => new Response("unauthorized", { status: 401 })) as any,
+      retry: { maxAttempts: 1 },
+    });
+    const { sink, events } = makeSink();
+    registerSubagentTool(parent, { client, sink });
+    const out = await parent.dispatch("spawn_subagent", JSON.stringify({ task: "fail please" }));
+    const parsed = JSON.parse(out);
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toBeTruthy();
+    const end = events[events.length - 1]!;
+    expect(end.kind).toBe("end");
+    expect(end.error).toBeTruthy();
+    expect(end.summary).toBeUndefined();
+  });
+
+  it("truncates oversized output and signals the truncation", async () => {
+    const parent = new ToolRegistry();
+    const huge = "x".repeat(20_000);
+    const client = makeClient([{ content: huge }]);
+    registerSubagentTool(parent, { client, maxResultChars: 100 });
+    const out = await parent.dispatch("spawn_subagent", JSON.stringify({ task: "spew" }));
+    const parsed = JSON.parse(out);
+    expect(parsed.output.length).toBeLessThan(huge.length);
+    expect(parsed.output).toMatch(/truncated/);
+  });
+
+  it("never registers spawn_subagent itself into the child registry (no recursion)", async () => {
+    // We can't easily peek at the child registry from outside the tool,
+    // but we CAN observe the child loop's prefix.toolSpecs via the
+    // request body the fake fetch sees. Tools advertised in the request
+    // are exactly the child registry's specs.
+    const parent = new ToolRegistry();
+    parent.register({ name: "harmless", readOnly: true, fn: () => "ok" });
+    parent.register({ name: "submit_plan", readOnly: true, fn: () => "ok" });
+    const seenToolNames: string[][] = [];
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async (_url: any, init: any) => {
+        const body = init?.body ? JSON.parse(init.body) : {};
+        const tools = (body.tools ?? []) as Array<{ function: { name: string } }>;
+        seenToolNames.push(tools.map((t) => t.function.name));
+        return new Response(
+          JSON.stringify({
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "fine" },
+                finish_reason: "stop",
+              },
+            ],
+            usage: { prompt_tokens: 10, completion_tokens: 1, total_tokens: 11 },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        );
+      }) as any,
+    });
+    registerSubagentTool(parent, { client });
+    await parent.dispatch("spawn_subagent", JSON.stringify({ task: "go" }));
+    expect(seenToolNames.length).toBe(1);
+    const childTools = seenToolNames[0]!;
+    // Inherited the harmless tool, but NOT spawn_subagent or submit_plan.
+    expect(childTools).toContain("harmless");
+    expect(childTools).not.toContain("spawn_subagent");
+    expect(childTools).not.toContain("submit_plan");
+  });
+
+  it("respects a custom system prompt passed in the tool args", async () => {
+    const seenSystems: string[] = [];
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async (_url: any, init: any) => {
+        const body = init?.body ? JSON.parse(init.body) : {};
+        const sys = (body.messages ?? []).find((m: any) => m.role === "system");
+        if (sys) seenSystems.push(sys.content);
+        return new Response(
+          JSON.stringify({
+            choices: [
+              {
+                index: 0,
+                message: { role: "assistant", content: "ok" },
+                finish_reason: "stop",
+              },
+            ],
+            usage: { prompt_tokens: 10, completion_tokens: 1, total_tokens: 11 },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        );
+      }) as any,
+    });
+    const parent = new ToolRegistry();
+    registerSubagentTool(parent, { client });
+    await parent.dispatch(
+      "spawn_subagent",
+      JSON.stringify({ task: "go", system: "You are a custom subagent." }),
+    );
+    expect(seenSystems[0]).toBe("You are a custom subagent.");
+  });
+
+  it("falls back to the default model when the model arg is invalid", async () => {
+    const seenModels: string[] = [];
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async (_url: any, init: any) => {
+        const body = init?.body ? JSON.parse(init.body) : {};
+        seenModels.push(body.model);
+        return new Response(
+          JSON.stringify({
+            choices: [
+              { index: 0, message: { role: "assistant", content: "ok" }, finish_reason: "stop" },
+            ],
+            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        );
+      }) as any,
+    });
+    const parent = new ToolRegistry();
+    registerSubagentTool(parent, { client });
+    // "gpt-4" is not a deepseek-* model — should be ignored.
+    await parent.dispatch("spawn_subagent", JSON.stringify({ task: "go", model: "gpt-4" }));
+    expect(seenModels[0]).toBe("deepseek-chat");
+  });
+
+  it("aborts the child when the parent's tool ctx signal fires", async () => {
+    const parent = new ToolRegistry();
+    // Slow client — sleeps 200ms before responding so the abort beats it.
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: vi.fn(async (_url: any, init: any) => {
+        const signal: AbortSignal | undefined = init?.signal;
+        await new Promise<void>((resolve, reject) => {
+          const t = setTimeout(resolve, 200);
+          signal?.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new DOMException("aborted", "AbortError"));
+          });
+        });
+        return new Response(
+          JSON.stringify({
+            choices: [
+              { index: 0, message: { role: "assistant", content: "late" }, finish_reason: "stop" },
+            ],
+            usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        );
+      }) as any,
+      retry: { maxAttempts: 1 },
+    });
+    registerSubagentTool(parent, { client });
+    const ctrl = new AbortController();
+    setTimeout(() => ctrl.abort(), 20);
+    const out = await parent.dispatch("spawn_subagent", JSON.stringify({ task: "slow" }), {
+      signal: ctrl.signal,
+    });
+    const parsed = JSON.parse(out);
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe("forkRegistryExcluding", () => {
+  it("copies all tools except the excluded names", () => {
+    const parent = new ToolRegistry();
+    parent.register({ name: "a", fn: () => "a" });
+    parent.register({ name: "b", fn: () => "b" });
+    parent.register({ name: "c", fn: () => "c" });
+    const child = forkRegistryExcluding(parent, new Set(["b"]));
+    expect(child.has("a")).toBe(true);
+    expect(child.has("b")).toBe(false);
+    expect(child.has("c")).toBe(true);
+    expect(child.size).toBe(2);
+  });
+
+  it("propagates plan-mode state from the parent", () => {
+    const parent = new ToolRegistry();
+    parent.register({ name: "x", readOnly: true, fn: () => "x" });
+    parent.setPlanMode(true);
+    const child = forkRegistryExcluding(parent, new Set());
+    expect(child.planMode).toBe(true);
+  });
+
+  it("child registry's plan mode defaults off when parent's is off", () => {
+    const parent = new ToolRegistry();
+    parent.register({ name: "x", fn: () => "x" });
+    const child = forkRegistryExcluding(parent, new Set());
+    expect(child.planMode).toBe(false);
+  });
+
+  it("dispatching a copied tool still runs its fn", async () => {
+    const parent = new ToolRegistry();
+    let calls = 0;
+    parent.register({
+      name: "counter",
+      fn: () => {
+        calls++;
+        return `n=${calls}`;
+      },
+    });
+    const child = forkRegistryExcluding(parent, new Set());
+    const out = await child.dispatch("counter", "{}");
+    expect(out).toBe("n=1");
+  });
+});

tests/telemetry.test.ts

@@ -1,6 +1,18 @@
 import { describe, expect, it } from "vitest";
 import { Usage } from "../src/client.js";
-import { SessionStats, costUsd, inputCostUsd, outputCostUsd } from "../src/telemetry.js";
+import {
+  DEEPSEEK_PRICING,
+  SessionStats,
+  costUsd,
+  inputCostUsd,
+  outputCostUsd,
+} from "../src/telemetry.js";
+
+// Derive expected figures from the pricing table so the tests don't
+// re-bake stale constants every time DeepSeek updates the price sheet.
+// The `costUsd` formula under test is:
+//   (hitT * hit + missT * miss + outT * out) / 1e6
+const CHAT = DEEPSEEK_PRICING["deepseek-chat"]!;
 
 describe("Usage.cacheHitRatio", () => {
   it("computes hit ratio", () => {
@@ -16,8 +28,10 @@ describe("costUsd", () => {
   it("applies DeepSeek pricing tiers", () => {
     const u = new Usage(1000, 100, 0, 800, 200);
     const c = costUsd("deepseek-chat", u);
-    // (800 * 0.07 + 200 * 0.27 + 100 * 1.10) / 1e6
-    expect(c).toBeCloseTo((800 * 0.07 + 200 * 0.27 + 100 * 1.1) / 1_000_000, 10);
+    expect(c).toBeCloseTo(
+      (800 * CHAT.inputCacheHit + 200 * CHAT.inputCacheMiss + 100 * CHAT.output) / 1_000_000,
+      10,
+    );
   });
 
   it("returns 0 for unknown model", () => {
@@ -56,12 +70,16 @@ describe("SessionStats", () => {
     const stats = new SessionStats();
     stats.record(1, "deepseek-chat", new Usage(1000, 100, 1100, 800, 200));
     const s = stats.summary();
-    // input: (800 * 0.07 + 200 * 0.27) / 1e6 = 0.000056 + 0.000054 = 0.00011
-    // output: 100 * 1.10 / 1e6 = 0.00011
-    expect(s.totalInputCostUsd).toBeCloseTo((800 * 0.07 + 200 * 0.27) / 1_000_000, 10);
-    expect(s.totalOutputCostUsd).toBeCloseTo((100 * 1.1) / 1_000_000, 10);
+    // `summary()` rounds USD figures to 6 decimals, so we match at 6 —
+    // the raw formula at higher precision is exercised by the
+    // `inputCostUsd` / `outputCostUsd` tests below.
+    expect(s.totalInputCostUsd).toBeCloseTo(
+      (800 * CHAT.inputCacheHit + 200 * CHAT.inputCacheMiss) / 1_000_000,
+      6,
+    );
+    expect(s.totalOutputCostUsd).toBeCloseTo((100 * CHAT.output) / 1_000_000, 6);
     // Sum of input+output equals total (within rounding).
-    expect(s.totalInputCostUsd + s.totalOutputCostUsd).toBeCloseTo(s.totalCostUsd, 9);
+    expect(s.totalInputCostUsd + s.totalOutputCostUsd).toBeCloseTo(s.totalCostUsd, 6);
   });
 });
 
@@ -69,13 +87,23 @@ describe("inputCostUsd / outputCostUsd", () => {
   it("input cost covers cache-hit + cache-miss but NOT completion", () => {
     const u = new Usage(1000, 100, 1100, 800, 200);
     const i = inputCostUsd("deepseek-chat", u);
-    expect(i).toBeCloseTo((800 * 0.07 + 200 * 0.27) / 1_000_000, 10);
+    expect(i).toBeCloseTo((800 * CHAT.inputCacheHit + 200 * CHAT.inputCacheMiss) / 1_000_000, 10);
   });
 
   it("output cost covers completion only", () => {
     const u = new Usage(1000, 100, 1100, 800, 200);
     const o = outputCostUsd("deepseek-chat", u);
-    expect(o).toBeCloseTo((100 * 1.1) / 1_000_000, 10);
+    expect(o).toBeCloseTo((100 * CHAT.output) / 1_000_000, 10);
+  });
+
+  it("chat and reasoner are unified at the same price", () => {
+    // Post-unification (2026-04): DeepSeek charges identically for both
+    // models. If this test starts failing, either DeepSeek reintroduced
+    // tiered pricing (update the constants) or someone accidentally
+    // edited only one entry — catch that before shipping.
+    const chat = DEEPSEEK_PRICING["deepseek-chat"]!;
+    const reasoner = DEEPSEEK_PRICING["deepseek-reasoner"]!;
+    expect(reasoner).toEqual(chat);
   });
 
   it("both return 0 for an unknown model", () => {

tests/tokenizer.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import { countTokens, encode, estimateConversationTokens } from "../src/tokenizer.js";
+
+describe("DeepSeek V3 tokenizer — golden cases", () => {
+  // These IDs were captured from the pure-TS port running against the
+  // bundled `data/deepseek-tokenizer.json.gz`. They match what DeepSeek's
+  // official Python tokenizer produces (HF LlamaTokenizerFast on the
+  // same tokenizer.json). If a case regresses, check that the data
+  // file wasn't accidentally truncated or the pre_tokenizer Sequence
+  // wasn't reordered.
+  it("empty string is zero tokens", () => {
+    expect(encode("")).toEqual([]);
+    expect(countTokens("")).toBe(0);
+  });
+
+  it("ASCII words tokenize compactly", () => {
+    expect(encode("Hello!")).toEqual([19923, 3]);
+    expect(encode("Hello, world!")).toEqual([19923, 14, 2058, 3]);
+  });
+
+  it("common CJK collocation is a single token", () => {
+    expect(encode("你好")).toEqual([30594]);
+  });
+
+  it("CJK sentence splits on punctuation", () => {
+    expect(encode("你好，世界！")).toEqual([30594, 303, 3427, 1175]);
+  });
+
+  it("digit run is isolated by the \\p{N}{1,3} pre-tokenizer rule", () => {
+    // "1 + 1 = 2" → numbers get their own tokens; spaces/operators
+    // fold into byte-level pieces.
+    expect(encode("1 + 1 = 2")).toEqual([19, 940, 223, 19, 438, 223, 20]);
+  });
+
+  it("recognizes <think>/</think> as atomic added tokens", () => {
+    // 128798 = <think>, 128799 = </think> per tokenizer.json added_tokens.
+    const ids = encode("<think>reasoning here</think>");
+    expect(ids[0]).toBe(128798);
+    expect(ids[ids.length - 1]).toBe(128799);
+    expect(ids.length).toBe(5);
+  });
+
+  it("mixed English+CJK follows the right pre-tokenizer branches", () => {
+    const ids = encode("mixed 中文 and english 混合");
+    expect(ids).toEqual([122545, 223, 21134, 305, 33010, 223, 14769]);
+  });
+
+  it("round-trips a code snippet at a reasonable compression ratio", () => {
+    const src = "function add(a, b) { return a + b; }";
+    const n = countTokens(src);
+    // 37 chars → expected ~12-14 tokens for a ByteLevel BPE trained on
+    // code. Assert a loose band so a future tokenizer refresh (vocab
+    // shift ±5%) doesn't break the test suite.
+    expect(n).toBeGreaterThanOrEqual(10);
+    expect(n).toBeLessThanOrEqual(16);
+  });
+
+  it("Chinese prose gets the expected ~0.6 tokens/char rate", () => {
+    const text = "深度求索是一家专注于人工智能基础技术研究的公司";
+    const n = countTokens(text);
+    // 22 CJK chars → DeepSeek's doc claims ~0.6 tokens/char ≈ 13, our
+    // V3 tokenizer's CJK compression is tighter; allow 8-16 as the
+    // sanity range.
+    expect(n).toBeGreaterThanOrEqual(8);
+    expect(n).toBeLessThanOrEqual(16);
+  });
+});
+
+describe("estimateConversationTokens", () => {
+  it("sums content across roles", () => {
+    const n = estimateConversationTokens([
+      { content: "you are helpful" },
+      { content: "你好" },
+      { content: "Hello!" },
+    ]);
+    const manual = countTokens("you are helpful") + countTokens("你好") + countTokens("Hello!");
+    expect(n).toBe(manual);
+  });
+
+  it("counts tool_calls JSON bytes when present", () => {
+    const withCalls = estimateConversationTokens([
+      {
+        content: null,
+        tool_calls: [{ id: "c1", function: { name: "read_file", arguments: '{"path":"a.ts"}' } }],
+      },
+    ]);
+    // The tool_calls serialization itself has weight; should be > 0.
+    expect(withCalls).toBeGreaterThan(0);
+  });
+
+  it("ignores missing / empty content without crashing", () => {
+    expect(
+      estimateConversationTokens([{ content: null }, { content: "" }, { content: undefined }]),
+    ).toBe(0);
+  });
+});
+
+describe("performance sanity", () => {
+  it("tokenizes 10k chars of typical mixed content in under 200 ms", () => {
+    const block = "Hello world! 你好 deepseek ".repeat(400); // ~9,600 chars
+    const t0 = performance.now();
+    const n = countTokens(block);
+    const t1 = performance.now();
+    expect(n).toBeGreaterThan(1000);
+    expect(t1 - t0).toBeLessThan(200);
+  });
+});

tests/tools-memory.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Tests for the `remember` / `forget` / `recall_memory` tool surface.
+ * Dispatches through ToolRegistry like R1 would, so refusals surface
+ * as JSON-encoded `{ error: ... }` strings (matching dispatch semantics).
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import { registerMemoryTools } from "../src/tools/memory.js";
+import { MemoryStore } from "../src/user-memory.js";
+
+describe("memory tools", () => {
+  let home: string;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-memtools-home-"));
+    projectRoot = mkdtempSync(join(tmpdir(), "reasonix-memtools-proj-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  describe("remember", () => {
+    it("writes a global memory and returns a human-readable confirmation", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("remember", {
+        type: "feedback",
+        scope: "global",
+        name: "pref_one",
+        description: "User prefers tabs",
+        content: "Always use tabs for indentation.",
+      });
+      expect(out).toMatch(/REMEMBERED \(global\/pref_one\)/);
+      expect(out).toMatch(/User prefers tabs/);
+      // Verify the store actually has it.
+      const store = new MemoryStore({ homeDir: home });
+      const listed = store.list();
+      expect(listed.map((e) => e.name)).toContain("pref_one");
+    });
+
+    it("refuses scope='project' when no projectRoot is configured", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("remember", {
+        type: "project",
+        scope: "project",
+        name: "xyz_abc",
+        description: "d",
+        content: "c",
+      });
+      const parsed = JSON.parse(out);
+      expect(parsed.error).toMatch(/scope='project'/);
+    });
+
+    it("allows scope='project' when projectRoot is configured", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home, projectRoot });
+      const out = await reg.dispatch("remember", {
+        type: "project",
+        scope: "project",
+        name: "bun_build",
+        description: "Build is bun run build",
+        content: "On this machine, no npm — only bun.",
+      });
+      expect(out).toMatch(/REMEMBERED \(project\/bun_build\)/);
+    });
+
+    it("returns an error (not a throw) for invalid names", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("remember", {
+        type: "user",
+        scope: "global",
+        name: "../bad",
+        description: "d",
+        content: "c",
+      });
+      const parsed = JSON.parse(out);
+      expect(parsed.error).toMatch(/invalid memory name/);
+    });
+
+    it("returns an error when description is empty", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("remember", {
+        type: "user",
+        scope: "global",
+        name: "nonempty_name",
+        description: "",
+        content: "body",
+      });
+      const parsed = JSON.parse(out);
+      expect(parsed.error).toMatch(/description/);
+    });
+  });
+
+  describe("forget", () => {
+    it("removes an existing memory and reports so", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      await reg.dispatch("remember", {
+        type: "user",
+        scope: "global",
+        name: "delete_me",
+        description: "d",
+        content: "c",
+      });
+      const out = await reg.dispatch("forget", { scope: "global", name: "delete_me" });
+      expect(out).toMatch(/forgot \(global\/delete_me\)/);
+      const store = new MemoryStore({ homeDir: home });
+      expect(store.list().map((e) => e.name)).not.toContain("delete_me");
+    });
+
+    it("is idempotent on a missing memory (reports 'no such memory')", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("forget", { scope: "global", name: "ghost_one" });
+      expect(out).toMatch(/no such memory/);
+    });
+  });
+
+  describe("recall_memory", () => {
+    it("returns the body of an existing memory (with header)", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      await reg.dispatch("remember", {
+        type: "feedback",
+        scope: "global",
+        name: "deep_detail",
+        description: "short one-liner",
+        content: "Full body with **markdown** and multiple paragraphs.\n\nSecond paragraph.",
+      });
+      const out = await reg.dispatch("recall_memory", {
+        scope: "global",
+        name: "deep_detail",
+      });
+      expect(out).toContain("deep_detail");
+      expect(out).toContain("Full body with **markdown**");
+      expect(out).toContain("Second paragraph.");
+    });
+
+    it("returns an error (not a throw) on missing name", async () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const out = await reg.dispatch("recall_memory", { scope: "global", name: "ghost_one" });
+      const parsed = JSON.parse(out);
+      expect(parsed.error).toMatch(/recall failed/);
+    });
+
+    it("is marked readOnly (available in plan mode)", () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      const tool = reg.get("recall_memory");
+      expect(tool?.readOnly).toBe(true);
+    });
+  });
+
+  describe("registration", () => {
+    it("registers all three tools", () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      expect(reg.has("remember")).toBe(true);
+      expect(reg.has("forget")).toBe(true);
+      expect(reg.has("recall_memory")).toBe(true);
+    });
+
+    it("remember / forget are NOT marked readOnly (gated in plan mode)", () => {
+      const reg = new ToolRegistry();
+      registerMemoryTools(reg, { homeDir: home });
+      expect(reg.get("remember")?.readOnly).not.toBe(true);
+      expect(reg.get("forget")?.readOnly).not.toBe(true);
+    });
+  });
+});

tests/tools-skills.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for the `run_skill` tool. Uses a temp `homeDir` and optional
+ * `projectRoot` so the tool never reads real skill dirs.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import { registerSkillTools } from "../src/tools/skills.js";
+
+/**
+ * Write a skill under `<baseDir>/.reasonix/skills/<name>/SKILL.md`.
+ * Callers pass their home tmpdir for global-scope skills, or their
+ * projectRoot tmpdir for project-scope skills — the on-disk layout is
+ * the same either way, only the base directory differs.
+ */
+function writeSkill(baseDir: string, name: string, description: string, body: string): void {
+  const dir = join(baseDir, ".reasonix", "skills", name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "SKILL.md"),
+    `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`,
+    "utf8",
+  );
+}
+
+/**
+ * Write a skill with arbitrary frontmatter — used for subagent-runAs
+ * tests where we need `runAs: subagent` and an optional `model:` line.
+ */
+function writeSkillWithFrontmatter(
+  baseDir: string,
+  name: string,
+  fm: Record<string, string>,
+  body: string,
+): void {
+  const dir = join(baseDir, ".reasonix", "skills", name);
+  mkdirSync(dir, { recursive: true });
+  const lines = ["---", `name: ${name}`];
+  for (const [k, v] of Object.entries(fm)) lines.push(`${k}: ${v}`);
+  lines.push("---", "");
+  writeFileSync(join(dir, "SKILL.md"), `${lines.join("\n")}${body}\n`, "utf8");
+}
+
+describe("run_skill tool", () => {
+  let home: string;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-skilltool-"));
+    projectRoot = mkdtempSync(join(tmpdir(), "reasonix-skilltool-proj-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it("registers run_skill as a read-only tool", () => {
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const tool = reg.get("run_skill");
+    expect(tool).toBeDefined();
+    expect(tool?.readOnly).toBe(true);
+  });
+
+  it("returns the skill body when the name resolves (global scope)", async () => {
+    writeSkill(home, "review", "Review a PR", "Step 1: diff. Step 2: comment.");
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", { name: "review" });
+    expect(out).toContain("# Skill: review");
+    expect(out).toContain("Review a PR");
+    expect(out).toContain("scope: global");
+    expect(out).toContain("Step 1: diff");
+  });
+
+  it("resolves project-scope skills when projectRoot is passed", async () => {
+    writeSkill(projectRoot, "deploy", "Deploy to staging", "Run pipeline.");
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, projectRoot, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", { name: "deploy" });
+    expect(out).toContain("scope: project");
+    expect(out).toContain("Run pipeline");
+  });
+
+  it("appends a forwarded 'Arguments:' line when provided", async () => {
+    writeSkill(home, "greet", "Greet someone", "Say hello to the name in args.");
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", { name: "greet", arguments: "Alice" });
+    expect(out).toContain("Arguments: Alice");
+  });
+
+  it("returns a structured error with available names on unknown skill", async () => {
+    writeSkill(home, "review", "Review a PR", "...");
+    writeSkill(home, "ship-it", "Push commit", "...");
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", { name: "nope" });
+    const parsed = JSON.parse(out);
+    expect(parsed.error).toMatch(/unknown skill/);
+    expect(parsed.available).toContain("review");
+    expect(parsed.available).toContain("ship-it");
+  });
+
+  it("rejects an empty name", async () => {
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", { name: "" });
+    expect(JSON.parse(out).error).toMatch(/requires a 'name'/);
+  });
+
+  it("dispatches subagent-runAs skills through subagentRunner", async () => {
+    writeSkillWithFrontmatter(
+      home,
+      "deepdive",
+      { description: "deep dive subagent", runAs: "subagent" },
+      "You are a deep-dive agent. Investigate the task and return a one-line answer.",
+    );
+    const reg = new ToolRegistry();
+    let received: { skillName: string; skillBody: string; task: string } | null = null;
+    registerSkillTools(reg, {
+      homeDir: home,
+      disableBuiltins: true,
+      subagentRunner: async (skill, task) => {
+        received = { skillName: skill.name, skillBody: skill.body, task };
+        return JSON.stringify({ success: true, output: "subagent-said-this" });
+      },
+    });
+    const out = await reg.dispatch("run_skill", {
+      name: "deepdive",
+      arguments: "find all tests that touch the loop",
+    });
+    expect(received?.skillName).toBe("deepdive");
+    expect(received?.skillBody).toContain("deep-dive agent");
+    expect(received?.task).toBe("find all tests that touch the loop");
+    const parsed = JSON.parse(out);
+    expect(parsed.output).toBe("subagent-said-this");
+  });
+
+  it("returns a configured-error when a subagent skill fires without a runner", async () => {
+    writeSkillWithFrontmatter(
+      home,
+      "needs-runner",
+      { description: "needs a runner", runAs: "subagent" },
+      "...",
+    );
+    const reg = new ToolRegistry();
+    // Note: NO subagentRunner.
+    registerSkillTools(reg, { homeDir: home, disableBuiltins: true });
+    const out = await reg.dispatch("run_skill", {
+      name: "needs-runner",
+      arguments: "do the thing",
+    });
+    expect(JSON.parse(out).error).toMatch(/no subagent runner is configured/);
+  });
+
+  it("requires arguments for subagent skills (subagent has no other context)", async () => {
+    writeSkillWithFrontmatter(
+      home,
+      "needs-args",
+      { description: "needs args", runAs: "subagent" },
+      "...",
+    );
+    const reg = new ToolRegistry();
+    registerSkillTools(reg, {
+      homeDir: home,
+      disableBuiltins: true,
+      subagentRunner: async () => "should-not-be-called",
+    });
+    const out = await reg.dispatch("run_skill", { name: "needs-args" });
+    expect(JSON.parse(out).error).toMatch(/requires 'arguments'/);
+  });
+
+  it("inline skills don't go through subagentRunner even when one exists", async () => {
+    writeSkill(home, "inline-skill", "plain", "Step 1, Step 2.");
+    const reg = new ToolRegistry();
+    let runnerCalls = 0;
+    registerSkillTools(reg, {
+      homeDir: home,
+      disableBuiltins: true,
+      subagentRunner: async () => {
+        runnerCalls++;
+        return "x";
+      },
+    });
+    const out = await reg.dispatch("run_skill", { name: "inline-skill" });
+    expect(out).toContain("Step 1, Step 2.");
+    expect(runnerCalls).toBe(0);
+  });
+});

tests/tools.test.ts

@@ -145,6 +145,31 @@ describe("ToolRegistry", () => {
     expect(received).toEqual({ a: { b: { c: "hi" } } });
   });
 
+  it("truncates oversized results when maxResultChars is set", async () => {
+    const reg = new ToolRegistry();
+    const big = "x".repeat(50_000);
+    reg.register({
+      name: "bloat",
+      parameters: { type: "object", properties: {} },
+      fn: () => big,
+    });
+    const out = await reg.dispatch("bloat", "{}", { maxResultChars: 1000 });
+    expect(out.length).toBeLessThan(2000);
+    expect(out).toMatch(/truncated/);
+  });
+
+  it("passes results through unchanged when maxResultChars is absent", async () => {
+    const reg = new ToolRegistry();
+    const big = "x".repeat(50_000);
+    reg.register({
+      name: "bloat",
+      parameters: { type: "object", properties: {} },
+      fn: () => big,
+    });
+    const out = await reg.dispatch("bloat", "{}");
+    expect(out.length).toBe(50_000);
+  });
+
   it("autoFlatten:false opts out", () => {
     const reg = new ToolRegistry({ autoFlatten: false });
     reg.register({

tests/truncate-tokens.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_MAX_RESULT_TOKENS, truncateForModelByTokens } from "../src/mcp/registry.js";
+import { countTokens } from "../src/tokenizer.js";
+
+describe("truncateForModelByTokens", () => {
+  it("returns the string unchanged when it fits the budget", () => {
+    const s = "Hello, world! This is a short string.";
+    expect(truncateForModelByTokens(s, 1000)).toBe(s);
+  });
+
+  it("returns the string unchanged when length <= budget (fast path)", () => {
+    // Fast path: every token is ≥ 1 char, so length ≤ budget implies
+    // tokens ≤ budget. No tokenize call should be needed.
+    const s = "a".repeat(50);
+    expect(truncateForModelByTokens(s, 100)).toBe(s);
+  });
+
+  it("truncates when tokens exceed the budget", () => {
+    // 2000 "hello " tokens → well above 100-token budget
+    const s = "hello ".repeat(2000);
+    const out = truncateForModelByTokens(s, 100);
+    expect(out).not.toBe(s);
+    // Output includes the head, a truncation marker, and a short tail
+    expect(out).toMatch(/…truncated ~?\d+ tokens \(\d+ chars\)/);
+    // Final token count stays reasonably close to (at or below) budget
+    // plus the marker's ~48-token overhead — we allow a small slack
+    // because the slice refinement is char-based and can overshoot by
+    // a few tokens before the retry loop settles.
+    expect(countTokens(out)).toBeLessThanOrEqual(250);
+  });
+
+  it("caps CJK text at the same token footprint as English", () => {
+    // 8000 chars of Chinese — roughly 5000-8000 tokens depending on
+    // which chars; old char-based cap at 32000 would let this through
+    // at 2× the token cost. Token cap pulls it down.
+    const s = "你好世界".repeat(2000); // 8000 chars
+    const out = truncateForModelByTokens(s, 500);
+    expect(countTokens(out)).toBeLessThanOrEqual(700);
+    expect(out).toMatch(/…truncated/);
+  });
+
+  it("preserves both the head and the tail of the content", () => {
+    const head = "START-OF-RESULT\n";
+    const middle = "filler line\n".repeat(5000);
+    const tail = "\nEND-OF-RESULT";
+    const s = head + middle + tail;
+    const out = truncateForModelByTokens(s, 500);
+    // Head leading sentinel is preserved at the start
+    expect(out.startsWith("START-OF-RESULT")).toBe(true);
+    // Tail trailing sentinel survives via the short tail window
+    expect(out.endsWith("END-OF-RESULT")).toBe(true);
+    expect(out).toMatch(/…truncated/);
+  });
+
+  it("returns the empty string when budget is zero or negative", () => {
+    expect(truncateForModelByTokens("anything", 0)).toBe("");
+    expect(truncateForModelByTokens("anything", -5)).toBe("");
+  });
+
+  it("handles the empty string", () => {
+    expect(truncateForModelByTokens("", 100)).toBe("");
+    expect(truncateForModelByTokens("", 0)).toBe("");
+  });
+
+  it("default token budget is 8000", () => {
+    expect(DEFAULT_MAX_RESULT_TOKENS).toBe(8_000);
+  });
+
+  it("truncated marker reports a positive dropped-tokens count", () => {
+    const s = "A".repeat(40_000);
+    const out = truncateForModelByTokens(s, 200);
+    const match = /truncated ~?(\d+) tokens \((\d+) chars\)/.exec(out);
+    expect(match).not.toBeNull();
+    const droppedTokens = Number(match![1]);
+    const droppedChars = Number(match![2]);
+    expect(droppedTokens).toBeGreaterThan(0);
+    expect(droppedChars).toBeGreaterThan(0);
+  });
+});

tests/update-command.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Tests for the `reasonix update` command — pure decision function
+ * + the CLI orchestrator with every side effect mocked via its
+ * test seams. No network, no spawn, no process.exit.
+ */
+
+import { describe, expect, it } from "vitest";
+import { planUpdate, updateCommand } from "../src/cli/commands/update.js";
+import { VERSION } from "../src/version.js";
+
+describe("planUpdate", () => {
+  it("up-to-date when current === latest", () => {
+    const plan = planUpdate({ current: "0.4.22", latest: "0.4.22" });
+    expect(plan.action).toBe("up-to-date");
+    expect(plan.command).toBeUndefined();
+  });
+
+  it("newer-local when current > latest (dev build)", () => {
+    const plan = planUpdate({ current: "0.5.0", latest: "0.4.22" });
+    expect(plan.action).toBe("newer-local");
+    expect(plan.command).toBeUndefined();
+  });
+
+  it("npx-hint when current < latest and running via npx", () => {
+    const plan = planUpdate({ current: "0.4.21", latest: "0.4.22", npx: true });
+    expect(plan.action).toBe("npx-hint");
+    expect(plan.command).toBeUndefined();
+    expect(plan.message).toContain("npx");
+  });
+
+  it("run-npm-install when current < latest and not npx", () => {
+    const plan = planUpdate({ current: "0.4.21", latest: "0.4.22", npx: false });
+    expect(plan.action).toBe("run-npm-install");
+    expect(plan.command).toEqual(["npm", "install", "-g", "reasonix@latest"]);
+  });
+});
+
+describe("updateCommand", () => {
+  function harness() {
+    const output: string[] = [];
+    let exitCode: number | undefined;
+    const spawnCalls: string[][] = [];
+    return {
+      output,
+      get exitCode() {
+        return exitCode;
+      },
+      spawnCalls,
+      write: (m: string) => {
+        output.push(m);
+      },
+      exit: (c: number) => {
+        exitCode = c;
+      },
+      spawnInstall: async (argv: string[]) => {
+        spawnCalls.push(argv);
+        return 0;
+      },
+    };
+  }
+
+  it("prints up-to-date and does NOT spawn when current === latest", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => VERSION,
+      isNpx: () => false,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: h.spawnInstall,
+    });
+    expect(h.output.join("")).toContain("up to date");
+    expect(h.spawnCalls).toHaveLength(0);
+    expect(h.exitCode).toBeUndefined();
+  });
+
+  it("prints npx hint and does NOT spawn when running under npx", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => "99.99.99",
+      isNpx: () => true,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: h.spawnInstall,
+    });
+    const joined = h.output.join("");
+    expect(joined).toContain("99.99.99");
+    expect(joined).toContain("npx");
+    expect(h.spawnCalls).toHaveLength(0);
+  });
+
+  it("spawns npm install -g when global install is behind latest", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => "99.99.99",
+      isNpx: () => false,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: h.spawnInstall,
+    });
+    expect(h.spawnCalls).toEqual([["npm", "install", "-g", "reasonix@latest"]]);
+    expect(h.exitCode).toBeUndefined();
+  });
+
+  it("--dry-run prints the command but does not spawn", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => "99.99.99",
+      isNpx: () => false,
+      dryRun: true,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: h.spawnInstall,
+    });
+    expect(h.spawnCalls).toHaveLength(0);
+    expect(h.output.join("")).toContain("(dry run)");
+  });
+
+  it("exits non-zero when the registry is unreachable", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => null,
+      isNpx: () => false,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: h.spawnInstall,
+    });
+    expect(h.output.join("")).toContain("could not reach");
+    expect(h.exitCode).toBe(1);
+  });
+
+  it("surfaces non-zero npm exit via the exit seam", async () => {
+    const h = harness();
+    await updateCommand({
+      fetchLatest: async () => "99.99.99",
+      isNpx: () => false,
+      write: h.write,
+      exit: h.exit,
+      spawnInstall: async () => 127,
+    });
+    expect(h.exitCode).toBe(127);
+    expect(h.output.join("")).toContain("did not complete");
+  });
+});

tests/usage.test.ts

@@ -0,0 +1,385 @@
+/**
+ * Tests for the usage log + aggregator.
+ *
+ * Covered:
+ *   - appendUsage round-trips (record → file → readUsageLog)
+ *   - readUsageLog tolerates malformed tail lines + missing file
+ *   - aggregateUsage rolls records into today / week / month / all
+ *     using rolling windows against an injected `now`
+ *   - bucketCacheHitRatio / bucketSavingsFraction handle zero-denominator
+ *   - stats dashboard render contains the expected rows
+ */
+
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { renderDashboard } from "../src/cli/commands/stats.js";
+import { Usage } from "../src/client.js";
+import {
+  type UsageRecord,
+  aggregateUsage,
+  appendUsage,
+  bucketCacheHitRatio,
+  bucketSavingsFraction,
+  readUsageLog,
+} from "../src/usage.js";
+
+function usage(overrides: Partial<Usage> = {}): Usage {
+  return new Usage(
+    overrides.promptTokens ?? 100,
+    overrides.completionTokens ?? 20,
+    overrides.totalTokens ?? 120,
+    overrides.promptCacheHitTokens ?? 80,
+    overrides.promptCacheMissTokens ?? 20,
+  );
+}
+
+describe("appendUsage + readUsageLog", () => {
+  let dir: string;
+  let path: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "reasonix-usage-"));
+    path = join(dir, "usage.jsonl");
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("round-trips a single record", () => {
+    const record = appendUsage({
+      session: "default",
+      model: "deepseek-reasoner",
+      usage: usage(),
+      now: 1_700_000_000_000,
+      path,
+    });
+    expect(record.session).toBe("default");
+    expect(record.costUsd).toBeGreaterThan(0);
+    expect(record.claudeEquivUsd).toBeGreaterThan(record.costUsd);
+
+    const loaded = readUsageLog(path);
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0]?.ts).toBe(1_700_000_000_000);
+    expect(loaded[0]?.session).toBe("default");
+  });
+
+  it("returns [] when the log does not exist", () => {
+    expect(readUsageLog(path)).toEqual([]);
+  });
+
+  it("tolerates a malformed trailing line (skips it)", () => {
+    appendUsage({ session: null, model: "deepseek-chat", usage: usage(), path });
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, "{ not valid json\n", "utf8");
+    const loaded = readUsageLog(path);
+    expect(loaded).toHaveLength(1);
+  });
+
+  it("creates the parent directory if missing", () => {
+    const deep = join(dir, "a", "b", "usage.jsonl");
+    appendUsage({ session: null, model: "deepseek-chat", usage: usage(), path: deep });
+    expect(readUsageLog(deep)).toHaveLength(1);
+  });
+
+  it("swallows write failure silently (best-effort contract)", () => {
+    // Point at a path under a FILE, not a directory — mkdirSync will
+    // blow up and appendUsage should absorb it without throwing.
+    const blocker = join(dir, "blocker");
+    appendFileSync(blocker, "not a dir");
+    expect(() =>
+      appendUsage({
+        session: null,
+        model: "deepseek-chat",
+        usage: usage(),
+        path: join(blocker, "usage.jsonl"),
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("aggregateUsage", () => {
+  const NOW = 1_700_000_000_000; // fixed epoch for all windows below
+  const DAY = 24 * 60 * 60 * 1000;
+
+  function rec(partial: Partial<UsageRecord> & { ts: number }): UsageRecord {
+    return {
+      session: null,
+      model: "deepseek-reasoner",
+      promptTokens: 100,
+      completionTokens: 20,
+      cacheHitTokens: 80,
+      cacheMissTokens: 20,
+      costUsd: 0.001,
+      claudeEquivUsd: 0.01,
+      ...partial,
+    };
+  }
+
+  it("empty input → empty buckets, null firstSeen/lastSeen", () => {
+    const agg = aggregateUsage([], { now: NOW });
+    expect(agg.buckets.map((b) => b.turns)).toEqual([0, 0, 0, 0]);
+    expect(agg.firstSeen).toBeNull();
+    expect(agg.lastSeen).toBeNull();
+  });
+
+  it("rolls records into today / week / month / all by age", () => {
+    const records = [
+      rec({ ts: NOW - 60_000 }), // 1 min ago → today
+      rec({ ts: NOW - 2 * DAY }), // 2 days ago → week + month + all
+      rec({ ts: NOW - 10 * DAY }), // 10 days → month + all
+      rec({ ts: NOW - 90 * DAY }), // 90 days → only all-time
+    ];
+    const agg = aggregateUsage(records, { now: NOW });
+    const [today, week, month, all] = agg.buckets;
+    expect(today?.turns).toBe(1);
+    expect(week?.turns).toBe(2);
+    expect(month?.turns).toBe(3);
+    expect(all?.turns).toBe(4);
+  });
+
+  it("sums token + cost fields across records in each window", () => {
+    const records = [
+      rec({
+        ts: NOW - 60_000,
+        costUsd: 0.5,
+        claudeEquivUsd: 5,
+        cacheHitTokens: 1,
+        cacheMissTokens: 0,
+      }),
+      rec({
+        ts: NOW - 60_001,
+        costUsd: 0.25,
+        claudeEquivUsd: 2,
+        cacheHitTokens: 1,
+        cacheMissTokens: 1,
+      }),
+    ];
+    const agg = aggregateUsage(records, { now: NOW });
+    const today = agg.buckets[0];
+    expect(today?.costUsd).toBeCloseTo(0.75);
+    expect(today?.claudeEquivUsd).toBeCloseTo(7);
+    expect(today?.cacheHitTokens).toBe(2);
+    expect(today?.cacheMissTokens).toBe(1);
+  });
+
+  it("byModel + bySession sort descending and group nulls under (ephemeral)", () => {
+    const records = [
+      rec({ ts: NOW - 60_000, model: "deepseek-chat", session: "a" }),
+      rec({ ts: NOW - 60_000, model: "deepseek-reasoner", session: "a" }),
+      rec({ ts: NOW - 60_000, model: "deepseek-reasoner", session: "b" }),
+      rec({ ts: NOW - 60_000, model: "deepseek-reasoner", session: null }),
+    ];
+    const agg = aggregateUsage(records, { now: NOW });
+    expect(agg.byModel[0]?.model).toBe("deepseek-reasoner");
+    expect(agg.byModel[0]?.turns).toBe(3);
+    expect(agg.bySession[0]?.session).toBe("a");
+    expect(agg.bySession.find((s) => s.session === "(ephemeral)")?.turns).toBe(1);
+  });
+});
+
+describe("bucket helpers", () => {
+  it("cache hit ratio — zero denominator → 0", () => {
+    const b = aggregateUsage([], { now: 1 }).buckets[0]!;
+    expect(bucketCacheHitRatio(b)).toBe(0);
+  });
+
+  it("cache hit ratio — 80 hit / 20 miss → 0.8", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000,
+          session: null,
+          model: "deepseek-chat",
+          promptTokens: 100,
+          completionTokens: 0,
+          cacheHitTokens: 80,
+          cacheMissTokens: 20,
+          costUsd: 0,
+          claudeEquivUsd: 0,
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    const today = agg.buckets[0]!;
+    expect(bucketCacheHitRatio(today)).toBeCloseTo(0.8);
+  });
+
+  it("savings fraction — zero Claude cost → 0 (no division)", () => {
+    const b = aggregateUsage([], { now: 1 }).buckets[0]!;
+    expect(bucketSavingsFraction(b)).toBe(0);
+  });
+
+  it("savings fraction — cost $1 vs Claude $10 → 0.9", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000,
+          session: null,
+          model: "deepseek-chat",
+          promptTokens: 0,
+          completionTokens: 0,
+          cacheHitTokens: 0,
+          cacheMissTokens: 0,
+          costUsd: 1,
+          claudeEquivUsd: 10,
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    expect(bucketSavingsFraction(agg.buckets[0]!)).toBeCloseTo(0.9);
+  });
+});
+
+describe("renderDashboard", () => {
+  it("includes the four window labels + header", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000,
+          session: "s",
+          model: "deepseek-reasoner",
+          promptTokens: 1,
+          completionTokens: 1,
+          cacheHitTokens: 1,
+          cacheMissTokens: 0,
+          costUsd: 0.001,
+          claudeEquivUsd: 0.1,
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    const out = renderDashboard(agg, "/tmp/fake.jsonl");
+    expect(out).toContain("today");
+    expect(out).toContain("week");
+    expect(out).toContain("month");
+    expect(out).toContain("all-time");
+    expect(out).toContain("cache hit");
+    expect(out).toContain("vs Claude");
+    expect(out).toContain("most used model:");
+    expect(out).toContain("top session:");
+    expect(out).toContain("tracked since:");
+  });
+
+  it("surfaces a subagent activity section when subagent records are present", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000,
+          session: "s",
+          model: "deepseek-chat",
+          promptTokens: 500,
+          completionTokens: 60,
+          cacheHitTokens: 400,
+          cacheMissTokens: 100,
+          costUsd: 0.002,
+          claudeEquivUsd: 0.02,
+          kind: "subagent",
+          subagent: {
+            skillName: "explore",
+            taskPreview: "find foo",
+            toolIters: 3,
+            durationMs: 2_500,
+          },
+        },
+        {
+          ts: 1_700_000_000_000,
+          session: "s",
+          model: "deepseek-chat",
+          promptTokens: 200,
+          completionTokens: 30,
+          cacheHitTokens: 100,
+          cacheMissTokens: 100,
+          costUsd: 0.0015,
+          claudeEquivUsd: 0.015,
+          kind: "subagent",
+          subagent: {
+            skillName: "explore",
+            taskPreview: "find bar",
+            toolIters: 2,
+            durationMs: 1_500,
+          },
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    expect(agg.subagents?.total).toBe(2);
+    expect(agg.subagents?.bySkill[0]?.skillName).toBe("explore");
+    expect(agg.subagents?.bySkill[0]?.count).toBe(2);
+    const out = renderDashboard(agg, "/tmp/fake.jsonl");
+    expect(out).toContain("subagent activity:");
+    expect(out).toContain("explore");
+    expect(out).toContain("2 run");
+  });
+
+  it("groups subagent records without a skillName under (adhoc)", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000,
+          session: null,
+          model: "deepseek-chat",
+          promptTokens: 10,
+          completionTokens: 2,
+          cacheHitTokens: 0,
+          cacheMissTokens: 10,
+          costUsd: 0.001,
+          claudeEquivUsd: 0.01,
+          kind: "subagent",
+          subagent: { taskPreview: "raw call", toolIters: 1, durationMs: 500 },
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    expect(agg.subagents?.bySkill[0]?.skillName).toBe("(adhoc)");
+  });
+
+  it("includes subagent cost in the main buckets (it's real spend)", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000 - 60_000,
+          session: "s",
+          model: "deepseek-chat",
+          promptTokens: 0,
+          completionTokens: 0,
+          cacheHitTokens: 0,
+          cacheMissTokens: 0,
+          costUsd: 0.5,
+          claudeEquivUsd: 5,
+          kind: "subagent",
+          subagent: { skillName: "explore", taskPreview: "x", toolIters: 1, durationMs: 100 },
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    expect(agg.buckets[0]?.costUsd).toBeCloseTo(0.5);
+    expect(agg.buckets[0]?.turns).toBe(1);
+  });
+
+  it("renders em-dashes for empty buckets rather than $0.000000", () => {
+    const agg = aggregateUsage(
+      [
+        {
+          ts: 1_700_000_000_000 - 365 * 24 * 60 * 60 * 1000,
+          session: null,
+          model: "deepseek-chat",
+          promptTokens: 1,
+          completionTokens: 1,
+          cacheHitTokens: 1,
+          cacheMissTokens: 0,
+          costUsd: 0.001,
+          claudeEquivUsd: 0.01,
+        },
+      ],
+      { now: 1_700_000_000_000 },
+    );
+    const out = renderDashboard(agg, "/tmp/fake.jsonl");
+    // today / week / month should all be empty because the only record
+    // is a year old. The all-time row still has a cost.
+    // Each em-dash represents an empty cell.
+    const emDashCount = (out.match(/—/g) ?? []).length;
+    expect(emDashCount).toBeGreaterThan(0);
+  });
+});

tests/user-memory.test.ts

@@ -0,0 +1,396 @@
+/**
+ * Tests for the `~/.reasonix/memory/` store and its prefix-loading
+ * composer. All I/O goes through a temp `homeDir` so the suite never
+ * touches the developer's actual memory files.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { applyProjectMemory } from "../src/project-memory.js";
+import {
+  MEMORY_INDEX_FILE,
+  MEMORY_INDEX_MAX_CHARS,
+  MemoryStore,
+  applyMemoryStack,
+  applyUserMemory,
+  projectHash,
+  sanitizeMemoryName,
+} from "../src/user-memory.js";
+
+const BASE = "You are a test assistant.";
+
+describe("user-memory", () => {
+  let home: string;
+  let projectRoot: string;
+  const originalEnv = process.env.REASONIX_MEMORY;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-umem-home-"));
+    projectRoot = mkdtempSync(join(tmpdir(), "reasonix-umem-proj-"));
+    // biome-ignore lint/performance/noDelete: avoid leaking "undefined" into env
+    delete process.env.REASONIX_MEMORY;
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(projectRoot, { recursive: true, force: true });
+    if (originalEnv === undefined) {
+      // biome-ignore lint/performance/noDelete: same
+      delete process.env.REASONIX_MEMORY;
+    } else {
+      process.env.REASONIX_MEMORY = originalEnv;
+    }
+  });
+
+  describe("sanitizeMemoryName", () => {
+    it("accepts simple identifiers", () => {
+      expect(sanitizeMemoryName("foo_bar")).toBe("foo_bar");
+      expect(sanitizeMemoryName("abc-def.9")).toBe("abc-def.9");
+      expect(sanitizeMemoryName("  padded  ")).toBe("padded");
+    });
+    it("rejects path-separator injection", () => {
+      expect(() => sanitizeMemoryName("../etc/passwd")).toThrow(/invalid memory name/);
+      expect(() => sanitizeMemoryName("foo/bar")).toThrow();
+      expect(() => sanitizeMemoryName("foo\\bar")).toThrow();
+    });
+    it("rejects leading dot / too-short / too-long names", () => {
+      expect(() => sanitizeMemoryName(".hidden")).toThrow();
+      expect(() => sanitizeMemoryName("ab")).toThrow();
+      expect(() => sanitizeMemoryName("a".repeat(41))).toThrow();
+    });
+  });
+
+  describe("projectHash", () => {
+    it("returns a stable 16-hex-char digest for the same path", () => {
+      const a = projectHash("/tmp/whatever");
+      const b = projectHash("/tmp/whatever");
+      expect(a).toBe(b);
+      expect(a).toMatch(/^[0-9a-f]{16}$/);
+    });
+    it("differs across paths", () => {
+      expect(projectHash("/tmp/a")).not.toBe(projectHash("/tmp/b"));
+    });
+  });
+
+  describe("MemoryStore basic I/O", () => {
+    it("writes a global memory and regenerates MEMORY.md", () => {
+      const store = new MemoryStore({ homeDir: home });
+      store.write({
+        name: "snake_case",
+        type: "feedback",
+        scope: "global",
+        description: "User prefers snake_case for new Python modules",
+        body: "Rule.\n\n**Why:** PEP 8.\n\n**How to apply:** new .py files default to snake_case.",
+      });
+      const file = join(home, "memory", "global", "snake_case.md");
+      expect(existsSync(file)).toBe(true);
+      const raw = readFileSync(file, "utf8");
+      expect(raw).toMatch(/^---\nname: snake_case\n/);
+      expect(raw).toContain("Rule.");
+      const indexPath = join(home, "memory", "global", MEMORY_INDEX_FILE);
+      expect(existsSync(indexPath)).toBe(true);
+      const index = readFileSync(indexPath, "utf8");
+      expect(index).toContain("[snake_case](snake_case.md)");
+      expect(index).toContain("User prefers snake_case");
+    });
+
+    it("round-trips write → read → list → delete for global scope", () => {
+      const store = new MemoryStore({ homeDir: home });
+      store.write({
+        name: "one",
+        type: "user",
+        scope: "global",
+        description: "First memory",
+        body: "content one",
+      });
+      store.write({
+        name: "two",
+        type: "reference",
+        scope: "global",
+        description: "Second memory",
+        body: "content two",
+      });
+      const listed = store.list();
+      expect(listed.map((e) => e.name).sort()).toEqual(["one", "two"]);
+
+      const one = store.read("global", "one");
+      expect(one.body).toBe("content one");
+      expect(one.type).toBe("user");
+      expect(one.description).toBe("First memory");
+      expect(one.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+
+      const removed = store.delete("global", "one");
+      expect(removed).toBe(true);
+      expect(store.list().map((e) => e.name)).toEqual(["two"]);
+
+      // MEMORY.md should no longer reference "one".
+      const index = readFileSync(join(home, "memory", "global", MEMORY_INDEX_FILE), "utf8");
+      expect(index).not.toContain("one.md");
+      expect(index).toContain("two.md");
+    });
+
+    it("returns false when deleting a nonexistent memory", () => {
+      const store = new MemoryStore({ homeDir: home });
+      expect(store.delete("global", "ghost")).toBe(false);
+    });
+
+    it("removes MEMORY.md entirely when the last memory is deleted", () => {
+      const store = new MemoryStore({ homeDir: home });
+      store.write({
+        name: "only",
+        type: "project",
+        scope: "global",
+        description: "d",
+        body: "b",
+      });
+      store.delete("global", "only");
+      const indexPath = join(home, "memory", "global", MEMORY_INDEX_FILE);
+      expect(existsSync(indexPath)).toBe(false);
+    });
+
+    it("refuses project scope without a projectRoot", () => {
+      const store = new MemoryStore({ homeDir: home });
+      expect(store.hasProjectScope()).toBe(false);
+      expect(() =>
+        store.write({
+          name: "nope",
+          type: "project",
+          scope: "project",
+          description: "d",
+          body: "b",
+        }),
+      ).toThrow(/projectRoot/);
+    });
+
+    it("routes project scope into the hashed subdir", () => {
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      expect(store.hasProjectScope()).toBe(true);
+      store.write({
+        name: "bun_build",
+        type: "project",
+        scope: "project",
+        description: "Build command is `bun run build` on this machine",
+        body: "Body here.",
+      });
+      const hashDir = join(home, "memory", projectHash(projectRoot));
+      const file = join(hashDir, "bun_build.md");
+      expect(existsSync(file)).toBe(true);
+      // Global scope dir should NOT contain the project file.
+      expect(existsSync(join(home, "memory", "global", "bun_build.md"))).toBe(false);
+    });
+
+    it("validates description / body non-empty", () => {
+      const store = new MemoryStore({ homeDir: home });
+      expect(() =>
+        store.write({ name: "x_y_z", type: "user", scope: "global", description: "", body: "b" }),
+      ).toThrow(/description/);
+      expect(() =>
+        store.write({
+          name: "x_y_z",
+          type: "user",
+          scope: "global",
+          description: "d",
+          body: " \n",
+        }),
+      ).toThrow(/body/);
+    });
+
+    it("loadIndex returns null for absent scope, content + flag for present", () => {
+      const store = new MemoryStore({ homeDir: home });
+      expect(store.loadIndex("global")).toBeNull();
+      store.write({
+        name: "x_y_z",
+        type: "user",
+        scope: "global",
+        description: "hi",
+        body: "b",
+      });
+      const idx = store.loadIndex("global");
+      expect(idx).not.toBeNull();
+      expect(idx?.truncated).toBe(false);
+      expect(idx?.content).toContain("x_y_z");
+    });
+
+    it("loadIndex truncates with a visible marker past the cap", () => {
+      const store = new MemoryStore({ homeDir: home });
+      // Write many entries so MEMORY.md crosses the cap.
+      for (let i = 0; i < 80; i++) {
+        store.write({
+          name: `entry_${String(i).padStart(3, "0")}`,
+          type: "user",
+          scope: "global",
+          description: "x".repeat(120),
+          body: "b",
+        });
+      }
+      const idx = store.loadIndex("global");
+      expect(idx?.truncated).toBe(true);
+      expect(idx?.content).toMatch(/truncated \d+ chars/);
+      expect(idx?.content.length).toBeLessThan(MEMORY_INDEX_MAX_CHARS + 64);
+    });
+
+    it("list() skips malformed frontmatter gracefully", () => {
+      const store = new MemoryStore({ homeDir: home });
+      const dir = store.dir("global");
+      writeFileSync(join(dir, "broken.md"), "no frontmatter here, just text\n", "utf8");
+      store.write({
+        name: "sane",
+        type: "user",
+        scope: "global",
+        description: "ok",
+        body: "b",
+      });
+      const entries = store.list();
+      expect(entries.map((e) => e.name).sort()).toContain("sane");
+    });
+
+    it("regenerated MEMORY.md is byte-stable for identical file sets (cache-prefix safety)", () => {
+      const storeA = new MemoryStore({ homeDir: home });
+      storeA.write({ name: "a_one", type: "user", scope: "global", description: "d1", body: "b1" });
+      storeA.write({ name: "b_two", type: "user", scope: "global", description: "d2", body: "b2" });
+      const first = readFileSync(join(home, "memory", "global", MEMORY_INDEX_FILE), "utf8");
+      // Delete + re-write in reverse order — sorted index should match.
+      storeA.delete("global", "a_one");
+      storeA.delete("global", "b_two");
+      storeA.write({ name: "b_two", type: "user", scope: "global", description: "d2", body: "b2" });
+      storeA.write({ name: "a_one", type: "user", scope: "global", description: "d1", body: "b1" });
+      const second = readFileSync(join(home, "memory", "global", MEMORY_INDEX_FILE), "utf8");
+      expect(second).toBe(first);
+    });
+  });
+
+  describe("applyUserMemory", () => {
+    it("is a no-op when both scopes are empty", () => {
+      expect(applyUserMemory(BASE, { homeDir: home, projectRoot })).toBe(BASE);
+    });
+
+    it("appends only the global block when no project memory exists", () => {
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      store.write({
+        name: "pref_one",
+        type: "user",
+        scope: "global",
+        description: "prefers tabs",
+        body: "b",
+      });
+      const out = applyUserMemory(BASE, { homeDir: home, projectRoot });
+      expect(out).toContain("# User memory — global");
+      expect(out).not.toContain("# User memory — this project");
+      expect(out).toContain("pref_one");
+    });
+
+    it("appends both blocks when both scopes populated", () => {
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      store.write({
+        name: "global_one",
+        type: "user",
+        scope: "global",
+        description: "g",
+        body: "b",
+      });
+      store.write({
+        name: "project_one",
+        type: "project",
+        scope: "project",
+        description: "p",
+        body: "b",
+      });
+      const out = applyUserMemory(BASE, { homeDir: home, projectRoot });
+      expect(out).toContain("# User memory — global");
+      expect(out).toContain("# User memory — this project");
+      expect(out).toContain("global_one");
+      expect(out).toContain("project_one");
+      // Global precedes project — stable ordering for cache hash.
+      expect(out.indexOf("global_one")).toBeLessThan(out.indexOf("project_one"));
+    });
+
+    it("is deterministic — identical state ⇒ identical output (cache-safe)", () => {
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      store.write({
+        name: "stable",
+        type: "user",
+        scope: "global",
+        description: "d",
+        body: "b",
+      });
+      const a = applyUserMemory(BASE, { homeDir: home, projectRoot });
+      const b = applyUserMemory(BASE, { homeDir: home, projectRoot });
+      expect(a).toBe(b);
+    });
+
+    it("respects REASONIX_MEMORY=off", () => {
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      store.write({
+        name: "pref_one",
+        type: "user",
+        scope: "global",
+        description: "d",
+        body: "b",
+      });
+      process.env.REASONIX_MEMORY = "off";
+      expect(applyUserMemory(BASE, { homeDir: home, projectRoot })).toBe(BASE);
+    });
+
+    it("skips the project block when no projectRoot is configured", () => {
+      const store = new MemoryStore({ homeDir: home });
+      store.write({
+        name: "global_only",
+        type: "user",
+        scope: "global",
+        description: "d",
+        body: "b",
+      });
+      const out = applyUserMemory(BASE, { homeDir: home });
+      expect(out).toContain("# User memory — global");
+      expect(out).not.toContain("# User memory — this project");
+    });
+  });
+
+  describe("applyMemoryStack", () => {
+    it("composes REASONIX.md → global memory → project memory", () => {
+      writeFileSync(join(projectRoot, "REASONIX.md"), "Pinned by REASONIX.md\n", "utf8");
+      // applyMemoryStack uses ~/.reasonix by default — redirect via HOME
+      // isn't portable across Windows; use the public applyUserMemory
+      // directly for the global/project part and compose manually to
+      // check ordering is what the helper produces.
+      const withProj = applyProjectMemory(BASE, projectRoot);
+      const store = new MemoryStore({ homeDir: home, projectRoot });
+      store.write({
+        name: "g_pref",
+        type: "user",
+        scope: "global",
+        description: "global pref",
+        body: "b",
+      });
+      store.write({
+        name: "p_fact",
+        type: "project",
+        scope: "project",
+        description: "project fact",
+        body: "b",
+      });
+      const out = applyUserMemory(withProj, { homeDir: home, projectRoot });
+      // Order: REASONIX.md content → global → project. Each unique
+      // string should appear, and in that order.
+      const iReasonix = out.indexOf("Pinned by REASONIX.md");
+      const iGlobal = out.indexOf("g_pref");
+      const iProject = out.indexOf("p_fact");
+      expect(iReasonix).toBeGreaterThan(BASE.length - 1);
+      expect(iGlobal).toBeGreaterThan(iReasonix);
+      expect(iProject).toBeGreaterThan(iGlobal);
+    });
+
+    it("applyMemoryStack injects no memory blocks when no memory is set", () => {
+      // No REASONIX.md, no HOME memory → no memory blocks. The bundled
+      // builtin skills (`explore`, `research`) still inject a Skills
+      // index, so we assert the absence of the memory-specific blocks
+      // rather than raw equality with BASE.
+      const out = applyMemoryStack(BASE, projectRoot);
+      expect(out).toContain(BASE);
+      expect(out).not.toMatch(/# Project memory/);
+      expect(out).not.toMatch(/# User memory/);
+    });
+  });
+});

tests/version.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for the version module — semver compare, npx detection, and
+ * the cached latest-version fetcher. Network is fully mocked: every
+ * `fetch` call goes through an injected stub so tests work offline
+ * and across CI providers without flake risk.
+ */
+
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  LATEST_CACHE_TTL_MS,
+  VERSION,
+  compareVersions,
+  getLatestVersion,
+  isNpxInstall,
+} from "../src/version.js";
+
+describe("VERSION", () => {
+  it("matches the published package.json version", () => {
+    const pkgPath = join(process.cwd(), "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    expect(VERSION).toBe(pkg.version);
+  });
+});
+
+describe("compareVersions", () => {
+  it("compares major/minor/patch numerically", () => {
+    expect(compareVersions("0.4.22", "0.4.22")).toBe(0);
+    expect(compareVersions("0.4.21", "0.4.22")).toBeLessThan(0);
+    expect(compareVersions("0.4.22", "0.4.21")).toBeGreaterThan(0);
+    expect(compareVersions("0.5.0", "0.4.99")).toBeGreaterThan(0);
+    expect(compareVersions("1.0.0", "0.99.99")).toBeGreaterThan(0);
+  });
+
+  it("treats pre-release suffix as lower than bare version", () => {
+    expect(compareVersions("0.4.22-rc.1", "0.4.22")).toBeLessThan(0);
+    expect(compareVersions("0.4.22", "0.4.22-rc.1")).toBeGreaterThan(0);
+    expect(compareVersions("0.4.22-alpha.1", "0.4.22-alpha.1")).toBe(0);
+    expect(compareVersions("0.4.22-alpha.1", "0.4.22-alpha.2")).toBeLessThan(0);
+  });
+
+  it("tolerates mismatched part counts", () => {
+    expect(compareVersions("1", "1.0.0")).toBe(0);
+    expect(compareVersions("1.2", "1.2.0")).toBe(0);
+    expect(compareVersions("1.2.0", "1.2.1")).toBeLessThan(0);
+  });
+});
+
+describe("isNpxInstall", () => {
+  const originalArgv1 = process.argv[1];
+  const originalUa = process.env.npm_config_user_agent;
+
+  afterEach(() => {
+    process.argv[1] = originalArgv1;
+    if (originalUa === undefined) {
+      // biome-ignore lint/performance/noDelete: restore missing env var exactly
+      delete process.env.npm_config_user_agent;
+    } else {
+      process.env.npm_config_user_agent = originalUa;
+    }
+  });
+
+  it("detects _npx path fragment", () => {
+    process.argv[1] = "/Users/x/.npm/_npx/abc123/node_modules/.bin/reasonix";
+    // biome-ignore lint/performance/noDelete: cover the no-env case
+    delete process.env.npm_config_user_agent;
+    expect(isNpxInstall()).toBe(true);
+  });
+
+  it("detects npx via user-agent string", () => {
+    process.argv[1] = "/usr/local/bin/reasonix";
+    process.env.npm_config_user_agent = "npx/10.2.4 npm/10.2.4 node/v20.10.0";
+    expect(isNpxInstall()).toBe(true);
+  });
+
+  it("returns false for plain global install", () => {
+    process.argv[1] = "/usr/local/lib/node_modules/reasonix/dist/cli/index.js";
+    // biome-ignore lint/performance/noDelete: cover the no-env case
+    delete process.env.npm_config_user_agent;
+    expect(isNpxInstall()).toBe(false);
+  });
+});
+
+describe("getLatestVersion", () => {
+  let home: string;
+
+  beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), "reasonix-version-"));
+  });
+
+  afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  function makeFetch(
+    body: unknown,
+    { ok = true, status = 200 }: { ok?: boolean; status?: number } = {},
+  ): typeof fetch {
+    return (async () =>
+      ({
+        ok,
+        status,
+        json: async () => body,
+      }) as unknown as Response) as typeof fetch;
+  }
+
+  it("fetches from the registry and caches the result", async () => {
+    let calls = 0;
+    const fetchImpl = (async () => {
+      calls++;
+      return { ok: true, json: async () => ({ version: "0.9.9" }) } as unknown as Response;
+    }) as typeof fetch;
+
+    const v1 = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v1).toBe("0.9.9");
+    expect(calls).toBe(1);
+
+    // Within TTL, no second network call.
+    const v2 = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v2).toBe("0.9.9");
+    expect(calls).toBe(1);
+
+    // Cache file exists and parses.
+    const cacheFile = join(home, ".reasonix", "version-cache.json");
+    expect(existsSync(cacheFile)).toBe(true);
+    const parsed = JSON.parse(readFileSync(cacheFile, "utf8"));
+    expect(parsed.version).toBe("0.9.9");
+    expect(typeof parsed.checkedAt).toBe("number");
+  });
+
+  it("force:true bypasses the cache", async () => {
+    writeFileSync(join(home, ".reasonix-cache-preseed.json"), ""); // just ensures the tmp dir is real
+    // Preseed the cache directly.
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(join(home, ".reasonix"), { recursive: true });
+    writeFileSync(
+      join(home, ".reasonix", "version-cache.json"),
+      JSON.stringify({ version: "0.1.0", checkedAt: Date.now() }),
+    );
+
+    const fetchImpl = makeFetch({ version: "0.9.9" });
+    const v = await getLatestVersion({ homeDir: home, fetchImpl, force: true });
+    expect(v).toBe("0.9.9");
+  });
+
+  it("honors an expired cache entry as stale and refetches", async () => {
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(join(home, ".reasonix"), { recursive: true });
+    writeFileSync(
+      join(home, ".reasonix", "version-cache.json"),
+      JSON.stringify({
+        version: "0.1.0",
+        checkedAt: Date.now() - LATEST_CACHE_TTL_MS - 1000,
+      }),
+    );
+    const fetchImpl = makeFetch({ version: "0.9.9" });
+    const v = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v).toBe("0.9.9");
+  });
+
+  it("returns null when fetch throws (offline)", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("ENOTFOUND");
+    }) as unknown as typeof fetch;
+    const v = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v).toBeNull();
+  });
+
+  it("returns null when the registry returns non-OK", async () => {
+    const fetchImpl = makeFetch({}, { ok: false, status: 500 });
+    const v = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v).toBeNull();
+  });
+
+  it("returns null when the body has no version string", async () => {
+    const fetchImpl = makeFetch({ notVersion: true });
+    const v = await getLatestVersion({ homeDir: home, fetchImpl });
+    expect(v).toBeNull();
+  });
+
+  it("swallows cache write failures silently", async () => {
+    // Point homeDir at a file (not a directory) — mkdirSync will
+    // fail and writeCache should ignore the error. Returned version
+    // is still the freshly fetched one.
+    const fetchImpl = makeFetch({ version: "0.9.9" });
+    const busted = join(home, "not-a-dir");
+    writeFileSync(busted, "blocker");
+    const v = await getLatestVersion({ homeDir: busted, fetchImpl });
+    expect(v).toBe("0.9.9");
+  });
+});

tests/web-tools.test.ts

@@ -0,0 +1,292 @@
+import { describe, expect, it, vi } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import {
+  formatSearchResults,
+  htmlToText,
+  parseMojeekResults,
+  registerWebTools,
+  webFetch,
+  webSearch,
+} from "../src/tools/web.js";
+
+describe("htmlToText", () => {
+  it("strips script/style/nav/footer and preserves paragraph breaks", () => {
+    const html = `
+      <html><head><title>x</title><style>body{color:red}</style></head>
+      <body>
+        <nav><a>skip</a></nav>
+        <p>Hello <strong>world</strong>.</p>
+        <p>Second paragraph.</p>
+        <script>evil()</script>
+        <footer>fine print</footer>
+      </body></html>
+    `;
+    const out = htmlToText(html);
+    expect(out).toContain("Hello world.");
+    expect(out).toContain("Second paragraph.");
+    expect(out).not.toContain("evil");
+    expect(out).not.toContain("skip");
+    expect(out).not.toContain("fine print");
+    expect(out).not.toContain("color:red");
+    expect(out).toMatch(/Hello world\.\n\nSecond paragraph\./);
+  });
+
+  it("decodes the common entities", () => {
+    expect(htmlToText("<p>a &amp; b &lt;c&gt; &quot;d&quot;</p>")).toContain('a & b <c> "d"');
+  });
+
+  it("collapses whitespace runs but keeps paragraph breaks", () => {
+    const out = htmlToText("<p>one    two</p><p>three</p>");
+    expect(out).toBe("one two\n\nthree");
+  });
+});
+
+describe("parseMojeekResults", () => {
+  // Fixture mirrors the shape Mojeek actually returns as of April 2026.
+  const sampleHtml = `
+    <ul class="results">
+      <li>
+        <a title="https://example.com/a" href="https://example.com/a" class="ob">
+          <p class="i"><span class="url">https://example.com</span></p>
+        </a>
+        <h2>
+          <a class="title" title="https://example.com/a" href="https://example.com/a">
+            Flutter 3.19 release notes
+          </a>
+        </h2>
+        <p class="s">
+          Flutter 3.19 introduces <strong>new Navigator</strong>&nbsp;APIs &amp; more.
+        </p>
+      </li>
+      <li>
+        <a href="https://medium.com/flutter/x" class="ob">
+          <p class="i"><span class="url">medium.com</span></p>
+        </a>
+        <h2>
+          <a class="title" href="https://medium.com/flutter/x">What's new in 3.19</a>
+        </h2>
+        <p class="s">An overview post.</p>
+      </li>
+    </ul>
+  `;
+
+  it("extracts title/url/snippet from the expected markup", () => {
+    const items = parseMojeekResults(sampleHtml);
+    expect(items).toHaveLength(2);
+    expect(items[0]).toEqual({
+      title: "Flutter 3.19 release notes",
+      url: "https://example.com/a",
+      snippet: "Flutter 3.19 introduces new Navigator APIs & more.",
+    });
+    expect(items[1]).toEqual({
+      title: "What's new in 3.19",
+      url: "https://medium.com/flutter/x",
+      snippet: "An overview post.",
+    });
+  });
+
+  it("returns empty on markup that doesn't match the expected shape", () => {
+    expect(parseMojeekResults("<html><body>nothing here</body></html>")).toEqual([]);
+  });
+
+  it("tolerates attribute-order swaps (href before class)", () => {
+    const html = `
+      <a href="https://example.com/z" class="title">Title Z</a>
+      <p class="s">Snippet Z.</p>
+    `;
+    const items = parseMojeekResults(html);
+    expect(items).toHaveLength(1);
+    expect(items[0]).toEqual({
+      title: "Title Z",
+      url: "https://example.com/z",
+      snippet: "Snippet Z.",
+    });
+  });
+
+  it("handles a title with no snippet sibling (empty snippet)", () => {
+    const html = `<a class="title" href="https://example.com/s">Solo</a>`;
+    const items = parseMojeekResults(html);
+    expect(items).toHaveLength(1);
+    expect(items[0]?.snippet).toBe("");
+  });
+});
+
+describe("webSearch", () => {
+  const twoResultsHtml = `
+    <a class="title" href="https://example.com/a">A</a>
+    <p class="s">snippet A</p>
+    <a class="title" href="https://example.com/b">B</a>
+    <p class="s">snippet B</p>`;
+
+  it("GETs Mojeek with a browser UA and query string", async () => {
+    const captured: { url: string; method: string; ua: string } = { url: "", method: "", ua: "" };
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(async (url: string | URL, init?: RequestInit) => {
+      captured.url = String(url);
+      captured.method = init?.method ?? "GET";
+      const headers = (init?.headers ?? {}) as Record<string, string>;
+      captured.ua = headers["User-Agent"] ?? "";
+      return new Response(twoResultsHtml, {
+        status: 200,
+        headers: { "Content-Type": "text/html" },
+      });
+    }) as unknown as typeof fetch;
+    try {
+      const out = await webSearch("flutter 3.19", { topK: 2 });
+      expect(captured.url).toContain("mojeek.com/search");
+      expect(captured.url).toContain("q=flutter%203.19");
+      expect(captured.method).toBe("GET");
+      expect(captured.ua).toMatch(/Mozilla\/5.0/);
+      expect(out).toHaveLength(2);
+      expect(out[0]?.title).toBe("A");
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("clamps topK to [1, 10]", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () => new Response(twoResultsHtml, { status: 200 }),
+    ) as unknown as typeof fetch;
+    try {
+      const outMax = await webSearch("x", { topK: 99 });
+      expect(outMax.length).toBeLessThanOrEqual(10);
+      const outMin = await webSearch("x", { topK: 0 });
+      expect(outMin.length).toBe(1);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("throws on non-2xx", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () => new Response("blocked", { status: 429 }),
+    ) as unknown as typeof fetch;
+    try {
+      await expect(webSearch("q")).rejects.toThrow(/web_search 429/);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("returns [] on a legitimately empty 'No results' page", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response("<html><body>Your search did not match any documents.</body></html>", {
+          status: 200,
+        }),
+    ) as unknown as typeof fetch;
+    try {
+      const out = await webSearch("zzyzx nothing here");
+      expect(out).toEqual([]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("surfaces a clear error on an anti-bot interstitial", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response("<html>Please solve the captcha to continue.</html>", { status: 200 }),
+    ) as unknown as typeof fetch;
+    try {
+      await expect(webSearch("q")).rejects.toThrow(/anti-bot|rate-limited|blocked/);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("surfaces a diagnostic error when the response looks like neither empty-nor-results", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response("<html><body>totally unexpected shape</body></html>", { status: 200 }),
+    ) as unknown as typeof fetch;
+    try {
+      await expect(webSearch("q")).rejects.toThrow(/doesn't look like a real empty page/);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe("formatSearchResults", () => {
+  it("renders a query header + numbered list", () => {
+    const out = formatSearchResults("hello", [
+      { title: "One", url: "https://one", snippet: "first" },
+      { title: "Two", url: "https://two", snippet: "second" },
+    ]);
+    expect(out).toMatch(/query: hello/);
+    expect(out).toMatch(/results \(2\)/);
+    expect(out).toMatch(/1\. One\n\s+https:\/\/one\n\s+first/);
+    expect(out).toMatch(/2\. Two/);
+  });
+});
+
+describe("registerWebTools", () => {
+  it("registers web_search and web_fetch", () => {
+    const registry = new ToolRegistry();
+    registerWebTools(registry);
+    expect(registry.size).toBe(2);
+  });
+
+  it("web_fetch refuses non-http(s) urls", async () => {
+    const registry = new ToolRegistry();
+    registerWebTools(registry);
+    const out = await registry.dispatch("web_fetch", JSON.stringify({ url: "file:///etc/passwd" }));
+    expect(out).toMatch(/must start with http/);
+  });
+});
+
+describe("webFetch", () => {
+  it("extracts title + body text from an html response", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () =>
+        new Response(
+          "<html><head><title>Demo</title></head><body><p>Hello world.</p></body></html>",
+          { status: 200, headers: { "Content-Type": "text/html; charset=utf-8" } },
+        ),
+    ) as unknown as typeof fetch;
+    try {
+      const page = await webFetch("https://example.com/demo");
+      expect(page.title).toBe("Demo");
+      expect(page.text).toContain("Hello world.");
+      expect(page.text).not.toContain("<title>");
+      expect(page.truncated).toBe(false);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("truncates long pages and flags the result", async () => {
+    const originalFetch = globalThis.fetch;
+    const big = `<html><body><p>${"a".repeat(50_000)}</p></body></html>`;
+    globalThis.fetch = vi.fn(
+      async () => new Response(big, { status: 200, headers: { "Content-Type": "text/html" } }),
+    ) as unknown as typeof fetch;
+    try {
+      const page = await webFetch("https://example.com/big", { maxChars: 1000 });
+      expect(page.truncated).toBe(true);
+      expect(page.text).toMatch(/\[… truncated \d+ chars …\]$/);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("surfaces non-2xx as a thrown error", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(
+      async () => new Response("nope", { status: 404 }),
+    ) as unknown as typeof fetch;
+    try {
+      await expect(webFetch("https://example.com/missing")).rejects.toThrow(/web_fetch 404/);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});