feat: project memory — REASONIX.md pinned into the immutable prefix (0.4.17)

Drop a REASONIX.md in the project root and its contents are pinned into the system prompt every session that opens there. Cache-first: read once, hashed into the prefix fingerprint, no per-turn budget. /memory prints what's currently pinned; REASONIX_MEMORY=off opts out. Suite 517 → 542. Re-exported applyProjectMemory / readProjectMemory / memoryEnabled + PROJECT_MEMORY_FILE / PROJECT_MEMORY_MAX_CHARS for library consumers that build their own system prompt.
feat: run_command shell tool · session picker · ShellConfirm picker · backspace/markdown fixes (0.4.16)
2026-11-07 10:45:59 -10:00 · 2026-04-22 04:55:06 -07:00 · 2026-04-22 04:43:17 -07:00 · 2026-04-22 04:05:25 -07:00 · 2026-04-22 02:35:02 -07:00 · 2026-04-22 01:59:44 -07:00
62 changed files with 10982 additions and 412 deletions
@@ -9,195 +9,476 @@
 **A DeepSeek-native AI coding assistant in your terminal.** Ink TUI. MCP
 first-class. No LangChain.

-```bash
-npx reasonix
-```
-
-One command. First run walks you through a 30-second wizard (API key →
-preset → pick MCP servers from a checklist); every run after that drops
-straight into chat with your tools wired up. Inside the chat, type `/help`.
-
-Why bother with yet another agent framework? Because every abstraction
-here earns its weight against a DeepSeek-specific property — dirt-cheap
-tokens, R1 reasoning traces, automatic prefix caching, JSON mode.
-Generic wrappers treat DeepSeek as "OpenAI with a different base URL"
-and leave these advantages on the table. Reasonix leans into them:
-on the same τ-bench-lite workload,
-[**94.4% cache hit, ~40% cheaper tokens, 100% pass rate**](#validated-numbers)
-vs. a cache-hostile baseline.
-
 ---

-## What you get
+## Quick start (60 seconds)

-| Feature | How it works | Opt in |
-|---|---|---|
-| **Setup wizard** | First run of `npx reasonix`: pick preset, multi-select MCP servers from a curated catalog, saved to config so the next run just launches chat | always on (first run) |
-| **MCP (stdio + SSE)** | Multi-server bridge — every MCP tool inherits Cache-First + repair + context-safety automatically. `reasonix mcp list` shows the catalog | always on |
-| **Cache-First Loop** | Immutable prefix + append-only log = prefix byte-stable across turns → DeepSeek's automatic prefix cache hits at 70–95% | always on |
-| **Context safety net** | Tool results capped at 32k chars · oversized sessions auto-heal on load · `/compact` to shrink further · ctx gauge in the status bar · Esc to abort exploration and get a forced summary | always on |
-| **R1 Thought Harvesting** | Parses `reasoning_content` into typed `{ subgoals, hypotheses, uncertainties, rejectedPaths }` via a cheap V3 call | `/preset smart` |
-| **Self-Consistency Branching** | Runs N parallel samples at spread temperatures; picks the one with the fewest flagged uncertainties | `/preset max` / `/branch N` |
-| **Tool-Call Repair** | Auto-flattens deep/wide schemas, scavenges tool calls leaked into `<think>`, repairs truncated JSON, breaks call-storms | always on |
-| **Retry layer** | Exponential backoff + jitter on 408/429/500/502/503/504 and network errors. 4xx auth errors don't retry | always on |
-| **Ink TUI** | Live cache-hit / cost / context panel. Streams R1 thinking to a compact preview. Renders Markdown (bold / lists / code / stripped LaTeX) | always on |
+**1. Get a DeepSeek API key.** Free credit on signup:
+<https://platform.deepseek.com/api_keys>

---
-
-## Why not just use LangChain?
-
-Even on the default `fast` preset (no harvest, no branching), Reasonix bakes
-in five DeepSeek-specific defences that generic agent frameworks leave to you:
-
-| | Reasonix default | generic frameworks |
-|---|---|---|
-| Prefix-stable loop (→ 85–95% cache hit) | ✅ | ❌ prompts rebuilt each turn |
-| Auto-flatten deep tool schemas | ✅ | ❌ DeepSeek drops args |
-| Retry with jittered backoff (429/503) | ✅ | ❌ custom callbacks |
-| Scavenge tool calls leaked into `<think>` | ✅ | ❌ |
-| Call-storm breaker on identical-arg repeats | ✅ | ❌ |
-| Live cache-hit / cost / vs-Claude panel | ✅ | ❌ |
-| First-run config prompt + Markdown TUI | ✅ | ❌ |
-
-Harvest and self-consistency branching are bonuses on top. The everyday
-win is that **a plain chat with Reasonix already pays for ~40% less tokens
-than the same chat through a naive LangChain setup**, because the prefix
-actually stays byte-stable.
-
-## Validated numbers
-
-**τ-bench-lite** — 8 multi-turn tool-use tasks × 3 repeats = 48 runs per
-side. Same tools / same prompt / same client on both sides, sole variable
-is prefix stability. Measured on live DeepSeek `deepseek-chat`:
-
-| metric | baseline (cache-hostile) | Reasonix | delta |
-|---|---:|---:|---:|
-| runs | 24 | 24 | — |
-| **cache hit** | 46.6% | **94.4%** | **+47.7pp** |
-| cost / task | $0.002599 | $0.001579 | **−39% (×0.61)** |
-| vs Claude Sonnet 4.6 (token-count estimate) | — | — | **~96% cheaper** |
-| pass rate | 96% (23/24) | **100% (24/24)** | Reasonix held the guardrail on every run |
-
-**Verify it yourself — no API key, zero cost:**
-
-```bash
-git clone https://github.com/esengine/reasonix.git && cd reasonix && npm install
-npx reasonix replay benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl
-npx reasonix diff \
-  benchmarks/tau-bench/transcripts/t01_address_happy.baseline.r1.jsonl \
-  benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl
-```
-
-The JSONL transcripts committed in `benchmarks/tau-bench/transcripts/`
-carry per-turn `usage`, `cost`, and `prefixHash`. Reasonix's prefix hash
-stays byte-stable across every model call; baseline's prefix 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`][r]. Reproduce
-with your own API key: `npx tsx benchmarks/tau-bench/runner.ts --repeats 3`.
-
-[r]: ./benchmarks/tau-bench/report.md
-
-### MCP — works out of the box
-
-Any [MCP](https://spec.modelcontextprotocol.io/) server's tools inherit
-Cache-First + repair + context-safety automatically. The wizard (`npx
-reasonix`) lets you multi-select from a curated catalog — no flags, no
-JSON-by-hand. Three live reference runs:
-
-| server | turns | tool calls | cache hit | cost | vs Claude |
-|---|---:|---:|---:|---:|---:|
-| bundled demo (`add` / `echo` / `get_time`) | 2 | 1 | **96.6%** (turn 2) | $0.000254 | −94.0% |
-| official `@modelcontextprotocol/server-filesystem` | 5 | 4 | **96.7%** overall | $0.001235 | −97.0% |
-| **both concurrently** (`demo_add` + `fs_write_file`) | 5 | 4 | **81.1%** | $0.001852 | −95.9% |
-
-The third row is the ecosystem proof: two MCP servers running as
-separate subprocesses, tools from both exercised in one conversation.
-**One single prefix hash across all 5 turns** — byte-stability survives
-concurrent MCP subprocesses.
-
-Reproduce without an API key (replay the committed transcripts):
-
-```bash
-npx reasonix replay benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl
-npx reasonix replay benchmarks/tau-bench/transcripts/mcp-filesystem.jsonl
-```
-
-Supported transports: **stdio** (local `npx` or binary) and **HTTP+SSE**
-(remote / hosted servers, MCP 2024-11-05 spec). Pass an `http(s)://`
-URL to `--mcp` and Reasonix opens the SSE stream and POSTs JSON-RPC
-to the endpoint the server advertises.
-
-[mcp]: ./benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl
-
---
-
-## Usage
-
-### One command
+**2. Run it.** No install needed.

 ```bash
 npx reasonix
 ```

-First run: a wizard asks for your API key, lets you pick a preset
-(fast / smart / max), then offers a multi-select checklist of MCP
-servers — filesystem, memory, github, puppeteer, everything. Everything
-is saved to `~/.reasonix/config.json`. Subsequent runs drop straight
-into chat.
+First run walks you through a 30-second wizard:

-### Inside the chat
+- 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, …)

-A status bar at the top shows cache hit %, cost, Claude-equivalent, and
-the **context gauge** (`ctx 42k/131k (32%)` — yellow at 50%, red + a
-`/compact` nudge at 80%). A command strip under the input lists the
-slash commands:
+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.

 ```
-/help                   full list + hints
-/preset <fast|smart|max> one-tap bundles (model + harvest + branch)
-/mcp                    list attached MCP servers and tools
-/compact [cap]          shrink oversized tool results in history
-/sessions · /forget     list / delete saved sessions
-/setup                  reconfigure (exits and tells you to run `reasonix setup`)
-/clear · /exit
+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
 ```

-**Esc while thinking** — abort the current exploration and force the
-model to summarize what it already found. No more "model ran 24 tool
-calls and gave up" — you get an answer every time.
+Requires Node ≥ 18. Works on macOS, Linux, Windows (Git Bash + PowerShell).

-Sessions live as JSONL under `~/.reasonix/sessions/<name>.jsonl` —
-every message appended atomically, so killing the CLI never loses
-context. Oversized tool results auto-heal on load, so poisoning a
-session with one giant `read_file` doesn't brick your history.
+---

-### Advanced — CLI subcommands and flags
+## 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.

 ```bash
-npx reasonix setup                       # reconfigure any time
-npx reasonix chat --session work         # a different named session
-npx reasonix chat --no-session           # ephemeral — nothing persisted
+cd my-project
+npx reasonix code
+```
+
+### Walkthrough: fix a bug
+
+```
+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 直接用 === 比对。我把查询和存储都规范化为小写，并补上一条测试。
+
+src/users.ts
+<<<<<<< SEARCH
+  return users.find(u => u.email === email);
+=======
+  const needle = email.toLowerCase();
+  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();
+  });
+
+  it("is case-insensitive", () => {
+    expect(findByEmail("[email protected]")).toBeDefined();
+  });
+>>>>>>> REPLACE
+
+▸ 2 pending edits across 2 files — /apply to write · /discard to drop
+```
+
+**At this point nothing has been written to disk.** You have three
+options:
+
+- `/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 › /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.
+
+### 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:
+
+```
+reasonix code › 这个项目的路由是怎么组织的？
+assistant
+  ▸ tool<directory_tree> → (src/ tree, 47 entries)
+  ▸ tool<read_file> → (src/router.ts, 1.2 KB)
+  ▸ 路由分三层：顶层 AppRouter 注册 tab，每个 tab 用 React Router 的
+    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.
+
+### Things to try
+
+- `/tool 1` — dump the last tool call's full output (when the 400-char
+  inline clip isn't enough).
+- `/think` — see the model's full R1 reasoning for the last turn
+  (reasoner preset only).
+- `/memory` — show the project's `REASONIX.md` (see below).
+- `/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.
+
+### Project memory — `REASONIX.md`
+
+Drop a `REASONIX.md` in the project root and its contents are pinned
+into the immutable-prefix system prompt every time you launch
+`reasonix` in that directory. Good for house conventions, domain
+glossary, or 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 the lookup for CI /
+offline repro.
+
+```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
+```
+
+---
+
+## Using `reasonix` — general chat
+
+Same TUI, no filesystem tools unless you opt in via MCP. Good for
+drafting, Q&A, schema design, architecture discussions, or driving
+your own MCP servers. Sessions persist per name under
+`~/.reasonix/sessions/`.
+
+```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
+```
+
+### 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
+
+```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 "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` |
+
+---
+
+## Commands inside the session
+
+| command | what it does |
+|---|---|
+| `/help` | full command reference with hints |
+| `/status` | current model · flags · context · session |
+| `/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) |
+| `/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 |
+| `/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`:
+
+| command | what it does |
+|---|---|
+| `/apply` | commit the pending SEARCH/REPLACE blocks to disk |
+| `/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"` |
+
+**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
+- `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)
+- `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.
+- 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.
+
+### Troubleshooting: duplicate rows / ghost rendering
+
+Some Windows terminals (Git Bash / MINTTY / winpty-wrapped shells)
+don't fully implement the ANSI cursor-up escapes Ink uses to repaint
+the live spinner region. Symptom: spinners, streaming previews, or
+tool-result rows print multiple copies into scrollback instead of
+overwriting in place.
+
+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.
+
+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`.
+
+```
+you › Flutter 3.19 新加了什么？
+assistant
+  ▸ tool<web_search> → query: "Flutter 3.19 new features"
+  ▸ tool<web_fetch> → https://docs.flutter.dev/release/3-19
+  ▸ 3.19 主要新增了 …
+```
+
+Backed by **Mojeek**'s public search page — an independent web index,
+no API key, no signup, bot-friendly. Coverage on niche or very recent
+queries can be thinner than Google/Bing, but it's reliable from
+scripts and doesn't gate on cookies or sessions. (DDG was the original
+backend but it started serving anti-bot pages in 2026.)
+
+**Turn it off** (offline mode / privacy / CI):
+
+```json
+// ~/.reasonix/config.json
+{ "apiKey": "sk-…", "search": false }
+```
+
+```bash
+# Or one env var (wins over config):
+REASONIX_SEARCH=off npx reasonix
+```
+
+**Bring your own provider** (Kagi, SearXNG, Serper, an internal
+cache) — implement the two tools however you want and register them
+manually:
+
+```ts
+import { ToolRegistry } from "reasonix";
+// Register your own `web_search` / `web_fetch` on a ToolRegistry,
+// then pass it to CacheFirstLoop (or `reasonix chat --no-config`
+// with seedTools via library API).
+```
+
+Inside the session:
+
+```
+reasonix › Flutter 3.19 引入了什么新的 Navigator API？
+assistant
+  ▸ tool<web_search> → query: "Flutter 3.19 new Navigator API"
+    answer: Flutter 3.19 introduces the NavigatorObserver changes …
+    1. Flutter 3.19 Release Notes — https://docs.flutter.dev/…
+    2. What's new in Flutter 3.19 — https://medium.com/…
+  ▸ tool<web_fetch> → https://docs.flutter.dev/release/release-notes/3-19-0
+    (full page text, clipped at 32k)
+  ▸ 3.19 新增了 …
+```
+
+For advanced / self-hosted search (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:
+
+```bash
+# stdio (local subprocess)
+npx reasonix --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe"
+
+# multiple servers at once
+npx reasonix \
+  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
+  --mcp "demo=npx tsx examples/mcp-server-demo.ts"
+
+# HTTP+SSE (remote / hosted)
+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.
+
+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 setup                       # reconfigure the wizard
+npx reasonix chat --session work         # named session
+npx reasonix chat --no-session           # ephemeral
 npx reasonix run "ask anything"          # one-shot, streams to stdout
 npx reasonix stats session.jsonl         # summarize a transcript
-npx reasonix replay chat.jsonl           # scrub a transcript + rebuild cost/cache
+npx reasonix replay chat.jsonl           # rebuild cost/cache from a transcript
 npx reasonix diff a.jsonl b.jsonl --md   # compare two transcripts
-npx reasonix mcp list                    # curated MCP server catalog
+npx reasonix mcp list                    # curated MCP catalog
+npx reasonix mcp inspect <spec>          # probe a single MCP server
+npx reasonix sessions                    # list saved sessions
 ```

-Power users can still bypass config and drive Reasonix with flags:
+Common flags:

 ```bash
-npx reasonix chat \
-  --preset max \
-  --mcp "filesystem=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
-  --mcp "kb=https://mcp.example.com/sse" \
-  --transcript session.jsonl \
-  --no-config   # ignore ~/.reasonix/config.json (for CI / reproducing issues)
+--preset <fast|smart|max>   # bundle (model + harvest + branch)
+--model <id>                # explicit model id
+--harvest / --no-harvest    # R1 plan-state extraction
+--branch <N>                # self-consistency budget
+--mcp "name=cmd args…"      # attach an MCP server (repeatable)
+--transcript path.jsonl     # write a JSONL transcript on the side
+--session <name>            # named session (default: per-dir for code mode)
+--no-session                # ephemeral
+--no-config                 # ignore ~/.reasonix/config.json (CI-friendly)
 ```

-### Library
+Env vars (win over config):
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+export DEEPSEEK_BASE_URL=https://...   # optional alternate endpoint
+```
+
+---
+
+## Library usage

 ```ts
 import {
@@ -229,7 +510,7 @@ const loop = new CacheFirstLoop({
    toolSpecs: tools.specs(),
  }),
  harvest: true,
-  branch: 3, // self-consistency budget
+  branch: 3,
 });

 for await (const ev of loop.step("What is 17 + 25?")) {
@@ -238,27 +519,72 @@ for await (const ev of loop.step("What is 17 + 25?")) {
 console.log(loop.stats.summary());
 ```

-### Configuration
+`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.

-The wizard handles everything on first run. If you'd rather use env vars
-(CI, shared boxes, etc.):
+---
+
+## Why Reasonix (not LangChain)
+
+Every abstraction here earns its weight against a DeepSeek-specific
+property — dirt-cheap tokens, R1 reasoning traces, automatic prefix
+caching, JSON mode. Generic wrappers leave these on the table.
+
+| | Reasonix default | generic frameworks |
+|---|---|---|
+| Prefix-stable loop (→ 85–95% cache hit) | yes | no (prompts rebuilt each turn) |
+| Auto-flatten deep tool schemas | yes | no (DeepSeek drops args) |
+| Retry with jittered backoff (429/503) | yes | no (custom callbacks) |
+| 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:
+
+| metric | baseline (cache-hostile) | Reasonix | delta |
+|---|---:|---:|---:|
+| cache hit | 46.6% | **94.4%** | +47.7 pp |
+| cost / task | $0.002599 | $0.001579 | **−39%** |
+| pass rate | 96% (23/24) | **100% (24/24)** | — |
+
+**Verify it yourself — no API key, zero cost:**

 ```bash
-export DEEPSEEK_API_KEY=sk-...        # wins over ~/.reasonix/config.json
-export DEEPSEEK_BASE_URL=https://...  # optional alternate endpoint
+git clone https://github.com/esengine/reasonix.git && cd reasonix && npm install
+npx reasonix replay benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl
+npx reasonix diff \
+  benchmarks/tau-bench/transcripts/t01_address_happy.baseline.r1.jsonl \
+  benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl
 ```

-Get a key (free credit on signup): <https://platform.deepseek.com/api_keys>
+The committed JSONL transcripts carry per-turn `usage`, `cost`, and
+`prefixHash`. Reasonix's prefix hash stays byte-stable across every
+model call; baseline's churns on every turn. The cache delta is
+*mechanically* attributable to log stability, not to a different
+system prompt.

-Re-run `npx reasonix setup` any time to add/remove MCP servers or switch
-preset — your existing selections are pre-checked.
+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):
+
+| server | turns | cache hit | cost | vs Claude |
+|---|---:|---:|---:|---:|
+| bundled demo (`add` / `echo` / `get_time`) | 2 | **96.6%** (turn 2) | $0.000254 | −94.0% |
+| official `server-filesystem` | 5 | **96.7%** | $0.001235 | −97.0% |
+| **both concurrently** | 5 | **81.1%** | $0.001852 | −95.9% |

 ---

 ## Non-goals

 - Multi-agent orchestration (use LangGraph).
- RAG / vector stores (use LlamaIndex or do it yourself).
+- RAG / vector stores (use LlamaIndex).
 - Multi-provider abstraction (use LiteLLM).
 - Web UI / SaaS.

@@ -274,13 +600,11 @@ cd reasonix
 npm install
 npm run dev chat        # run CLI from source via tsx
 npm run build           # tsup to dist/
-npm test                # vitest (279 tests)
+npm test                # vitest (444 tests)
 npm run lint            # biome
 npm run typecheck       # tsc --noEmit
 ```

-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for internals.
-
 ---

 ## License
@@ -67,14 +67,33 @@ const TOOLS = [
    description: "Returns the server's current ISO-8601 timestamp.",
    inputSchema: { type: "object", properties: {} },
  },
+  {
+    name: "slow_count",
+    description:
+      "Counts from 1 to n with a ~300 ms pause between steps, emitting notifications/progress frames along the way. Useful for demonstrating Reasonix's progress-bar UI.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        n: { type: "integer", description: "Final number to count to (default 5, max 20)" },
+      },
+    },
+  },
 ];

-function send(msg: JsonRpcSuccess | JsonRpcError): void {
+interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+function send(msg: JsonRpcSuccess | JsonRpcError | JsonRpcNotification): void {
  // Stdio MCP framing: one JSON per line.
  process.stdout.write(`${JSON.stringify(msg)}\n`);
 }

-function handleRequest(req: JsonRpcRequest): JsonRpcSuccess | JsonRpcError | null {
+async function handleRequest(
+  req: JsonRpcRequest,
+): Promise<JsonRpcSuccess | JsonRpcError | null> {
  const id = req.id ?? null;

  switch (req.method) {
@@ -99,10 +118,15 @@ function handleRequest(req: JsonRpcRequest): JsonRpcSuccess | JsonRpcError | nul
    }

    case "tools/call": {
-      const params = (req.params ?? {}) as { name?: string; arguments?: Record<string, unknown> };
+      const params = (req.params ?? {}) as {
+        name?: string;
+        arguments?: Record<string, unknown>;
+        _meta?: { progressToken?: string | number };
+      };
      const name = params.name ?? "";
      const args = params.arguments ?? {};
-      const out = callTool(name, args);
+      const progressToken = params._meta?.progressToken;
+      const out = await callTool(name, args, progressToken);
      if (out.error) {
        return {
          jsonrpc: "2.0",
@@ -129,10 +153,11 @@ function handleRequest(req: JsonRpcRequest): JsonRpcSuccess | JsonRpcError | nul
  }
 }

-function callTool(
+async function callTool(
  name: string,
  args: Record<string, unknown>,
-): { text: string; error?: string } {
+  progressToken: string | number | undefined,
+): Promise<{ text: string; error?: string }> {
  if (name === "echo") {
    const msg = typeof args.msg === "string" ? args.msg : "";
    return { text: `echo: ${msg}` };
@@ -148,6 +173,28 @@ function callTool(
  if (name === "get_time") {
    return { text: new Date().toISOString() };
  }
+  if (name === "slow_count") {
+    // Cap at 20 so an over-eager model can't make the demo run for
+    // minutes. Default 5 gives ~1.5s which is plenty to see the bar.
+    const raw = typeof args.n === "number" ? args.n : Number(args.n);
+    const n = Number.isFinite(raw) && raw >= 1 ? Math.min(Math.floor(raw), 20) : 5;
+    for (let i = 1; i <= n; i++) {
+      await new Promise((r) => setTimeout(r, 300));
+      if (progressToken !== undefined) {
+        send({
+          jsonrpc: "2.0",
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress: i,
+            total: n,
+            message: `counting ${i} of ${n}`,
+          },
+        });
+      }
+    }
+    return { text: `counted to ${n}` };
+  }
  return { text: "", error: `unknown tool: ${name}` };
 }

@@ -168,8 +215,22 @@ function main(): void {
      });
      return;
    }
-    const resp = handleRequest(req);
-    if (resp) send(resp);
+    // Fire-and-forget: handleRequest is async so slow tools (slow_count
+    // and any future streamed-progress tools) can emit notifications
+    // between in-flight requests without blocking the reader loop. Any
+    // unexpected throw lands as an internal-error response so malformed
+    // tool logic doesn't silently hang the client.
+    handleRequest(req)
+      .then((resp) => {
+        if (resp) send(resp);
+      })
+      .catch((err) => {
+        send({
+          jsonrpc: "2.0",
+          id: req.id ?? null,
+          error: { code: -32603, message: `internal: ${(err as Error).message}` },
+        });
+      });
  });
  rl.on("close", () => process.exit(0));
 }
@@ -1,6 +1,6 @@
 {
  "name": "reasonix",
-  "version": "0.3.2",
+  "version": "0.4.17",
  "description": "DeepSeek-native agent framework: cache-first loop, R1 thought harvesting, tool-call repair.",
  "type": "module",
  "bin": {
@@ -1,15 +1,32 @@
+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";
 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 { 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";
+
+export interface ProgressInfo {
+  toolName: string;
+  progress: number;
+  total?: number;
+  message?: string;
+}

 export interface ChatOptions {
  model: string;
@@ -22,16 +39,55 @@ export interface ChatOptions {
  mcp?: string[];
  /** Global prefix — only used when a single anonymous server is given. */
  mcpPrefix?: string;
+  /**
+   * Pre-built ToolRegistry used as a seed. MCP bridges (if any) are
+   * layered on top of whatever's already registered. Used by
+   * `reasonix code` to register native filesystem tools in place of
+   * the old `npx -y @modelcontextprotocol/server-filesystem` subprocess.
+   */
+  seedTools?: ToolRegistry;
+  /**
+   * Enable SEARCH/REPLACE edit-block processing after each assistant turn.
+   * 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 {
  initialKey: string | undefined;
  tools: ToolRegistry | undefined;
  mcpSpecs: string[];
+  mcpServers: McpServerSummary[];
+  /**
+   * Shared ref the bridge's `onProgress` callback writes through.
+   * App sets `.current` to its own handler on mount so every
+   * progress frame from any bridged tool lands in the UI's
+   * `OngoingToolRow`. Ref keeps the wire-up synchronous with
+   * 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, ...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
@@ -43,6 +99,26 @@ function Root({ initialKey, tools, mcpSpecs, ...appProps }: RootProps) {
    );
  }
  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}
@@ -53,6 +129,9 @@ function Root({ initialKey, tools, mcpSpecs, ...appProps }: RootProps) {
      session={appProps.session}
      tools={tools}
      mcpSpecs={mcpSpecs}
+      mcpServers={mcpServers}
+      progressSink={progressSink}
+      codeMode={appProps.codeMode}
    />
  );
 }
@@ -65,10 +144,20 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
  const clients: McpClient[] = [];
  const successfulSpecs: string[] = [];
  const failedSpecs: Array<{ spec: string; reason: string }> = [];
-  let tools: ToolRegistry | undefined;
+  const mcpServers: McpServerSummary[] = [];
+  // Shared progress sink: the bridge's onProgress callback writes
+  // through `progressSink.current`, which App.tsx sets to its UI
+  // updater on mount. Started null so early progress frames (before
+  // the App has mounted) are dropped rather than buffered.
+  const progressSink: { current: ((info: ProgressInfo) => void) | null } = { current: null };
+  // Seed registry from the caller (e.g. reasonix code's native
+  // filesystem tools) — MCP bridges layer on top rather than
+  // replacing. When no seed AND no MCP, tools stays undefined and
+  // the loop runs as a bare chat.
+  let tools: ToolRegistry | undefined = opts.seedTools;

  if (requestedSpecs.length > 0) {
-    tools = new ToolRegistry();
+    if (!tools) tools = new ToolRegistry();
    for (const raw of requestedSpecs) {
      try {
        const spec = parseMcpSpec(raw);
@@ -83,7 +172,31 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
            : new StdioTransport({ command: spec.command, args: spec.args });
        const mcp = new McpClient({ transport });
        await mcp.initialize();
-        const bridge = await bridgeMcpTools(mcp, { registry: tools, namePrefix: prefix });
+        const bridge = await bridgeMcpTools(mcp, {
+          registry: tools,
+          namePrefix: prefix,
+          onProgress: (info) => progressSink.current?.(info),
+        });
+        // Collect resources + prompts once at startup so the /mcp
+        // slash can render them synchronously. Servers that don't
+        // support these fall through as `{supported: false}` instead
+        // of throwing — see inspectMcpServer.
+        let report: InspectionReport;
+        try {
+          report = await inspectMcpServer(mcp);
+        } catch {
+          // If the inspect call itself fails (rare — shouldn't happen
+          // since inspectMcpServer swallows -32601), synthesize a
+          // minimal report so `/mcp` still has something to render.
+          report = {
+            protocolVersion: mcp.protocolVersion,
+            serverInfo: mcp.serverInfo,
+            capabilities: mcp.serverCapabilities ?? {},
+            tools: { supported: true, items: [] },
+            resources: { supported: false, reason: "inspect failed" },
+            prompts: { supported: false, reason: "inspect failed" },
+          };
+        }
        const label = spec.name ?? "anon";
        const source =
          spec.transport === "sse" ? spec.url : `${spec.command} ${spec.args.join(" ")}`;
@@ -92,6 +205,12 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
        );
        clients.push(mcp);
        successfulSpecs.push(raw);
+        mcpServers.push({
+          label,
+          spec: raw,
+          toolCount: bridge.registeredNames.length,
+          report,
+        });
      } catch (err) {
        // Per-server failure is non-fatal: one broken server shouldn't
        // kill a chat that has working servers configured. We record
@@ -105,17 +224,55 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
        );
      }
    }
-    // If every requested server failed, drop the empty registry so the
-    // loop still runs as a bare chat instead of advertising zero tools.
-    if (successfulSpecs.length === 0) {
+    // If every requested server failed AND no seed registry was
+    // provided, drop the empty registry so the loop still runs as a
+    // bare chat instead of advertising zero tools. If the caller
+    // passed seedTools we keep the registry — the seed tools are
+    // still there and usable.
+    if (successfulSpecs.length === 0 && !opts.seedTools) {
      tools = undefined;
    }
  }
  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);
+  }
+
+  // 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} tools={tools} mcpSpecs={mcpSpecs} {...opts} />,
-    { exitOnCtrlC: true },
+    <Root
+      initialKey={initialKey}
+      tools={tools}
+      mcpSpecs={mcpSpecs}
+      mcpServers={mcpServers}
+      progressSink={progressSink}
+      sessionPreview={sessionPreview}
+      {...opts}
+    />,
+    // patchConsole:false — we never log to console during the TUI, and the
+    // patch is a known redraw-glitch source on winpty/MINTTY terminals.
+    { exitOnCtrlC: true, patchConsole: false },
  );
  try {
    await waitUntilExit();
@@ -0,0 +1,80 @@
+/**
+ * `reasonix code [dir]` — opinionated wrapper around `reasonix chat` for
+ * code-editing workflows.
+ *
+ * What it does differently from plain chat:
+ *   - Registers native filesystem tools rooted at the given directory
+ *     (CWD by default). No subprocess, no `npx install` step, R1-
+ *     friendly schemas. Replaced the old `@modelcontextprotocol/server-filesystem`
+ *     subprocess in 0.4.9 because its `edit_file` argv shape was the
+ *     biggest driver of R1 DSML hallucinations.
+ *   - Uses a coding-focused system prompt (src/code/prompt.ts) that
+ *     teaches the model to propose edits as SEARCH/REPLACE blocks.
+ *   - Defaults to the `smart` preset (reasoner + harvest) because
+ *     coding tasks pay back R1 thinking.
+ *   - Scopes its session to the directory so projects don't share
+ *     conversation history.
+ *   - Hooks `codeMode` into the TUI so assistant replies get parsed
+ *     for SEARCH/REPLACE blocks and applied on disk after each turn.
+ */
+
+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 { registerShellTools } from "../../tools/shell.js";
+import { chatCommand } from "./chat.js";
+
+export interface CodeOptions {
+  /** Directory to root the filesystem tools at. Defaults to process.cwd(). */
+  dir?: string;
+  /** Override the default `smart` model. */
+  model?: string;
+  /** Disable session persistence. */
+  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;
+}
+
+export async function codeCommand(opts: CodeOptions = {}): Promise<void> {
+  const { codeSystemPrompt } = await import("../../code/prompt.js");
+  const rootDir = resolve(opts.dir ?? process.cwd());
+  // Per-directory session so switching projects doesn't mix histories.
+  // `code-<sanitized-basename>` fits the session name rules without
+  // truncating most project names.
+  const session = opts.noSession ? undefined : `code-${sanitizeName(basename(rootDir))}`;
+
+  // Native filesystem tools. No subprocess, ~50-200 ms faster per call
+  // than the MCP server was, and `edit_file` takes a flat SEARCH/REPLACE
+  // shape instead of the `string="false"` JSON-in-string array that
+  // 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.
+    extraAllowed: loadProjectShellAllowed(rootDir),
+  });
+
+  process.stderr.write(
+    `▸ 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
+    system: codeSystemPrompt(rootDir),
+    transcript: opts.transcript,
+    session,
+    seedTools: tools,
+    codeMode: { rootDir },
+    forceResume: opts.forceResume,
+    forceNew: opts.forceNew,
+  });
+}
@@ -51,6 +51,7 @@ export async function diffCommand(opts: DiffOptions): Promise<void> {
  if (wantTui) {
    const { waitUntilExit } = render(React.createElement(DiffApp, { report }), {
      exitOnCtrlC: true,
+      patchConsole: false,
    });
    await waitUntilExit();
    return;
@@ -0,0 +1,107 @@
+/**
+ * `reasonix mcp inspect <spec>` — connect to one MCP server, list
+ * everything it exposes (tools, resources, prompts), print a
+ * human-readable summary. Useful as:
+ *   - a diagnostic tool for "does my MCP server even work?"
+ *   - a discovery tool for "what can this server do?"
+ *   - the only CLI surface for the resources+prompts methods added
+ *     in 0.4.5 (chat mode consumes tools but hasn't wired up the
+ *     other two families yet).
+ */
+
+import { McpClient } from "../../mcp/client.js";
+import { inspectMcpServer } from "../../mcp/inspect.js";
+import type { InspectionReport } from "../../mcp/inspect.js";
+import { parseMcpSpec } from "../../mcp/spec.js";
+import { SseTransport } from "../../mcp/sse.js";
+import { type McpTransport, StdioTransport } from "../../mcp/stdio.js";
+
+export interface McpInspectOptions {
+  /** The raw --mcp spec string (e.g. `fs=npx -y @modelcontextprotocol/server-filesystem .`). */
+  spec: string;
+  /** Emit JSON on stdout instead of the human-readable table. */
+  json?: boolean;
+}
+
+export async function mcpInspectCommand(opts: McpInspectOptions): Promise<void> {
+  const spec = parseMcpSpec(opts.spec);
+  const transport: McpTransport =
+    spec.transport === "sse"
+      ? new SseTransport({ url: spec.url })
+      : new StdioTransport({ command: spec.command, args: spec.args });
+  const client = new McpClient({ transport });
+  try {
+    await client.initialize();
+    const report = await inspectMcpServer(client);
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(formatReport(spec.name ?? "(anon)", report));
+    }
+  } finally {
+    await client.close();
+  }
+}
+
+function formatReport(nsName: string, r: InspectionReport): string {
+  const lines: string[] = [];
+  lines.push(`MCP server [${nsName}]`);
+  lines.push(
+    `  server     ${r.serverInfo.name || "(unknown)"}${r.serverInfo.version ? ` v${r.serverInfo.version}` : ""}`,
+  );
+  lines.push(`  protocol   ${r.protocolVersion}`);
+  const capKeys = Object.keys(r.capabilities);
+  lines.push(`  caps       ${capKeys.length > 0 ? capKeys.join(", ") : "(none advertised)"}`);
+  if (r.instructions) {
+    lines.push(`  notes      ${r.instructions.trim().slice(0, 200)}`);
+  }
+  lines.push("");
+  lines.push(formatSection("Tools", r.tools, toolLine));
+  lines.push(formatSection("Resources", r.resources, resourceLine));
+  lines.push(formatSection("Prompts", r.prompts, promptLine));
+  return lines.join("\n");
+}
+
+function formatSection<T>(
+  title: string,
+  section: { supported: true; items: T[] } | { supported: false; reason: string },
+  render: (item: T) => string,
+): string {
+  if (!section.supported) {
+    return `${title}: (not supported — ${section.reason})`;
+  }
+  if (section.items.length === 0) {
+    return `${title}: (none)`;
+  }
+  const lines = [`${title} (${section.items.length}):`];
+  for (const item of section.items) lines.push(`  ${render(item)}`);
+  return lines.join("\n");
+}
+
+function toolLine(t: { name: string; description?: string }): string {
+  const desc = t.description ? ` — ${oneLine(t.description, 80)}` : "";
+  return `· ${t.name}${desc}`;
+}
+
+function resourceLine(r: { uri: string; name: string; mimeType?: string }): string {
+  const mime = r.mimeType ? ` [${r.mimeType}]` : "";
+  return `· ${r.name}${mime}  ${r.uri}`;
+}
+
+function promptLine(p: {
+  name: string;
+  description?: string;
+  arguments?: Array<{ name: string; required?: boolean }>;
+}): string {
+  const argPart =
+    p.arguments && p.arguments.length > 0
+      ? ` (${p.arguments.map((a) => (a.required ? a.name : `${a.name}?`)).join(", ")})`
+      : "";
+  const desc = p.description ? ` — ${oneLine(p.description, 80)}` : "";
+  return `· ${p.name}${argPart}${desc}`;
+}
+
+function oneLine(s: string, max: number): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
@@ -31,6 +31,7 @@ export async function replayCommand(opts: ReplayOptions): Promise<void> {
  const pages = groupRecordsByTurn(parsed.records);
  const { waitUntilExit } = render(React.createElement(ReplayApp, { meta: parsed.meta, pages }), {
    exitOnCtrlC: true,
+    patchConsole: false,
  });
  await waitUntilExit();
 }
@@ -39,7 +39,7 @@ export async function setupCommand(_opts: SetupOptions = {}): Promise<void> {
        unmount();
      }}
    />,
-    { exitOnCtrlC: true },
+    { exitOnCtrlC: true, patchConsole: false },
  );
  await waitUntilExit();
 }
@@ -1,8 +1,11 @@
 import { Command } from "commander";
 import { readConfig } from "../config.js";
 import { VERSION } from "../index.js";
+import { applyProjectMemory } from "../project-memory.js";
 import { chatCommand } from "./commands/chat.js";
+import { codeCommand } from "./commands/code.js";
 import { diffCommand } from "./commands/diff.js";
+import { mcpInspectCommand } from "./commands/mcp-inspect.js";
 import { mcpListCommand } from "./commands/mcp.js";
 import { replayCommand } from "./commands/replay.js";
 import { runCommand } from "./commands/run.js";
@@ -35,7 +38,7 @@ program.action(async () => {
  const defaults = resolveDefaults({});
  await chatCommand({
    model: defaults.model,
-    system: DEFAULT_SYSTEM,
+    system: applyProjectMemory(DEFAULT_SYSTEM, process.cwd()),
    harvest: defaults.harvest,
    branch: defaults.branch,
    session: defaults.session,
@@ -50,6 +53,27 @@ program
    await setupCommand({});
  });

+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.",
+  )
+  .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")
+  .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,
+    });
+  });
+
 program
  .command("chat")
  .description("Interactive Ink TUI with live cache/cost panel.")
@@ -71,6 +95,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.',
@@ -94,13 +120,15 @@ program
    });
    await chatCommand({
      model: defaults.model,
-      system: opts.system,
+      system: applyProjectMemory(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,
    });
  });

@@ -140,7 +168,7 @@ program
    await runCommand({
      task,
      model: defaults.model,
-      system: opts.system,
+      system: applyProjectMemory(opts.system, process.cwd()),
      harvest: defaults.harvest,
      branch: defaults.branch,
      transcript: opts.transcript,
@@ -215,6 +243,21 @@ mcp
    mcpListCommand({ json: !!opts.json });
  });

+mcp
+  .command("inspect <spec>")
+  .description(
+    'Connect to one MCP server and print its server info + tools/resources/prompts. <spec> takes the same forms as --mcp ("name=cmd args", "cmd args", or an SSE URL).',
+  )
+  .option("--json", "Emit the full inspection report as JSON instead of the human-readable summary")
+  .action(async (spec: string, opts) => {
+    try {
+      await mcpInspectCommand({ spec, json: !!opts.json });
+    } catch (err) {
+      process.stderr.write(`mcp inspect failed: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
+  });
+
 program.command("version").description("Print Reasonix version.").action(versionCommand);

 program.parseAsync(process.argv).catch((err) => {
@@ -1,10 +1,11 @@
 import { Box, Text } from "ink";
-import React, { useEffect, useState } from "react";
+import React from "react";
 import { type TypedPlanState, isPlanStateEmpty } from "../../harvest.js";
 import type { BranchProgress, BranchSummary } from "../../loop.js";
 import type { TurnStats } from "../../telemetry.js";
 import { PlanStateBlock } from "./PlanStateBlock.js";
 import { Markdown } from "./markdown.js";
+import { useElapsedSeconds, useTick } from "./ticker.js";

 export type DisplayRole = "user" | "assistant" | "tool" | "system" | "error" | "info" | "warning";

@@ -20,6 +21,7 @@ export interface DisplayEvent {
  stats?: TurnStats;
  repair?: string;
  streaming?: boolean;
+  toolCallBuild?: { name: string; chars: number };
 }

 export const EventRow = React.memo(function EventRow({ event }: { event: DisplayEvent }) {
@@ -54,10 +56,32 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
    );
  }
  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.
+    const isError = event.text.startsWith("ERROR:");
+    const color = isError ? "red" : "yellow";
+    const marker = isError ? "✗" : "→";
+    // `edit_file` results get a dedicated diff renderer — colored
+    // line-by-line so `-` removals show red, `+` additions show
+    // green, unchanged context lines dim. Always full, never
+    // truncated: users need to see the whole change to trust
+    // /apply. Other tools keep the 400-char clip + /tool N escape.
+    const isEditFile =
+      (event.toolName === "edit_file" || event.toolName?.endsWith("_edit_file")) && !isError;
    return (
      <Box flexDirection="column" marginTop={1}>
-        <Text color="yellow">{`tool<${event.toolName ?? "?"}>  →`}</Text>
-        <Text dimColor> {truncate(event.text, 400)}</Text>
+        <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>
    );
  }
@@ -93,6 +117,61 @@ export const EventRow = React.memo(function EventRow({ event }: { event: Display
  );
 });

+/**
+ * Render the payload of an `edit_file` tool result with proper
+ * diff coloring: first line is the header ("edited X (A→B chars)"),
+ * subsequent lines are prefixed with `-` (removed), `+` (added), or
+ * space (unchanged context). Unchanged lines render dim so the
+ * changed ones pop visually. No truncation — the whole diff is
+ * shown so the user can audit what landed before `/apply` or
+ * `git diff` review.
+ */
+function EditFileDiff({ text }: { text: string }) {
+  const lines = text.split(/\r?\n/);
+  // Line 0 is the status header ("edited X (A→B chars)"), Line 1 is
+  // the unified-diff hunk header ("@@ -N,M +N,M @@"), the rest is
+  // the colored diff body. We style the two headers distinctly so
+  // the hunk marker stands out the way git-diff's cyan `@@` does in
+  // most terminals.
+  const [statusHeader, hunkHeader, ...body] = lines;
+  return (
+    <Box flexDirection="column">
+      <Text dimColor>{` ${statusHeader ?? ""}`}</Text>
+      {hunkHeader !== undefined ? (
+        <Text color="cyan" bold>
+          {hunkHeader}
+        </Text>
+      ) : null}
+      {body.map((line, i) => {
+        // Key includes the line content slice so React isn't forced
+        // to treat purely-positional identity; lines in the same
+        // diff don't reorder but could repeat (e.g. blank lines).
+        const key = `${i}-${line.slice(0, 32)}`;
+        if (line.startsWith("- ")) {
+          return (
+            <Text key={key} color="red">
+              {line}
+            </Text>
+          );
+        }
+        if (line.startsWith("+ ")) {
+          return (
+            <Text key={key} color="green">
+              {line}
+            </Text>
+          );
+        }
+        // Context line (starts with "  ") or unknown — dim.
+        return (
+          <Text key={key} dimColor>
+            {line}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}
+
 function BranchBlock({ branch }: { branch: BranchSummary }) {
  const per = branch.uncertainties
    .map((u, i) => {
@@ -114,10 +193,15 @@ function BranchBlock({ branch }: { branch: BranchSummary }) {
 }

 function ReasoningBlock({ reasoning }: { reasoning: string }) {
-  const max = 220;
+  const max = 260;
  const flat = reasoning.replace(/\s+/g, " ").trim();
+  // Show the TAIL of the reasoning rather than the head. R1 opens
+  // with generic scaffolding ("let me look at the structure...") that
+  // repeats across turns and hides the part users actually want to
+  // see — the decision right before the model commits to an action.
+  // Users can dump the full reasoning with `/think` if needed.
  const preview =
-    flat.length <= max ? flat : `${flat.slice(0, max)}… (+${flat.length - max} chars)`;
+    flat.length <= max ? flat : `… (+${flat.length - max} earlier chars) ${flat.slice(-max)}`;
  return (
    <Box marginBottom={1}>
      <Text dimColor italic>
@@ -134,12 +218,7 @@ function ReasoningBlock({ reasoning }: { reasoning: string }) {
 * the terminal viewport and leaves artifacts in scrollback.
 */
 function Elapsed() {
-  const [s, setS] = useState(0);
-  useEffect(() => {
-    const start = Date.now();
-    const id = setInterval(() => setS(Math.floor((Date.now() - start) / 1000)), 1000);
-    return () => clearInterval(id);
-  }, []);
+  const s = useElapsedSeconds();
  const mm = String(Math.floor(s / 60)).padStart(2, "0");
  const ss = String(s % 60).padStart(2, "0");
  return <Text dimColor>{`${mm}:${ss}`}</Text>;
@@ -192,16 +271,49 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {

  const tail = lastLine(event.text, 140);
  const reasoningTail = event.reasoning ? lastLine(event.reasoning, 120) : "";
+  const toolCallBuild = event.toolCallBuild;
+  // Four distinct phases a turn can be in — label them plainly so
+  // the user doesn't have to decode "streaming · 391 + think 4506
+  // chars" to figure out what's happening:
+  //   pre-first-byte: request in flight, no bytes back yet
+  //   reasoning-only: R1 thinking, no visible content yet
+  //   tool-call-only: tool_call arguments streaming, no content/reasoning bytes
+  //   writing: content streaming (R1 has already produced its thought)
+  //   both: rare — content present AND reasoning still growing
+  // We can't cheaply distinguish "reasoning still growing" from
+  // "reasoning finished but we already saw it", so when content is
+  // present we just say "writing response" and surface both counts.
+  const preFirstByte = !event.text && !event.reasoning && !toolCallBuild;
+  const reasoningOnly = !event.text && !!event.reasoning && !toolCallBuild;
+  const toolCallOnly = !event.text && !event.reasoning && !!toolCallBuild;
+  let label: string;
+  let labelColor: "yellow" | "cyan" | "green" | "magenta" | undefined;
+  if (preFirstByte) {
+    label = "request sent · waiting for server";
+    labelColor = "yellow";
+  } else if (reasoningOnly) {
+    label = `R1 reasoning · ${event.reasoning?.length ?? 0} chars of thought`;
+    labelColor = "cyan";
+  } else if (toolCallOnly) {
+    label = `assembling tool call <${toolCallBuild.name}> · ${toolCallBuild.chars} chars of arguments`;
+    labelColor = "magenta";
+  } else {
+    const parts: string[] = [`writing response · ${event.text.length} chars`];
+    if (event.reasoning) parts.push(`after ${event.reasoning.length} chars of reasoning`);
+    if (toolCallBuild) {
+      parts.push(`building tool call <${toolCallBuild.name}> · ${toolCallBuild.chars} chars`);
+    }
+    label = parts.join(" · ");
+    labelColor = "green";
+  }
  return (
    <Box flexDirection="column" marginTop={1}>
      <Box>
        <Text bold color="green">
          assistant{" "}
        </Text>
-        <Text dimColor>
-          (streaming · {event.text.length}
-          {event.reasoning ? ` + think ${event.reasoning.length}` : ""} chars){" "}
-        </Text>
+        <Pulse />
+        <Text color={labelColor}>{` ${label} `}</Text>
        <Elapsed />
      </Box>
      {reasoningTail ? (
@@ -211,15 +323,41 @@ function StreamingAssistant({ event }: { event: DisplayEvent }) {
      ) : null}
      {tail ? (
        <Text dimColor>▸ {tail}</Text>
-      ) : (
+      ) : preFirstByte ? (
        <Text dimColor italic>
-          {"  (waiting for first token…)"}
+          {"  connection open, first byte typically in 5-60s depending on model + load"}
        </Text>
-      )}
+      ) : reasoningOnly ? (
+        <Text color="yellow" dimColor>
+          {
+            "  R1 is thinking before it speaks — body text starts when reasoning completes (typically 20-90s)."
+          }
+        </Text>
+      ) : toolCallOnly ? (
+        <Text color="magenta" dimColor>
+          {"  tool-call arguments streaming — the model is about to dispatch a tool"}
+        </Text>
+      ) : event.reasoning ? (
+        <Text color="yellow" dimColor>
+          {"  R1 still reasoning — body text or tool call arrives when thinking completes"}
+        </Text>
+      ) : null}
    </Box>
  );
 }

+/**
+ * Blinking indicator so the user can tell the stream is alive even
+ * when the reasoner hasn't produced body text yet. Uses the shared
+ * tick (TICK_MS ≈ 120ms) scaled down 4× so the visible blink rate
+ * lands around 500ms — feels like a heartbeat, not a progress bar.
+ */
+function Pulse() {
+  const tick = useTick();
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  return <Text color="cyan">{frames[Math.floor(tick / 4) % frames.length]}</Text>;
+}
+
 function lastLine(s: string, maxChars: number): string {
  const flat = s.replace(/\s+/g, " ").trim();
  if (!flat) return "";
@@ -1,6 +1,7 @@
-import { Box, Text } from "ink";
-import TextInput from "ink-text-input";
-import React from "react";
+import { Box, Text, useInput } from "ink";
+import React, { useRef, useState } from "react";
+import { type MultilineKey, lineAndColumn, processMultilineKey } from "./multiline-keys.js";
+import { useTick } from "./ticker.js";

 export interface PromptInputProps {
  value: string;
@@ -11,10 +12,16 @@ export interface PromptInputProps {
 }

 /**
- * Keep `<TextInput>` mounted at all times and use its `focus` prop to gate
- * input. Conditionally rendering it (mount / unmount between turns) loses
- * the stdin raw-mode claim on some terminals, which silently drops
- * keystrokes after the first turn finishes.
+ * 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>`.
+ *
+ * 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,
@@ -23,21 +30,135 @@ export function PromptInput({
  disabled,
  placeholder,
 }: PromptInputProps) {
+  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 ke: MultilineKey = {
+        input,
+        return: key.return,
+        shift: key.shift,
+        ctrl: key.ctrl,
+        meta: key.meta,
+        backspace: key.backspace,
+        delete: key.delete,
+        tab: key.tab,
+        upArrow: key.upArrow,
+        downArrow: key.downArrow,
+        leftArrow: key.leftArrow,
+        rightArrow: key.rightArrow,
+        escape: key.escape,
+        pageUp: key.pageUp,
+        pageDown: key.pageDown,
+      };
+      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");
+    : (placeholder ?? "type a message, or /command · Ctrl+J for 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={disabled ? "gray" : "cyan"} paddingX={1}>
-      <Text bold color={disabled ? "gray" : "cyan"}>
-        you ›{" "}
-      </Text>
-      <TextInput
-        value={value}
-        onChange={onChange}
-        onSubmit={onSubmit}
-        focus={!disabled}
-        placeholder={effectivePlaceholder}
-      />
+    <Box borderStyle="round" borderColor={borderColor} paddingX={1} flexDirection="column">
+      {lines.map((line, i) => {
+        const isFirst = i === 0;
+        const showPlaceholder = isFirst && value.length === 0;
+        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}>
+            {isFirst ? (
+              <Text bold color={borderColor}>
+                you ›{" "}
+              </Text>
+            ) : (
+              <Text dimColor>{"     "}</Text>
+            )}
+            {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>
+    </>
+  );
+}
@@ -52,6 +52,8 @@ export function ReplayApp({ meta, pages }: ReplayAppProps) {
  const summary = {
    turns: cumStats.turns,
    totalCostUsd: cumStats.totalCostUsd,
+    totalInputCostUsd: cumStats.totalInputCostUsd,
+    totalOutputCostUsd: cumStats.totalOutputCostUsd,
    claudeEquivalentUsd: cumStats.claudeEquivalentUsd,
    savingsVsClaudePct: cumStats.savingsVsClaudePct,
    cacheHitRatio: cumStats.cacheHitRatio,
@@ -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);
+}
@@ -0,0 +1,105 @@
+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 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)}
+        />
+      </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;
+}
@@ -0,0 +1,85 @@
+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 SlashSuggestionsProps {
+  /**
+   * Current matching suggestions, computed by the parent. `null` means
+   * "not in slash-prefix mode" — render nothing. Empty array means "in
+   * slash mode but no matches" — render the "no matches" hint.
+   */
+  matches: SlashCommandSpec[] | null;
+  /** Index (within `matches`) of the currently highlighted row. */
+  selectedIndex: number;
+}
+
+/**
+ * Floating slash-command panel. Rendered below the input box when
+ * the user is typing a `/…` prefix. Navigation state lives in the
+ * parent (App.tsx owns `slashSelected`) so ↑/↓/Tab/Enter stay
+ * consistent with the useInput handler. This component is pure
+ * display: `matches` and `selectedIndex` come in, rows go out.
+ */
+export function SlashSuggestions({
+  matches,
+  selectedIndex,
+}: SlashSuggestionsProps): React.ReactElement | null {
+  if (matches === null) return null;
+  if (matches.length === 0) {
+    return (
+      <Box paddingX={1}>
+        <Text color="yellow">no slash command matches that prefix</Text>
+        <Text dimColor> — Backspace to edit, or /help for the full list</Text>
+      </Box>
+    );
+  }
+  // Limit rows so the suggestion list never dwarfs the rest of the
+  // UI. Keep the currently-selected row in view by sliding the
+  // window when the selection is near either edge.
+  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((spec, i) => (
+        <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>
+    </Box>
+  );
+}
+
+function SuggestionRow({ spec, isSelected }: { spec: SlashCommandSpec; isSelected: boolean }) {
+  const marker = isSelected ? "▸" : " ";
+  const name = `/${spec.cmd}`;
+  const argsSuffix = spec.argsHint ? ` ${spec.argsHint}` : "";
+  // Selected row gets full cyan coloring so it pops out against the
+  // dimmed others — mirrors the style GitHub Issues / Discord use
+  // for focused dropdown rows.
+  if (isSelected) {
+    return (
+      <Box>
+        <Text bold color="cyan">
+          {marker} {name.padEnd(12)}
+          {argsSuffix.padEnd(16)}
+        </Text>
+        <Text color="cyan"> {spec.summary}</Text>
+      </Box>
+    );
+  }
+  return (
+    <Box>
+      <Text dimColor>
+        {marker} {name.padEnd(12)}
+        {argsSuffix.padEnd(16)} {spec.summary}
+      </Text>
+    </Box>
+  );
+}
@@ -9,6 +9,15 @@ export interface StatsPanelProps {
  prefixHash: string;
  harvestOn?: boolean;
  branchBudget?: number;
+  /**
+   * Account balance fetched once at launch (and optionally refreshed
+   * per-turn by the TUI). `null` or absent hides the balance cell
+   * entirely — /user/balance failed or the user ran with `--no-config`.
+   * The top-up warning fires below 1.0 unit of whatever currency
+   * the endpoint reports so a Chinese user with CNY and a U.S. user
+   * with USD both see "getting low."
+   */
+  balance?: { currency: string; total: number } | null;
 }

 export function StatsPanel({
@@ -17,6 +26,7 @@ export function StatsPanel({
  prefixHash,
  harvestOn,
  branchBudget,
+  balance,
 }: StatsPanelProps) {
  const hitPct = (summary.cacheHitRatio * 100).toFixed(1);
  const hitColor =
@@ -52,16 +62,13 @@ export function StatsPanel({
        </Text>
        <Text>
          <Text dimColor>cost </Text>
-          <Text color="green">${summary.totalCostUsd.toFixed(6)}</Text>
-        </Text>
-        <Text>
-          <Text dimColor>vs Claude </Text>
-          <Text>${summary.claudeEquivalentUsd.toFixed(6)}</Text>
-        </Text>
-        <Text>
-          <Text dimColor>saving </Text>
          <Text color="green" bold>
-            {summary.savingsVsClaudePct.toFixed(1)}%
+            ${summary.totalCostUsd.toFixed(6)}
+          </Text>
+          <Text dimColor>
+            {" (in "}${summary.totalInputCostUsd.toFixed(6)}
+            {" · out "}${summary.totalOutputCostUsd.toFixed(6)}
+            {")"}
          </Text>
        </Text>
        {summary.lastPromptTokens > 0 ? (
@@ -79,6 +86,16 @@ export function StatsPanel({
            ) : 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>
+          </Text>
+        ) : null}
      </Box>
    </Box>
  );
@@ -144,8 +144,21 @@ 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;
+/**
+ * Split a single line into styled segments for bold / italic / inline
+ * code.
+ *
+ * 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]+?)`|(?<![*\w])\*([^*\n]+?)\*(?!\w))/g;

 function InlineMd({ text }: { text: string }) {
  const parts: React.ReactNode[] = [];
@@ -156,6 +169,11 @@ function InlineMd({ text }: { text: string }) {
    if (start > last) {
      parts.push(<Text key={`t${idx++}`}>{text.slice(last, start)}</Text>);
    }
+    // Groups, in the order they appear in INLINE_RE:
+    //   m[2] = bold content (inside ** **)
+    //   m[3] = triple-backtick content (strip leading lang tag)
+    //   m[4] = single-backtick inline code
+    //   m[5] = italic content (inside * *)
    if (m[2] !== undefined) {
      parts.push(
        <Text key={`b${idx++}`} bold>
@@ -163,17 +181,26 @@ function InlineMd({ text }: { text: string }) {
        </Text>,
      );
    } else if (m[3] !== 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[3].replace(/^(\w+)\s+/, "");
      parts.push(
        <Text key={`c${idx++}`} color="yellow">
-          {m[3]}
+          {stripped}
        </Text>,
      );
    } else if (m[4] !== undefined) {
      parts.push(
-        <Text key={`i${idx++}`} italic>
+        <Text key={`c${idx++}`} color="yellow">
          {m[4]}
        </Text>,
      );
+    } else if (m[5] !== undefined) {
+      parts.push(
+        <Text key={`i${idx++}`} italic>
+          {m[5]}
+        </Text>,
+      );
    }
    last = start + m[0].length;
  }
@@ -206,10 +233,42 @@ interface CodeBlock {
 interface HrBlock {
  kind: "hr";
 }
+// First-class Aider-style SEARCH/REPLACE block. We detect these at
+// parse time instead of routing them through the paragraph / inline
+// markdown path because the inline parser would otherwise eat `**`
+// inside JSDoc `/** ... *\/` comments and `para.join(" ")` would
+// collapse the block's newlines. Rendered as a diff so the user can
+// actually read what's about to change.
+interface EditBlockView {
+  kind: "edit-block";
+  filename: string;
+  search: string;
+  replace: string;
+}

-type Block = ParagraphBlock | HeadingBlock | BulletBlock | CodeBlock | HrBlock;
+/**
+ * GitHub-Flavored-Markdown-ish tables. We don't do alignment flags
+ * (:--- / ---:) — column-wise left-alignment is fine for a terminal
+ * and the LLM rarely specifies alignment anyway. Columns grow to
+ * fit the widest cell, with a hard cap so a pathological 200-char
+ * cell doesn't blow past the terminal width.
+ */
+interface TableBlock {
+  kind: "table";
+  header: string[];
+  rows: string[][];
+}

-function parseBlocks(raw: string): Block[] {
+type Block =
+  | ParagraphBlock
+  | HeadingBlock
+  | BulletBlock
+  | CodeBlock
+  | HrBlock
+  | EditBlockView
+  | TableBlock;
+
+export function parseBlocks(raw: string): Block[] {
  const lines = raw.split(/\r?\n/);
  const out: Block[] = [];
  let para: string[] = [];
@@ -218,6 +277,11 @@ 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(" ") });
@@ -231,25 +295,95 @@ function parseBlocks(raw: string): Block[] {
    }
  };

-  for (const rawLine of lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i]!;
    const line = rawLine.replace(/\s+$/g, "");

-    const fence = line.match(/^```(\w*)/);
-    if (fence) {
-      if (inCode) {
-        out.push({ kind: "code", lang: codeLang, text: codeBuf.join("\n") });
-        codeBuf = [];
-        codeLang = "";
-        inCode = false;
-      } else {
+    // Detect Aider-style SEARCH/REPLACE block. Matches the preceding
+    // non-blank line as the filename, then `<<<<<<< SEARCH`, content,
+    // `=======`, content, `>>>>>>> REPLACE`. We don't do markdown
+    // inside — neither the paragraph nor inline parsers should touch
+    // this content.
+    if (!inCode && /^<{7} SEARCH\s*$/.test(line)) {
+      // Filename is the previous non-blank line we just pushed to para.
+      // Pull it back out; if there isn't one, treat as literal text.
+      const filename = para.pop()?.trim();
+      if (filename) {
+        flushPara();
+        flushList();
+        let j = i + 1;
+        const searchLines: string[] = [];
+        while (j < lines.length && !/^={7}\s*$/.test(lines[j]!)) {
+          searchLines.push(lines[j]!);
+          j++;
+        }
+        const replaceLines: string[] = [];
+        let k = j + 1;
+        while (k < lines.length && !/^>{7} REPLACE\s*$/.test(lines[k]!)) {
+          replaceLines.push(lines[k]!);
+          k++;
+        }
+        if (j < lines.length && k < lines.length) {
+          out.push({
+            kind: "edit-block",
+            filename,
+            search: searchLines.join("\n"),
+            replace: replaceLines.join("\n"),
+          });
+          i = k;
+          continue;
+        }
+        // Malformed — no separator or no close. Fall through: put
+        // the filename back in the paragraph so we don't lose it.
+        para.push(filename);
+      }
+    }
+
+    // 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;
    }
@@ -275,6 +409,31 @@ 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("|")) {
+      const next = (lines[i + 1] ?? "").trim();
+      if (/^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next)) {
+        flushPara();
+        flushList();
+        const header = splitTableRow(line);
+        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;
+          rows.push(splitTableRow(r));
+          j++;
+        }
+        out.push({ kind: "table", header, rows });
+        i = j - 1;
+        continue;
+      }
+    }
+
    const bm = line.match(/^\s*[-*+]\s+(.+)$/);
    if (bm) {
      flushPara();
@@ -336,11 +495,154 @@ function BlockView({ block }: { block: Block }) {
          <Text color="yellow">{block.text}</Text>
        </Box>
      );
+    case "edit-block":
+      return <EditBlockRow block={block} />;
+    case "table":
+      return <TableBlockRow block={block} />;
    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.
+ */
+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 trimmed = masked.trim().replace(/^\||\|$/g, "");
+  return trimmed.split("|").map((c) => c.trim().replace(new RegExp(SENTINEL, "g"), "|"));
+}
+
+/**
+ * Render a GFM table as an aligned grid. Column widths are the max
+ * display length in that column, capped at 40 chars so one huge cell
+ * 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 }) {
+  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] ?? ""));
+    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">
+      <Box>
+        {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)}
+            {ci < colCount - 1 ? " │ " : ""}
+          </Text>
+        ))}
+      </Box>
+      <Text dimColor>{separator}</Text>
+      {block.rows.map((row, ri) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: table rows render in source order and don't reorder
+        <Box key={`r-${ri}`}>
+          {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)}
+              {ci < colCount - 1 ? " │ " : ""}
+            </Text>
+          ))}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+/**
+ * Terminal display width of a string, approximately. CJK characters
+ * and full-width punctuation take 2 columns; everything else is 1.
+ * Good enough for aligning table cells in a Chinese-or-English mix;
+ * real wcwidth is bigger than we need to drag in for this use case.
+ */
+function displayWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) {
+    const code = ch.codePointAt(0) ?? 0;
+    // CJK unified ideographs, full-width forms, hiragana/katakana,
+    // Hangul syllables — rough bucket, close enough for the terminal.
+    if (
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x2e80 && code <= 0x303e) ||
+      (code >= 0x3041 && code <= 0x33ff) ||
+      (code >= 0x3400 && code <= 0x4dbf) ||
+      (code >= 0x4e00 && code <= 0x9fff) ||
+      (code >= 0xa000 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe4f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6)
+    ) {
+      w += 2;
+    } else {
+      w += 1;
+    }
+  }
+  return w;
+}
+
+/**
+ * SEARCH/REPLACE rendered as a minimal diff: filename on top, red
+ * `-` lines, a gutter, green `+` lines. No inner markdown / inline
+ * parsing — content is shown verbatim so JSDoc `/**` and `*` won't
+ * be eaten by bold/italic regex.
+ *
+ * A truly empty SEARCH means "new file" and we label the filename
+ * accordingly instead of rendering an empty red half.
+ */
+function EditBlockRow({ block }: { block: EditBlockView }) {
+  const isNewFile = block.search.length === 0;
+  const searchLines = block.search.split("\n");
+  const replaceLines = block.replace.split("\n");
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingX={1}>
+      <Box>
+        <Text bold color="cyan">
+          {block.filename}
+        </Text>
+        {isNewFile ? (
+          <Text color="green" bold>
+            {" (new file)"}
+          </Text>
+        ) : null}
+      </Box>
+      {isNewFile ? null : (
+        <Box flexDirection="column" marginTop={1}>
+          {searchLines.map((line, i) => (
+            <Text key={`s-${i}-${line.length}`} color="red">
+              {`- ${line}`}
+            </Text>
+          ))}
+        </Box>
+      )}
+      <Box flexDirection="column" marginTop={isNewFile ? 1 : 0}>
+        {replaceLines.map((line, i) => (
+          <Text key={`r-${i}-${line.length}`} color="green">
+            {`+ ${line}`}
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
 export function Markdown({ text }: { text: string }) {
  const cleaned = stripMath(text);
  const blocks = React.useMemo(() => parseBlocks(cleaned), [cleaned]);
@@ -0,0 +1,199 @@
+/**
+ * Pure keystroke → action reducer for PromptInput.
+ *
+ * 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.
+ *
+ * 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 {
+  input: string;
+  return?: boolean;
+  shift?: boolean;
+  ctrl?: boolean;
+  meta?: boolean;
+  backspace?: boolean;
+  delete?: boolean;
+  tab?: boolean;
+  upArrow?: boolean;
+  downArrow?: boolean;
+  leftArrow?: boolean;
+  rightArrow?: boolean;
+  escape?: boolean;
+  pageUp?: boolean;
+  pageDown?: boolean;
+}
+
+export interface MultilineAction {
+  /** New buffer value. `null` = unchanged. */
+  next: string | null;
+  /** New cursor position (0..value.length). `null` = unchanged. */
+  cursor: number | null;
+  /** When `true`, fire `onSubmit(submitValue ?? value)`. */
+  submit: boolean;
+  submitValue?: string;
+}
+
+const BACKSLASH_SUFFIX = /\\$/;
+
+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;
+  }
+
+  // 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 insertAt(value, cursor, "\n");
+  }
+
+  if (key.return) {
+    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 };
+    }
+    return { next: null, cursor: null, submit: true, submitValue: value };
+  }
+
+  // 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,
+    };
+  }
+
+  // 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);
+  }
+
+  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);
+}
+
+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);
+}
@@ -1,5 +1,9 @@
+import { spawnSync } from "node:child_process";
 import type { CacheFirstLoop } from "../../loop.js";
+import type { InspectionReport } from "../../mcp/inspect.js";
+import { PROJECT_MEMORY_FILE, memoryEnabled, readProjectMemory } from "../../project-memory.js";
 import { deleteSession, listSessions } from "../../session.js";
+import { DEEPSEEK_CONTEXT_TOKENS, DEFAULT_CONTEXT_TOKENS } from "../../telemetry.js";

 export interface SlashResult {
  /** Text to display back to the user as a system/info line. */
@@ -10,6 +14,13 @@ export interface SlashResult {
  clear?: boolean;
  /** Unknown command — display usage hint. */
  unknown?: boolean;
+  /**
+   * Re-submit this text as a user message after displaying `info`.
+   * Used by `/retry` — the slash command truncates the log, then
+   * asks the TUI to push the original text back through the normal
+   * submit flow so a fresh turn runs.
+   */
+  resubmit?: string;
 }

 /**
@@ -25,6 +36,134 @@ export interface SlashContext {
   * omitted → no MCP servers attached.
   */
  mcpSpecs?: string[];
+  /**
+   * Callback for `/undo` — provided by the TUI when it's running in
+   * code mode. Returns a human-readable report of what was restored.
+   * Absent outside code mode → `/undo` replies "not available here".
+   */
+  codeUndo?: () => string;
+  /**
+   * Callback for `/apply` — commits pending edit blocks to disk. Returns
+   * a report of what landed. Absent → `/apply` replies "nothing pending"
+   * or "not available outside code mode".
+   */
+  codeApply?: () => string;
+  /**
+   * Callback for `/discard` — drops the pending edit blocks without
+   * touching disk.
+   */
+  codeDiscard?: () => string;
+  /**
+   * Root directory passed by `reasonix code`. Enables `/commit`, which
+   * runs `git add -A && git commit` in this directory. Missing → `/commit`
+   * replies "only available in code mode".
+   */
+  codeRoot?: string;
+  /**
+   * How many edit blocks are currently pending `/apply` or `/discard`.
+   * Surfaced by `/status`. TUI populates it live from its pending ref;
+   * omitted → treat as 0 (chat-only session).
+   */
+  pendingEditCount?: number;
+  /**
+   * Callback returning every tool result seen this session in
+   * chronological order (oldest first). Powers `/tool [N]` for
+   * inspecting the full untruncated output that `EventLog` clips at
+   * 400 chars for display. Absent → `/tool` replies "not available".
+   */
+  toolHistory?: () => Array<{ toolName: string; text: string }>;
+  /**
+   * Pre-captured inspection reports for each connected MCP server.
+   * Populated once at chat startup (chat.tsx) so `/mcp` can render
+   * tools + resources + prompts synchronously without needing async
+   * handler support.
+   */
+  mcpServers?: McpServerSummary[];
+  /**
+   * Directory `/memory` should resolve `REASONIX.md` from. In code
+   * mode this is the rootDir the filesystem tools are pinned to; in
+   * plain chat this is `process.cwd()` at launch time. Absent → the
+   * TUI is running in some non-cwd context (tests) and `/memory`
+   * replies "root unknown" instead of silently reading a different dir.
+   */
+  memoryRoot?: string;
+}
+
+export interface McpServerSummary {
+  /** Short label shown in the `/mcp` output (server namespace or "anon"). */
+  label: string;
+  /** Original --mcp spec string. */
+  spec: string;
+  /** Count of tools bridged into the Reasonix registry from this server. */
+  toolCount: number;
+  /** Full inspection snapshot — used for the resources + prompts sections. */
+  report: InspectionReport;
+}
+
+/**
+ * Slash command registry. Drives `/help`, the on-type suggestion
+ * popup (`SlashSuggestions`), and auto-complete. Kept as data rather
+ * than derived from the `handleSlash` switch so summaries can be
+ * user-facing rather than code comments.
+ *
+ * `contextual` gates commands that only make sense in certain modes:
+ *   - `"code"` — only show when the TUI is running `reasonix code`
+ *   - absent → always shown
+ */
+export interface SlashCommandSpec {
+  cmd: string;
+  summary: string;
+  contextual?: "code";
+  /** If the command takes args, hint text shown after the name. */
+  argsHint?: string;
+}
+
+export const SLASH_COMMANDS: readonly SlashCommandSpec[] = [
+  { cmd: "help", summary: "show the full command reference" },
+  { cmd: "status", summary: "current model, flags, context, session" },
+  {
+    cmd: "preset",
+    argsHint: "<fast|smart|max>",
+    summary: "one-tap model + harvest + branch bundle",
+  },
+  { cmd: "model", argsHint: "<id>", summary: "switch DeepSeek model id" },
+  { cmd: "harvest", argsHint: "[on|off]", summary: "toggle Pillar-2 plan-state extraction" },
+  { cmd: "branch", argsHint: "<N|off>", summary: "run N parallel samples per turn (N>=2)" },
+  { cmd: "mcp", summary: "list MCP servers + tools attached to this session" },
+  { cmd: "tool", argsHint: "[N]", summary: "dump full output of the Nth tool call (1=latest)" },
+  { cmd: "memory", summary: "show the project's REASONIX.md (pinned into the system prompt)" },
+  { cmd: "think", summary: "dump the last turn's full R1 reasoning (reasoner only)" },
+  { cmd: "retry", summary: "truncate & resend your last message (fresh sample)" },
+  { cmd: "compact", argsHint: "[cap]", summary: "shrink oversized tool results in the log" },
+  { cmd: "sessions", summary: "list saved sessions (current marked with ▸)" },
+  { cmd: "forget", summary: "delete the current session from disk" },
+  { cmd: "setup", summary: "reminds you to exit and run `reasonix setup`" },
+  { cmd: "clear", summary: "clear visible scrollback only (log/context kept)" },
+  { cmd: "new", summary: "start a fresh conversation (clear context + scrollback)" },
+  { cmd: "exit", summary: "quit the TUI" },
+  // Code-mode only
+  { cmd: "apply", summary: "commit pending edit blocks to disk", contextual: "code" },
+  { cmd: "discard", summary: "drop pending edit blocks without writing", contextual: "code" },
+  { cmd: "undo", summary: "roll back the last applied edit batch", contextual: "code" },
+  {
+    cmd: "commit",
+    argsHint: '"msg"',
+    summary: "git add -A && git commit -m ...",
+    contextual: "code",
+  },
+];
+
+/**
+ * Filter the registry by a prefix string (without the leading `/`).
+ * Empty prefix returns the full non-contextual list (plus code-mode
+ * entries when `codeMode` is true). Case-insensitive.
+ */
+export function suggestSlashCommands(prefix: string, codeMode = false): SlashCommandSpec[] {
+  const p = prefix.toLowerCase();
+  return SLASH_COMMANDS.filter((c) => {
+    if (c.contextual === "code" && !codeMode) return false;
+    return c.cmd.startsWith(p);
+  });
 }

 export function parseSlash(text: string): { cmd: string; args: string[] } | null {
@@ -47,7 +186,22 @@ export function handleSlash(
      return { exit: true };

    case "clear":
-      return { clear: true };
+      return {
+        clear: true,
+        info: "▸ cleared visible scrollback only. Context (message log) is intact — next turn still sees everything. Use /new to start fresh, or /forget to delete the session entirely.",
+      };
+
+    case "new":
+    case "reset": {
+      // Actually drop the in-memory log + rewrite the session file
+      // so the NEXT call has no prior context. Keeps session name,
+      // model, and other config — just the conversation is reset.
+      const { dropped } = loop.clearLog();
+      return {
+        clear: true,
+        info: `▸ new conversation — dropped ${dropped} message(s) from context. Same session, fresh slate.`,
+      };
+    }

    case "help":
    case "?":
@@ -63,9 +217,18 @@ export function handleSlash(
          "  /mcp                     list MCP servers + tools attached to this session",
          "  /setup                   (exit + reconfigure) → run `reasonix setup`",
          "  /compact [cap]           shrink large tool results in history (default 4k/result)",
+          "  /think                   dump the most recent turn's full R1 reasoning (reasoner only)",
+          "  /tool [N]                list tool calls (or dump full output of #N, 1=most recent)",
+          "  /memory                  show the project's REASONIX.md (pinned into the system prompt)",
+          "  /retry                   truncate & resend your last message (fresh sample from the model)",
+          "  /apply                   (code mode) commit the pending edit blocks to disk",
+          "  /discard                 (code mode) drop pending edits without writing",
+          "  /undo                    (code mode) roll back the last applied edit batch",
+          '  /commit "msg"            (code mode) git add -A && git commit -m "msg"',
          "  /sessions                list saved sessions (current is marked with ▸)",
          "  /forget                  delete the current session from disk",
-          "  /clear                   clear displayed history (log + session kept)",
+          "  /new                     start fresh: drop all context + clear scrollback",
+          "  /clear                   clear displayed scrollback only (context kept — model still sees it)",
          "  /exit                    quit",
          "",
          "Presets:",
@@ -80,15 +243,39 @@ export function handleSlash(
      };

    case "mcp": {
+      const servers = ctx.mcpServers ?? [];
      const specs = ctx.mcpSpecs ?? [];
      const toolSpecs = loop.prefix.toolSpecs ?? [];
-      if (specs.length === 0 && toolSpecs.length === 0) {
+      if (servers.length === 0 && specs.length === 0 && toolSpecs.length === 0) {
        return {
          info:
            "no MCP servers attached. Run `reasonix setup` to pick some, " +
            'or launch with --mcp "<spec>". `reasonix mcp list` shows the catalog.',
        };
      }
+      // Rich path — we have full inspection reports, so show each
+      // server with its tools / resources / prompts grouped together.
+      if (servers.length > 0) {
+        const lines: string[] = [];
+        for (const s of servers) {
+          const { report } = s;
+          const serverName = report.serverInfo.name || "(unknown)";
+          const serverVer = report.serverInfo.version ? ` v${report.serverInfo.version}` : "";
+          lines.push(`[${s.label}] ${serverName}${serverVer}  —  ${s.spec}`);
+          lines.push(`  tools     ${s.toolCount}`);
+          appendSection(lines, "resources", report.resources);
+          appendSection(lines, "prompts  ", report.prompts);
+          lines.push("");
+        }
+        lines.push(
+          "Chat mode consumes tools today; resources+prompts are surfaced here for awareness.",
+        );
+        lines.push(
+          "Full catalog: `reasonix mcp list` · deeper diagnosis: `reasonix mcp inspect <spec>`.",
+        );
+        return { info: lines.join("\n") };
+      }
+      // Fallback — older path when the TUI hasn't populated `mcpServers`.
      const lines: string[] = [];
      if (specs.length > 0) {
        lines.push(`MCP servers (${specs.length}):`);
@@ -111,6 +298,159 @@ export function handleSlash(
          "`reasonix setup`. Changes take effect on next launch.",
      };

+    case "retry": {
+      const prev = loop.retryLastUser();
+      if (!prev) {
+        return {
+          info: "nothing to retry — no prior user message in this session's log.",
+        };
+      }
+      const preview = prev.length > 80 ? `${prev.slice(0, 80)}…` : prev;
+      return {
+        info: `▸ retrying: "${preview}"`,
+        resubmit: prev,
+      };
+    }
+
+    case "memory": {
+      if (!memoryEnabled()) {
+        return {
+          info: "project memory is disabled (REASONIX_MEMORY=off in env). Unset the var to re-enable; no REASONIX.md will be pinned in the meantime.",
+        };
+      }
+      if (!ctx.memoryRoot) {
+        return {
+          info: "no project root on this session — `/memory` needs a working directory to resolve REASONIX.md from.",
+        };
+      }
+      const mem = readProjectMemory(ctx.memoryRoot);
+      if (!mem) {
+        return {
+          info: [
+            `no ${PROJECT_MEMORY_FILE} in ${ctx.memoryRoot}.`,
+            "",
+            "Project memory is an optional file you pin notes into — project conventions,",
+            "things the model keeps forgetting, domain glossary, setup gotchas. When present,",
+            "its contents are appended to the system prompt (the immutable-prefix region)",
+            "so every turn sees it without eating per-turn context, and the prefix cache stays",
+            "warm as long as the file is stable.",
+            "",
+            `Create it with:  echo "# Project notes for Reasonix" > ${PROJECT_MEMORY_FILE}`,
+            "Re-launch (or `/new`) to pick up changes — the prefix is hashed at session start.",
+          ].join("\n"),
+        };
+      }
+      const header = mem.truncated
+        ? `▸ project memory: ${mem.path} (${mem.originalChars.toLocaleString()} chars, truncated for the prefix)`
+        : `▸ project memory: ${mem.path} (${mem.originalChars.toLocaleString()} chars)`;
+      return {
+        info: [
+          header,
+          "",
+          mem.content,
+          "",
+          "Changes take effect on the next launch or `/new` — the system prompt is hashed once per session to keep the prefix cache warm.",
+        ].join("\n"),
+      };
+    }
+
+    case "think":
+    case "reasoning": {
+      const raw = loop.scratch.reasoning;
+      if (!raw || !raw.trim()) {
+        return {
+          info:
+            "no reasoning cached. `/think` shows the full R1 thought for the most recent turn — " +
+            "only `deepseek-reasoner` produces it, and only once the turn completes.",
+        };
+      }
+      return { info: `↳ full thinking (${raw.length} chars):\n\n${raw.trim()}` };
+    }
+
+    case "tool": {
+      // EventLog truncates tool results at 400 chars for display. When
+      // the user wants to check what the model actually read (e.g. to
+      // verify it isn't hallucinating a file's contents), they need
+      // the full text. `/tool` is the escape hatch.
+      const history = ctx.toolHistory?.() ?? [];
+      if (history.length === 0) {
+        return {
+          info:
+            "no tool calls yet in this session. `/tool` lists them once the model has actually " +
+            "used a tool; `/tool N` dumps the full (untruncated) output of the Nth-most-recent.",
+        };
+      }
+      const raw = (args[0] ?? "").toLowerCase();
+      if (raw === "" || raw === "list" || raw === "ls") {
+        return { info: formatToolList(history) };
+      }
+      const n = Number.parseInt(raw, 10);
+      if (!Number.isFinite(n) || n < 1) {
+        return {
+          info: "usage: /tool [N]   (no arg → list; N=1 → most recent result in full, N=2 → previous, …)",
+        };
+      }
+      if (n > history.length) {
+        return {
+          info: `only ${history.length} tool call(s) in history — asked for #${n}. Try /tool with no arg to see the list.`,
+        };
+      }
+      const entry = history[history.length - n];
+      if (!entry) {
+        return { info: `could not read tool call #${n}` };
+      }
+      return {
+        info: `↳ tool<${entry.toolName}> #${n} (${entry.text.length} chars):\n\n${entry.text}`,
+      };
+    }
+
+    case "undo": {
+      if (!ctx.codeUndo) {
+        return {
+          info: "/undo is only available inside `reasonix code` — chat mode doesn't apply edits.",
+        };
+      }
+      return { info: ctx.codeUndo() };
+    }
+
+    case "apply": {
+      if (!ctx.codeApply) {
+        return {
+          info: "/apply is only available inside `reasonix code` (nothing to apply here).",
+        };
+      }
+      return { info: ctx.codeApply() };
+    }
+
+    case "discard": {
+      if (!ctx.codeDiscard) {
+        return {
+          info: "/discard is only available inside `reasonix code`.",
+        };
+      }
+      return { info: ctx.codeDiscard() };
+    }
+
+    case "commit": {
+      if (!ctx.codeRoot) {
+        return {
+          info: "/commit is only available inside `reasonix code` (needs a rooted git repo).",
+        };
+      }
+      // Reassemble the original argv. The parser lowercases cmd but
+      // leaves args alone, and the TUI splits on whitespace which
+      // mangles quoted messages — rejoin with spaces and strip a
+      // surrounding pair of double quotes if the user wrote them.
+      const raw = args.join(" ").trim();
+      const message = stripOuterQuotes(raw);
+      if (!message) {
+        return {
+          info: `usage: /commit "your commit message"  — runs \`git add -A && git commit -m "…"\` in ${ctx.codeRoot}`,
+        };
+      }
+      return runGitCommit(ctx.codeRoot, message);
+    }
+
    case "compact": {
      // Manual companion to the automatic heal-on-load. Re-applies
      // truncation with a tighter cap (4k chars per tool result) and
@@ -166,13 +506,31 @@ export function handleSlash(

    case "status": {
      const branchBudget = loop.branchOptions.budget ?? 1;
-      return {
-        info:
-          `model=${loop.model}  ` +
-          `harvest=${loop.harvestEnabled ? "on" : "off"}  ` +
-          `branch=${branchBudget > 1 ? branchBudget : "off"}  ` +
-          `stream=${loop.stream ? "on" : "off"}`,
-      };
+      const ctxMax = DEEPSEEK_CONTEXT_TOKENS[loop.model] ?? DEFAULT_CONTEXT_TOKENS;
+      const lastPromptTokens = loop.stats.summary().lastPromptTokens;
+      const ctxPct = ctxMax > 0 ? Math.round((lastPromptTokens / ctxMax) * 100) : 0;
+      const ctxLine =
+        lastPromptTokens > 0
+          ? `  ctx    ${compactNum(lastPromptTokens)}/${compactNum(ctxMax)} (${ctxPct}%)`
+          : "  ctx    no turns yet";
+      const pending = ctx.pendingEditCount ?? 0;
+      const sessionLine = loop.sessionName
+        ? `  session "${loop.sessionName}" · ${loop.log.length} messages in log (resumed ${loop.resumedMessageCount})`
+        : "  session (ephemeral — no persistence)";
+      const mcpCount = ctx.mcpSpecs?.length ?? 0;
+      const toolCount = loop.prefix.toolSpecs.length;
+      const mcpLine = `  mcp     ${mcpCount} server(s), ${toolCount} tool(s) in registry`;
+      const pendingLine =
+        pending > 0 ? `  edits   ${pending} pending (/apply to commit, /discard to drop)` : "";
+      const lines = [
+        `  model   ${loop.model}`,
+        `  flags   harvest=${loop.harvestEnabled ? "on" : "off"} · branch=${branchBudget > 1 ? branchBudget : "off"} · stream=${loop.stream ? "on" : "off"}`,
+        ctxLine,
+        mcpLine,
+        sessionLine,
+      ];
+      if (pendingLine) lines.push(pendingLine);
+      return { info: lines.join("\n") };
    }

    case "model": {
@@ -229,3 +587,109 @@ export function handleSlash(
      return { unknown: true, info: `unknown command: /${cmd}  (try /help)` };
  }
 }
+
+/**
+ * Render a section (resources / prompts) of an MCP inspection into a
+ * compact "name  count  items" form, collapsing when unsupported.
+ * Names-only — descriptions and full metadata live in
+ * `reasonix mcp inspect`, which is purpose-built for the deep view.
+ */
+function appendSection(
+  lines: string[],
+  label: string,
+  section:
+    | { supported: true; items: Array<{ name: string }> }
+    | { supported: false; reason: string }
+    | undefined,
+): void {
+  if (!section || !section.supported) {
+    lines.push(
+      `  ${label.trim()}    ${section?.supported === false ? "(not supported)" : "(none)"}`,
+    );
+    return;
+  }
+  const names = section.items.map((i) => i.name);
+  if (names.length === 0) {
+    lines.push(`  ${label.trim()}    (none)`);
+    return;
+  }
+  const head = names.slice(0, 5).join(", ");
+  const more = names.length > 5 ? ` +${names.length - 5} more` : "";
+  lines.push(`  ${label.trim()}    ${names.length}  [${head}${more}]`);
+}
+
+function formatToolList(history: Array<{ toolName: string; text: string }>): string {
+  const total = history.length;
+  const header = `Tool calls in this session (${total}, most recent first):`;
+  // Show the 10 most recent. Older ones are rarely what the user
+  // wants — and the help footer tells them how to reach any entry
+  // by index if they do.
+  const shown = Math.min(total, 10);
+  const lines: string[] = [header];
+  for (let i = 0; i < shown; i++) {
+    const entry = history[total - 1 - i];
+    if (!entry) continue;
+    const idx = i + 1; // 1-based from most recent
+    const flat = entry.text.replace(/\s+/g, " ").trim();
+    const preview = flat.length > 80 ? `${flat.slice(0, 80)}…` : flat;
+    const name = entry.toolName.length > 24 ? `${entry.toolName.slice(0, 23)}…` : entry.toolName;
+    lines.push(
+      `  #${String(idx).padStart(2)}  ${name.padEnd(24)}  ${String(entry.text.length).padStart(6)} chars  ${preview}`,
+    );
+  }
+  if (total > shown) {
+    lines.push(`  … (${total - shown} earlier, reach with /tool N)`);
+  }
+  lines.push("");
+  lines.push("View full output: /tool N   (N=1 → most recent)");
+  return lines.join("\n");
+}
+
+function compactNum(n: number): string {
+  if (n < 1000) return String(n);
+  const k = n / 1000;
+  return k >= 100 ? `${Math.round(k)}k` : `${k.toFixed(1)}k`;
+}
+
+function stripOuterQuotes(s: string): string {
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * Run `git add -A` then `git commit -m <message>` in `rootDir`. Returns
+ * a SlashResult with a human-scannable info line. We surface stderr on
+ * failure so the user sees exactly what git complained about (bad
+ * config, pre-commit hook rejection, nothing staged, etc.).
+ */
+function runGitCommit(rootDir: string, message: string): SlashResult {
+  const add = spawnSync("git", ["add", "-A"], { cwd: rootDir, encoding: "utf8" });
+  if (add.error || add.status !== 0) {
+    return { info: `git add failed (${add.status ?? "?"}):\n${gitTail(add)}` };
+  }
+  const commit = spawnSync("git", ["commit", "-m", message], {
+    cwd: rootDir,
+    encoding: "utf8",
+  });
+  if (commit.error || commit.status !== 0) {
+    return { info: `git commit failed (${commit.status ?? "?"}):\n${gitTail(commit)}` };
+  }
+  const firstLine = (commit.stdout || "").split(/\r?\n/)[0] ?? "";
+  return { info: `▸ committed: ${message}${firstLine ? `\n  ${firstLine}` : ""}` };
+}
+
+/**
+ * Safely extract whatever diagnostic text is available from a spawnSync
+ * result — on Windows or when cwd doesn't exist, `stderr`/`stdout` can
+ * be `undefined` and the caller has only `error.message` to go on.
+ */
+function gitTail(res: ReturnType<typeof spawnSync>): string {
+  const stderr = (res.stderr as string | undefined) ?? "";
+  const stdout = (res.stdout as string | undefined) ?? "";
+  const body = stderr.trim() || stdout.trim();
+  if (body) return body;
+  if (res.error) return (res.error as Error).message;
+  return "(no output from git)";
+}
@@ -0,0 +1,55 @@
+import React, { type ReactNode, createContext, useContext, useEffect, useState } from "react";
+
+/**
+ * Global heartbeat for every animated component (braille spinners,
+ * elapsed-seconds counters, cursor blink). A single setInterval feeds
+ * all of them instead of each component owning one. Consolidating the
+ * 5-6 independent timers that used to exist in App.tsx + EventLog.tsx +
+ * PromptInput.tsx into one source dramatically cuts the number of
+ * React re-renders per second on heavy turns and stops Ink from
+ * patching the terminal 30+ times/sec — the main amplifier of redraw
+ * artifacts on winpty/MINTTY-class Windows terminals.
+ *
+ * Resolution: `TICK_MS` (default 120). Components that want 500ms or
+ * 1s cadence just modulo the tick counter.
+ */
+export const TICK_MS = 120;
+
+const TickContext = createContext(0);
+
+export interface TickerProviderProps {
+  children: ReactNode;
+  /**
+   * When true, the provider skips the setInterval entirely — tick stays at
+   * 0, all consumers render once and never re-render from the timer. Used
+   * by PLAIN_UI mode so the cursor and any surviving spinners don't drive
+   * repaints on fragile Windows terminals.
+   */
+  disabled?: boolean;
+}
+
+export function TickerProvider({ children, disabled }: TickerProviderProps) {
+  const [tick, setTick] = useState(0);
+  useEffect(() => {
+    if (disabled) return;
+    const id = setInterval(() => setTick((t) => t + 1), TICK_MS);
+    return () => clearInterval(id);
+  }, [disabled]);
+  return <TickContext.Provider value={tick}>{children}</TickContext.Provider>;
+}
+
+/** Current global tick. Re-renders the calling component every `TICK_MS`. */
+export function useTick(): number {
+  return useContext(TickContext);
+}
+
+/**
+ * Seconds elapsed since the calling component mounted. Derived from
+ * the shared tick + a fresh Date.now() read, so no dedicated timer
+ * is needed.
+ */
+export function useElapsedSeconds(): number {
+  const [start] = useState(() => Date.now());
+  useTick(); // subscribe to the tick so we re-render
+  return Math.floor((Date.now() - start) / 1000);
+}
@@ -45,6 +45,25 @@ export interface StreamChunk {
  raw: any;
 }

+/**
+ * Response shape for DeepSeek's `/user/balance` endpoint. One entry
+ * per currency the account is funded in (typically CNY, sometimes
+ * USD). `total_balance` is the spendable figure; `granted_balance`
+ * counts promotional credits that expire, `topped_up_balance` is
+ * what the user paid for and keeps.
+ */
+export interface BalanceInfo {
+  currency: string;
+  total_balance: string;
+  granted_balance?: string;
+  topped_up_balance?: string;
+}
+
+export interface UserBalance {
+  is_available: boolean;
+  balance_infos: BalanceInfo[];
+}
+
 export interface DeepSeekClientOptions {
  apiKey?: string;
  baseUrl?: string;
@@ -92,6 +111,28 @@ export class DeepSeekClient {
    return payload;
  }

+  /**
+   * Fetch the current DeepSeek account balance. Separate endpoint
+   * from chat completions, no billing impact. Returns null on any
+   * network/auth failure so callers can gate the balance display
+   * without a hard error — the rest of the session works regardless.
+   */
+  async getBalance(opts: { signal?: AbortSignal } = {}): Promise<UserBalance | null> {
+    try {
+      const resp = await this._fetch(`${this.baseUrl}/user/balance`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: opts.signal,
+      });
+      if (!resp.ok) return null;
+      const data = (await resp.json()) as UserBalance;
+      if (!data || !Array.isArray(data.balance_infos)) return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
  async chat(opts: ChatRequestOptions): Promise<ChatResponse> {
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
@@ -0,0 +1,241 @@
+/**
+ * Aider-style SEARCH/REPLACE edit blocks.
+ *
+ * The model emits blocks in this exact shape, one or more per response:
+ *
+ *   path/to/file.ts
+ *   <<<<<<< SEARCH
+ *   exact existing lines (whitespace-sensitive)
+ *   =======
+ *   replacement lines
+ *   >>>>>>> REPLACE
+ *
+ * We chose this over unified diffs because:
+ *   - Models produce it reliably — no line-number drift.
+ *   - It tolerates multi-edit responses without ambiguity over which
+ *     hunk belongs to which file.
+ *   - Aider has years of evidence that this format works even against
+ *     weaker models than DeepSeek R1, so it's a conservative pick.
+ *
+ * The SEARCH text must match the file byte-for-byte. Empty SEARCH is a
+ * sentinel for "create new file" — the REPLACE becomes the whole file.
+ * If SEARCH doesn't match we refuse the edit and surface the failure;
+ * we do NOT guess or fuzzy-match. A wrong silent edit is worse than a
+ * missing one — the user can re-ask with the exact current content.
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export interface EditBlock {
+  /** Path as written by the model — relative to rootDir, or absolute. */
+  path: string;
+  /** Literal text to match in the target file. Empty → create new file. */
+  search: string;
+  /** Replacement text to write in place of `search`. */
+  replace: string;
+  /** Char offset in the source message where this block started. */
+  offset: number;
+}
+
+export type ApplyStatus =
+  /** Edit landed on disk. */
+  | "applied"
+  /** New file created (SEARCH was empty and file didn't exist). */
+  | "created"
+  /** File exists but SEARCH block wasn't found in its content. */
+  | "not-found"
+  /** File doesn't exist and SEARCH was non-empty (can't create without content). */
+  | "file-missing"
+  /** Path escapes rootDir — refused on safety grounds. */
+  | "path-escape"
+  /** fs write / read threw. */
+  | "error";
+
+export interface ApplyResult {
+  path: string;
+  status: ApplyStatus;
+  /** Extra detail (e.g. error message) for logs. */
+  message?: string;
+}
+
+/**
+ * One edit block per match. The regex is anchored to the 7-char marker
+ * lines because those are visually distinct and unlikely to appear in
+ * normal code.
+ *
+ * Anchored with `^` + `m` flag so the filename has to live on its own
+ * line. Keeps us from matching e.g. a JS-import string that happens to
+ * contain `<<<<<<< SEARCH` in inner text.
+ */
+// `\n?` before the =======/REPLACE separators makes the body optional:
+// empty SEARCH (new-file sentinel) works without requiring a gratuitous
+// empty line, and the same holds for empty REPLACE (file-deletion
+// semantics, not yet supported but cheaply representable).
+const BLOCK_RE = /^(\S[^\n]*)\n<{7} SEARCH\n([\s\S]*?)\n?={7}\n([\s\S]*?)\n?>{7} REPLACE/gm;
+
+export function parseEditBlocks(text: string): EditBlock[] {
+  const out: EditBlock[] = [];
+  BLOCK_RE.lastIndex = 0;
+  let m: RegExpExecArray | null = BLOCK_RE.exec(text);
+  while (m !== null) {
+    out.push({
+      path: m[1]!.trim(),
+      search: m[2]!,
+      replace: m[3]!,
+      offset: m.index,
+    });
+    m = BLOCK_RE.exec(text);
+  }
+  return out;
+}
+
+export function applyEditBlock(block: EditBlock, rootDir: string): ApplyResult {
+  const absRoot = resolve(rootDir);
+  const absTarget = resolve(absRoot, block.path);
+  // Refuse paths that escape rootDir. `resolve` normalizes `..`, so
+  // startsWith on the normalized pair is enough.
+  if (absTarget !== absRoot && !absTarget.startsWith(`${absRoot}${sep()}`)) {
+    return {
+      path: block.path,
+      status: "path-escape",
+      message: `resolved path ${absTarget} is outside rootDir ${absRoot}`,
+    };
+  }
+
+  const searchEmpty = block.search.length === 0;
+  const exists = existsSync(absTarget);
+
+  try {
+    if (!exists) {
+      if (!searchEmpty) {
+        return {
+          path: block.path,
+          status: "file-missing",
+          message: "file does not exist; to create it, use an empty SEARCH block",
+        };
+      }
+      mkdirSync(dirname(absTarget), { recursive: true });
+      writeFileSync(absTarget, block.replace, "utf8");
+      return { path: block.path, status: "created" };
+    }
+
+    const content = readFileSync(absTarget, "utf8");
+    if (searchEmpty) {
+      return {
+        path: block.path,
+        status: "not-found",
+        message: "empty SEARCH only creates new files — this file already exists",
+      };
+    }
+    const idx = content.indexOf(block.search);
+    if (idx === -1) {
+      return {
+        path: block.path,
+        status: "not-found",
+        message: "SEARCH text does not match the current file content exactly",
+      };
+    }
+    // Replace only the first occurrence — if the model needs multiple
+    // identical edits it should emit multiple blocks (each anchored by
+    // more surrounding context). Auto-expanding to replace-all is a
+    // footgun when the same string legitimately appears in several
+    // unrelated places.
+    const replaced = `${content.slice(0, idx)}${block.replace}${content.slice(idx + block.search.length)}`;
+    writeFileSync(absTarget, replaced, "utf8");
+    return { path: block.path, status: "applied" };
+  } catch (err) {
+    return { path: block.path, status: "error", message: (err as Error).message };
+  }
+}
+
+export function applyEditBlocks(blocks: EditBlock[], rootDir: string): ApplyResult[] {
+  return blocks.map((b) => applyEditBlock(b, rootDir));
+}
+
+// ---------- snapshot / restore (for /undo) ----------
+
+export interface EditSnapshot {
+  /** Path relative to rootDir, as the block named it. */
+  path: string;
+  /**
+   * File content before the edit batch was applied. `null` means the
+   * file didn't exist yet — restoring that means deleting whatever the
+   * edit created.
+   */
+  prevContent: string | null;
+}
+
+/**
+ * Capture the current state of every file an edit batch is about to
+ * touch, so `/undo` can roll back if the user doesn't like the result.
+ * De-duplicates by path because one batch can contain multiple blocks
+ * for the same file, and we only want one "before" snapshot per file.
+ */
+export function snapshotBeforeEdits(blocks: EditBlock[], rootDir: string): EditSnapshot[] {
+  const absRoot = resolve(rootDir);
+  const seen = new Set<string>();
+  const snapshots: EditSnapshot[] = [];
+  for (const b of blocks) {
+    if (seen.has(b.path)) continue;
+    seen.add(b.path);
+    const abs = resolve(absRoot, b.path);
+    if (!existsSync(abs)) {
+      snapshots.push({ path: b.path, prevContent: null });
+      continue;
+    }
+    try {
+      snapshots.push({ path: b.path, prevContent: readFileSync(abs, "utf8") });
+    } catch {
+      // Unreadable (permission / binary) — record null so we at least
+      // don't pretend the snapshot is authoritative. The restore path
+      // will treat null as "delete on undo", which is wrong in that
+      // case but the file wasn't ours to begin with.
+      snapshots.push({ path: b.path, prevContent: null });
+    }
+  }
+  return snapshots;
+}
+
+/**
+ * Restore files to their snapshotted state. Snapshots with
+ * `prevContent === null` were created by the edit, so undo = delete.
+ * Otherwise the prior content is written back, replacing whatever the
+ * edit left behind.
+ */
+export function restoreSnapshots(snapshots: EditSnapshot[], rootDir: string): ApplyResult[] {
+  const absRoot = resolve(rootDir);
+  return snapshots.map((snap) => {
+    const abs = resolve(absRoot, snap.path);
+    if (abs !== absRoot && !abs.startsWith(`${absRoot}${sep()}`)) {
+      return {
+        path: snap.path,
+        status: "path-escape",
+        message: "snapshot path escapes rootDir — refusing to restore",
+      };
+    }
+    try {
+      if (snap.prevContent === null) {
+        if (existsSync(abs)) unlinkSync(abs);
+        return {
+          path: snap.path,
+          status: "applied",
+          message: "removed (the edit had created it)",
+        };
+      }
+      writeFileSync(abs, snap.prevContent, "utf8");
+      return {
+        path: snap.path,
+        status: "applied",
+        message: "restored to pre-edit content",
+      };
+    } catch (err) {
+      return { path: snap.path, status: "error", message: (err as Error).message };
+    }
+  });
+}
+
+/** Platform separator — `\` on Windows, `/` elsewhere. */
+function sep(): string {
+  return process.platform === "win32" ? "\\" : "/";
+}
@@ -0,0 +1,102 @@
+/**
+ * System prompt used by `reasonix code`. Teaches the model:
+ *
+ *   1. It has a filesystem MCP bridge rooted at the user's CWD.
+ *   2. To modify files it emits SEARCH/REPLACE blocks (not
+ *      `write_file` — that would whole-file rewrite and kill diff
+ *      reviewability).
+ *   3. Read first, edit second — SEARCH must match byte-for-byte.
+ *   4. Be concise. The user can read a diff faster than prose.
+ *
+ * Kept short on purpose. Long system prompts eat context budget that
+ * the Cache-First Loop is trying to conserve. The SEARCH/REPLACE spec
+ * is the one unavoidable bloat; we trim everything else.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { applyProjectMemory } from "../project-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.
+
+# 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:
+- analyze, read, explore, describe, or summarize a project
+- explain how something works
+- answer a question about the code
+
+In those cases, use tools to gather what you need, then reply in prose. No SEARCH/REPLACE blocks, no file changes. If you're unsure what the user wants, ask.
+
+When you do propose edits, the user will review them and decide whether to \`/apply\` or \`/discard\`. Don't assume they'll accept — write as if each edit will be audited, because it will.
+
+# Editing files
+
+When you've been asked to change a file, output one or more SEARCH/REPLACE blocks in this exact format:
+
+path/to/file.ext
+<<<<<<< SEARCH
+exact existing lines from the file, including whitespace
+=======
+the new lines
+>>>>>>> REPLACE
+
+Rules:
+- Always read_file first so your SEARCH matches byte-for-byte. If it doesn't match, the edit is rejected and you'll have to retry with the exact current content.
+- One edit per block. Multiple blocks in one response are fine.
+- To create a new file, leave SEARCH empty:
+    path/to/new.ts
+    <<<<<<< SEARCH
+    =======
+    (whole file content here)
+    >>>>>>> REPLACE
+- 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.
+
+# 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.
+
+# 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.
+`;
+
+/**
+ * Inject the project's `.gitignore` content into the system prompt as a
+ * "respect this on top of the built-in denylist" hint. We don't parse
+ * 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.
+ *
+ * Stacking order (stable for cache prefix):
+ *   base prompt → project memory (REASONIX.md) → .gitignore block
+ */
+export function codeSystemPrompt(rootDir: string): string {
+  const withMemory = applyProjectMemory(CODE_SYSTEM_PROMPT, rootDir);
+  const gitignorePath = join(rootDir, ".gitignore");
+  if (!existsSync(gitignorePath)) return withMemory;
+  let content: string;
+  try {
+    content = readFileSync(gitignorePath, "utf8");
+  } catch {
+    return withMemory;
+  }
+  const MAX = 2000;
+  const truncated =
+    content.length > MAX
+      ? `${content.slice(0, MAX)}\n… (truncated ${content.length - MAX} chars)`
+      : content;
+  return `${withMemory}
+
+# Project .gitignore
+
+The user's repo ships this .gitignore — treat every pattern as "don't traverse or edit inside these paths unless explicitly asked":
+
+\`\`\`
+${truncated}
+\`\`\`
+`;
+}
@@ -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);
@@ -68,8 +68,12 @@ export async function harvest(
  reasoningContent: string | null | undefined,
  client?: DeepSeekClient,
  options: HarvestOptions = {},
+  signal?: AbortSignal,
 ): Promise<TypedPlanState> {
  if (!client || !reasoningContent) return emptyPlanState();
+  // Fast-path the already-aborted case so we don't burn a network
+  // round-trip for a result the caller no longer wants.
+  if (signal?.aborted) return emptyPlanState();
  const minLen = options.minReasoningLen ?? 40;
  const trimmed = reasoningContent.trim();
  if (trimmed.length < minLen) return emptyPlanState();
@@ -92,6 +96,7 @@ export async function harvest(
      responseFormat: { type: "json_object" },
      temperature: 0,
      maxTokens: 600,
+      signal,
    });
    return parsePlanState(resp.content, maxItems, maxItemLen);
  } catch {
@@ -3,7 +3,12 @@
 export { DeepSeekClient, Usage } from "./client.js";
 export type { ChatResponse, StreamChunk, DeepSeekClientOptions } from "./client.js";

-export { CacheFirstLoop, formatLoopError, healLoadedMessages } from "./loop.js";
+export {
+  CacheFirstLoop,
+  formatLoopError,
+  healLoadedMessages,
+  stripHallucinatedToolMarkup,
+} from "./loop.js";
 export type {
  CacheFirstLoopOptions,
  LoopEvent,
@@ -24,10 +29,51 @@ export type {
 export { ImmutablePrefix, AppendOnlyLog, VolatileScratch } from "./memory.js";
 export type { ImmutablePrefixOptions } from "./memory.js";

-export { ToolRegistry } from "./tools.js";
-export type { ToolDefinition } from "./tools.js";
+export {
+  PROJECT_MEMORY_FILE,
+  PROJECT_MEMORY_MAX_CHARS,
+  applyProjectMemory,
+  memoryEnabled,
+  readProjectMemory,
+} from "./project-memory.js";
+export type { ProjectMemory } from "./project-memory.js";

-export { SessionStats, costUsd, claudeEquivalentCost } from "./telemetry.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 {
+  NeedsConfirmationError,
+  formatCommandResult,
+  isAllowed,
+  registerShellTools,
+  runCommand,
+  tokenizeCommand,
+} 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,
+  costUsd,
+  inputCostUsd,
+  outputCostUsd,
+  claudeEquivalentCost,
+} from "./telemetry.js";
 export type { TurnStats, SessionSummary } from "./telemetry.js";

 export {
@@ -101,6 +147,24 @@ export {
 export type { BridgeOptions, BridgeResult, FlattenOptions } from "./mcp/registry.js";
 export { parseMcpSpec } from "./mcp/spec.js";
 export type { McpSpec, StdioMcpSpec, SseMcpSpec } from "./mcp/spec.js";
+export { inspectMcpServer } from "./mcp/inspect.js";
+export type { InspectionReport, SectionResult } from "./mcp/inspect.js";
+
+// ---------- code mode (v0.3 — `reasonix code`) ----------
+export {
+  parseEditBlocks,
+  applyEditBlock,
+  applyEditBlocks,
+  snapshotBeforeEdits,
+  restoreSnapshots,
+} from "./code/edit-blocks.js";
+export type {
+  EditBlock,
+  ApplyResult,
+  ApplyStatus,
+  EditSnapshot,
+} from "./code/edit-blocks.js";
+export { CODE_SYSTEM_PROMPT, codeSystemPrompt } from "./code/prompt.js";
 export {
  MCP_PROTOCOL_VERSION,
  isJsonRpcError,
@@ -115,6 +179,21 @@ export type {
  JsonRpcRequest,
  JsonRpcResponse,
  JsonRpcMessage,
+  McpResource,
+  McpResourceContents,
+  McpResourceContentsText,
+  McpResourceContentsBlob,
+  ListResourcesResult,
+  ReadResourceResult,
+  McpPrompt,
+  McpPromptArgument,
+  McpPromptMessage,
+  McpPromptResourceBlock,
+  ListPromptsResult,
+  GetPromptResult,
+  McpProgressHandler,
+  McpProgressInfo,
+  ProgressNotificationParams,
 } from "./mcp/types.js";

 export { fetchWithRetry } from "./retry.js";
@@ -140,4 +219,4 @@ export type {
  JSONSchema,
 } from "./types.js";

-export const VERSION = "0.3.2";
+export const VERSION = "0.4.17";
@@ -10,17 +10,46 @@ import { DEFAULT_MAX_RESULT_CHARS, truncateForModel } 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";
-import { SessionStats, type TurnStats } from "./telemetry.js";
+import {
+  DEEPSEEK_CONTEXT_TOKENS,
+  DEFAULT_CONTEXT_TOKENS,
+  SessionStats,
+  type TurnStats,
+} from "./telemetry.js";
 import { ToolRegistry } from "./tools.js";
 import type { ChatMessage, ToolCall } from "./types.js";

 export type EventRole =
  | "assistant_delta"
  | "assistant_final"
+  /**
+   * Emitted as `tool_calls[].function.arguments` streams in. A tool
+   * call with a large arguments payload produces no `content` or
+   * `reasoning_content` bytes — this is the only signal the UI has
+   * that the stream is alive during that window.
+   */
+  | "tool_call_delta"
+  /**
+   * Yielded immediately before a tool is dispatched. Lets the TUI put
+   * up a "▸ tool<X> running…" spinner while the tool's Promise is
+   * pending — otherwise the UI looks frozen whenever a tool call
+   * takes more than a few hundred ms (a big `filesystem_edit_file`
+   * is a typical trigger).
+   */
+  | "tool_start"
  | "tool"
  | "done"
  | "error"
  | "warning"
+  /**
+   * Transient "what's happening right now" indicator. Emitted during
+   * silent phases — between a tool result and the next iteration's
+   * first streaming byte, and right before harvest — so the TUI can
+   * show a spinner with explanatory text instead of looking frozen.
+   * The UI clears it on the next primary event (assistant_delta,
+   * tool_start, tool, assistant_final, error).
+   */
+  | "status"
  | "branch_start"
  | "branch_progress"
  | "branch_done";
@@ -52,12 +81,24 @@ export interface LoopEvent {
   * what it returned. Needed by `reasonix diff` to explain divergences.
   */
  toolArgs?: string;
+  /** Cumulative arguments-string length for `role === "tool_call_delta"`. */
+  toolCallArgsChars?: number;
  stats?: TurnStats;
  planState?: TypedPlanState;
  repair?: RepairReport;
  branch?: BranchSummary;
  branchProgress?: BranchProgress;
  error?: string;
+  /**
+   * True on `assistant_final` events emitted by the no-tools fallback
+   * when the loop hit its budget, was aborted, or tripped the
+   * token-context guard. Consumers that act on assistant text (notably
+   * the code-mode edit applier) MUST treat these as display-only —
+   * the model is "wrapping up," not proposing new work. Applying
+   * SEARCH/REPLACE blocks found in a forced summary caused the
+   * "analysis became edits" bug in v0.4.1 and earlier.
+   */
+  forcedSummary?: boolean;
 }

 export interface CacheFirstLoopOptions {
@@ -130,24 +171,29 @@ export class CacheFirstLoop {
  private _turn = 0;
  private _streamPreference: boolean;
  /**
-   * Set by {@link abort} to short-circuit the tool-call loop after the
-   * current iteration. Reset at the start of each `step()` so an Esc
-   * during one turn doesn't poison the next.
+   * AbortController per active turn. Threaded through the DeepSeek
+   * HTTP calls AND every tool dispatch so Esc actually cancels the
+   * in-flight network/subprocess work — not "we'll get to it after
+   * the current call finishes." Re-created at the start of each
+   * `step()` (the prior turn's signal has already fired).
   */
-  private _aborted = false;
+  private _turnAbort: AbortController = new AbortController();

  constructor(opts: CacheFirstLoopOptions) {
    this.client = opts.client;
    this.prefix = opts.prefix;
    this.tools = opts.tools ?? new ToolRegistry();
    this.model = opts.model ?? "deepseek-chat";
-    // 24 is a compromise: enough for real filesystem / MCP exploration
-    // (which legitimately chains read_file → list_directory → read_file)
-    // without letting a confused model burn unlimited cost. When this
-    // ceiling is hit the loop forces a final no-tools summary call —
-    // see the post-loop branch at the bottom of step() — so the user
-    // never sees a silent stop, just a "hit tool-call budget" summary.
-    this.maxToolIters = opts.maxToolIters ?? 24;
+    // Iter cap is a safety net, not the primary stop condition. The
+    // primary stop is the token-context guard inside step(): after
+    // every model response we check whether the prompt is already past
+    // 80% of the model's context window, and if so divert to the
+    // forced-summary path. 64 is high enough that exploration almost
+    // never exhausts it before the token guard fires first — which
+    // is the point: let the real constraint (context window) drive
+    // 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;

    // Resolve branch config first (since it forces harvest on).
    if (typeof opts.branch === "number") {
@@ -195,8 +241,18 @@ export class CacheFirstLoop {
      for (const msg of messages) this.log.append(msg);
      this.resumedMessageCount = messages.length;
      if (healedCount > 0) {
+        // Persist the healed log back to disk so the damage doesn't
+        // re-surface on the next session load — otherwise `heal →
+        // append → resume → heal → …` would keep noticing the same
+        // broken tail every restart. Non-fatal on I/O error: the
+        // in-memory log is already healed so this session still works.
+        try {
+          rewriteSession(this.sessionName, messages);
+        } catch {
+          /* disk full / perms — skip, in-memory heal still applies */
+        }
        process.stderr.write(
-          `▸ session "${this.sessionName}": healed ${healedCount} oversized tool result(s) (was ${healedFrom.toLocaleString()} chars total). Old payloads were truncated to fit DeepSeek's context window; the conversation is preserved.\n`,
+          `▸ 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`,
        );
      }
    } else {
@@ -217,7 +273,13 @@ export class CacheFirstLoop {
   */
  compact(tightCapChars = 4000): { healedCount: number; charsSaved: number } {
    const before = this.log.toMessages();
-    const { messages, healedCount, healedFrom } = healLoadedMessages(before, tightCapChars);
+    // 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);
@@ -246,6 +308,31 @@ export class CacheFirstLoop {
    }
  }

+  /**
+   * Start a fresh conversation WITHOUT exiting. Drops every message
+   * in the in-memory log AND rewrites the session file to empty so
+   * a resume won't re-hydrate the old turns. Unlike `/forget`, which
+   * deletes the session entirely, this keeps the session name and
+   * config intact — it's the "new chat" button.
+   *
+   * The immutable prefix (system prompt + tool specs) is preserved
+   * — that's the cache-first invariant, not part of the conversation.
+   * Returns the number of messages dropped so the UI can show it.
+   */
+  clearLog(): { dropped: number } {
+    const dropped = this.log.length;
+    this.log.compactInPlace([]);
+    if (this.sessionName) {
+      try {
+        rewriteSession(this.sessionName, []);
+      } catch {
+        /* disk issue shouldn't block the in-memory clear */
+      }
+    }
+    this.scratch.reset();
+    return { dropped };
+  }
+
  /**
   * Reconfigure model/harvest/branch/stream mid-session. The loop's log,
   * scratch, and stats are preserved — only the per-turn behavior changes.
@@ -284,26 +371,78 @@ export class CacheFirstLoop {
  }

  private buildMessages(pendingUser: string | null): ChatMessage[] {
-    const msgs: ChatMessage[] = [...this.prefix.toMessages(), ...this.log.toMessages()];
+    // Full tool_calls ↔ tool pairing validation. DeepSeek 400s on
+    // both sides of this contract — unpaired assistant.tool_calls
+    // ("insufficient tool messages following") OR stray tool entries
+    // ("tool must be a response to a preceding tool_calls"). A corrupted
+    // session from an earlier build can have either. Rather than
+    // applying a bunch of narrow tail-trim heuristics, rebuild the
+    // message stream through the same validator used at load time so
+    // the payload we hand to the API is well-formed by construction.
+    const healed = healLoadedMessages(this.log.toMessages(), DEFAULT_MAX_RESULT_CHARS);
+    const msgs: ChatMessage[] = [...this.prefix.toMessages(), ...healed.messages];
    if (pendingUser !== null) msgs.push({ role: "user", content: pendingUser });
    return msgs;
  }

  /**
-   * Signal the currently-running {@link step} that the user wants to
-   * stop exploring. Takes effect at the next iteration boundary — if a
-   * tool call is mid-flight it will be allowed to finish, then the
-   * loop diverts to the forced-summary path so the user gets an
-   * answer instead of a cliff. Called by the TUI on Esc.
+   * Signal the currently-running {@link step} to stop **now**. Cancels
+   * the in-flight network request (DeepSeek HTTP/SSE) AND any tool call
+   * currently dispatching (MCP `notifications/cancelled` + promise
+   * reject). The loop itself also sees `signal.aborted` at each
+   * iteration boundary and exits quickly instead of looping again.
+   * Called by the TUI on Esc.
   */
  abort(): void {
-    this._aborted = true;
+    this._turnAbort.abort();
+  }
+
+  /**
+   * Drop everything in the log after (and including) the most recent
+   * user message. Used by `/retry` so the caller can re-send that
+   * message with a fresh turn instead of layering another response on
+   * top of the prior exchange. Returns the content of the dropped user
+   * message, or `null` if there isn't one yet.
+   *
+   * Persists by rewriting the session file — otherwise the next
+   * launch would rehydrate the old exchange and `/retry` would seem
+   * to have done nothing.
+   */
+  retryLastUser(): string | null {
+    const entries = this.log.entries;
+    let lastUserIdx = -1;
+    for (let i = entries.length - 1; i >= 0; i--) {
+      if (entries[i]!.role === "user") {
+        lastUserIdx = i;
+        break;
+      }
+    }
+    if (lastUserIdx < 0) return null;
+    const raw = entries[lastUserIdx]!.content;
+    const userText = typeof raw === "string" ? raw : "";
+    // Keep everything strictly before the user message. The caller
+    // will submit the text again through the normal path, which
+    // re-appends the user turn on first successful API response.
+    const preserved = entries.slice(0, lastUserIdx).map((m) => ({ ...m }));
+    this.log.compactInPlace(preserved);
+    if (this.sessionName) {
+      try {
+        rewriteSession(this.sessionName, preserved);
+      } catch {
+        /* disk-full / perms — in-memory compaction still applies */
+      }
+    }
+    return userText;
  }

  async *step(userInput: string): AsyncGenerator<LoopEvent> {
    this._turn++;
    this.scratch.reset();
-    this._aborted = false;
+    // 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.
+    this._turnAbort = new AbortController();
+    const signal = this._turnAbort.signal;
    let pendingUser: string | null = userInput;
    const toolSpecs = this.prefix.tools();
    // 70% of the iter budget is the "you're getting close" threshold. We
@@ -313,15 +452,56 @@ export class CacheFirstLoop {
    let warnedForIterBudget = false;

    for (let iter = 0; iter < this.maxToolIters; iter++) {
-      if (this._aborted) {
+      if (signal.aborted) {
+        // Esc means "stop now" — not "stop and force another 30-90s
+        // reasoner call to produce a summary I didn't ask for". The
+        // user's mental model of cancel is immediate. We emit a
+        // synthetic assistant_final (tagged forcedSummary so the
+        // code-mode applier ignores it) with a short stopped
+        // message, then done. The prior tool outputs are still in
+        // the log if the user wants to continue — asking again
+        // will hit a warm cache and be cheap.
+        //
+        // Budget / context-guard still call forceSummaryAfterIterLimit
+        // because there the USER didn't choose to stop — we did —
+        // and leaving them staring at nothing is worse than one extra
+        // call.
        yield {
          turn: this._turn,
          role: "warning",
-          content: `aborted at iter ${iter}/${this.maxToolIters} — forcing summary from what was gathered`,
+          content: `aborted at iter ${iter}/${this.maxToolIters} — stopped without producing a summary (press ↑ + Enter or /retry to resume)`,
        };
-        yield* this.forceSummaryAfterIterLimit({ reason: "aborted" });
+        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 });
+        yield {
+          turn: this._turn,
+          role: "assistant_final",
+          content: stoppedMsg,
+          forcedSummary: true,
+        };
+        yield { turn: this._turn, role: "done", content: stoppedMsg };
        return;
      }
+      // Bridge the silence between the PREVIOUS iter's tool result and
+      // THIS iter's first streaming byte. R1 can spend 20-90s reasoning
+      // about tool output before the first delta lands, and prior to
+      // this hint the UI had nothing to render. Only emit on iter > 0
+      // because iter 0's "thinking" phase is already covered by the
+      // streaming row / StreamingAssistant's placeholder.
+      //
+      // Wording is explicit about the two things happening: the tool
+      // result IS being uploaded (it's now part of the next prompt) and
+      // the model IS thinking. Users were reading "thinking about the
+      // tool result" as the model-only phase, but the wait also covers
+      // the upload round-trip.
+      if (iter > 0) {
+        yield {
+          turn: this._turn,
+          role: "status",
+          content: "tool result uploaded · model thinking before next response…",
+        };
+      }
      if (!warnedForIterBudget && iter >= warnAt) {
        warnedForIterBudget = true;
        yield {
@@ -377,6 +557,7 @@ export class CacheFirstLoop {
              model: this.model,
              messages,
              tools: toolSpecs.length ? toolSpecs : undefined,
+              signal,
            },
            {
              ...this.branchOptions,
@@ -435,6 +616,7 @@ export class CacheFirstLoop {
            model: this.model,
            messages,
            tools: toolSpecs.length ? toolSpecs : undefined,
+            signal,
          })) {
            if (chunk.contentDelta) {
              assistantContent += chunk.contentDelta;
@@ -465,6 +647,16 @@ export class CacheFirstLoop {
              if (d.argumentsDelta)
                cur.function.arguments = (cur.function.arguments ?? "") + d.argumentsDelta;
              callBuf.set(d.index, cur);
+              // Skip the id-only opener: name is empty until the next chunk.
+              if (cur.function.name) {
+                yield {
+                  turn: this._turn,
+                  role: "tool_call_delta",
+                  content: "",
+                  toolName: cur.function.name,
+                  toolCallArgsChars: (cur.function.arguments ?? "").length,
+                };
+              }
            }
            if (chunk.usage) usage = chunk.usage;
          }
@@ -474,6 +666,7 @@ export class CacheFirstLoop {
            model: this.model,
            messages,
            tools: toolSpecs.length ? toolSpecs : undefined,
+            signal,
          });
          assistantContent = resp.content;
          reasoningContent = resp.reasoningContent ?? "";
@@ -499,15 +692,31 @@ export class CacheFirstLoop {
      }

      this.scratch.reasoning = reasoningContent || null;
+      // Harvest is a second API round-trip (cheap model, but still
+      // 1-10s) that was previously silent. Bridge the gap with a
+      // status indicator so the TUI shows *something* instead of
+      // "reasoning finished, now staring at the wall."
+      if (
+        !preHarvestedPlanState &&
+        this.harvestEnabled &&
+        (reasoningContent?.trim().length ?? 0) >= 40
+      ) {
+        yield {
+          turn: this._turn,
+          role: "status",
+          content: "extracting plan state from reasoning…",
+        };
+      }
      const planState = preHarvestedPlanState
        ? preHarvestedPlanState
        : this.harvestEnabled
-          ? await harvest(reasoningContent || null, this.client, this.harvestOptions)
+          ? await harvest(reasoningContent || null, this.client, this.harvestOptions, signal)
          : emptyPlanState();

      const { calls: repairedCalls, report } = this.repair.process(
        toolCalls,
        reasoningContent || null,
+        assistantContent || null,
      );

      this.appendAndPersist(this.assistantMessage(assistantContent, repairedCalls));
@@ -527,10 +736,93 @@ export class CacheFirstLoop {
        return;
      }

+      // Token-budget guard — the real stop condition. Iter count is a
+      // proxy that misses the actual constraint: how close the prompt
+      // already is to DeepSeek's 131k context. If we're over 80%, the
+      // NEXT call (with the just-executed tools' results stuffed into
+      // history) will be worse, and fairly soon it'll 400 with
+      // "maximum context length".
+      //
+      // Strategy, in order:
+      //   1. Try auto-compacting the log (shrink oversized tool
+      //      results). If that gets us back under 80% we keep going —
+      //      the user doesn't lose their turn to a premature summary.
+      //   2. If still over after compact, divert to the forced-summary
+      //      path. BUT first drop the trailing assistant-with-tool_calls
+      //      that we just appended — we haven't executed the tools yet,
+      //      so sending this to the summary call with no matching tool
+      //      responses would 400 ("insufficient tool messages following
+      //      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;
+      if (usage && usage.promptTokens / ctxMax > 0.8) {
+        const before = usage.promptTokens;
+        const compactResult = this.compact(4000);
+        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;
+          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.`,
+          };
+          // Intentionally don't re-check the threshold here: even if
+          // compaction didn't fully clear us under 80%, one more tool
+          // call's overhead isn't going to overflow, and the NEXT
+          // iter's fresh `usage` from the API will catch real danger.
+        } else {
+          yield {
+            turn: this._turn,
+            role: "warning",
+            content: `context ${before.toLocaleString()}/${ctxMax.toLocaleString()} (${Math.round(
+              (before / ctxMax) * 100,
+            )}%) — nothing to auto-compact. Forcing summary from what was gathered.`,
+          };
+          // Drop the trailing assistant-with-tool_calls we just
+          // appended. The forced-summary call would otherwise trip
+          // DeepSeek's "insufficient tool messages following tool_calls"
+          // validator, since we bail BEFORE dispatching the tools.
+          const tail = this.log.entries[this.log.entries.length - 1];
+          if (
+            tail &&
+            tail.role === "assistant" &&
+            Array.isArray(tail.tool_calls) &&
+            tail.tool_calls.length > 0
+          ) {
+            const kept = this.log.entries.slice(0, -1);
+            this.log.compactInPlace([...kept]);
+            if (this.sessionName) {
+              try {
+                rewriteSession(this.sessionName, kept);
+              } catch {
+                /* disk issue shouldn't block the summary path */
+              }
+            }
+          }
+          yield* this.forceSummaryAfterIterLimit({ reason: "context-guard" });
+          return;
+        }
+      }
+
      for (const call of repairedCalls) {
        const name = call.function?.name ?? "";
        const args = call.function?.arguments ?? "{}";
-        const result = await this.tools.dispatch(name, args);
+        // Announce the tool BEFORE awaiting it so the TUI can render a
+        // "running…" indicator. Without this, the window between
+        // assistant_final and the tool-result yield is silent from the
+        // UI's perspective — which makes long tool calls feel like the
+        // app has hung.
+        yield {
+          turn: this._turn,
+          role: "tool_start",
+          content: "",
+          toolName: name,
+          toolArgs: args,
+        };
+        const result = await this.tools.dispatch(name, args, { signal });
        this.appendAndPersist({
          role: "tool",
          tool_call_id: call.id ?? "",
@@ -556,22 +848,41 @@ export class CacheFirstLoop {
  }

  private async *forceSummaryAfterIterLimit(
-    opts: { reason: "budget" | "aborted" } = { reason: "budget" },
+    opts: { reason: "budget" | "aborted" | "context-guard" } = { reason: "budget" },
  ): AsyncGenerator<LoopEvent> {
    try {
+      // The summary call is non-streaming (reasoner, 30-60s typical).
+      // Without this status the user sees nothing happening after the
+      // yellow "budget reached" warning until the summary arrives.
+      yield {
+        turn: this._turn,
+        role: "status",
+        content: "summarizing what was gathered…",
+      };
      const messages = this.buildMessages(null);
+      // Passing `tools: undefined` was supposed to force a text
+      // response, but R1 can still hallucinate tool-call markup
+      // (e.g. DSML `<｜DSML｜function_calls>…</｜DSML｜function_calls>`)
+      // in prose when it's been primed by prior tool use. An explicit
+      // user-role instruction plus post-hoc stripping of known
+      // hallucination shapes keeps the user from seeing raw markup.
+      messages.push({
+        role: "user",
+        content:
+          "I'm out of tool-call budget for this turn. Summarize in plain prose what you learned from the tool results above. Do NOT emit any tool calls, function-call markup, DSML invocations, or SEARCH/REPLACE edit blocks — they will be silently discarded. Just plain text.",
+      });
      const resp = await this.client.chat({
        model: this.model,
        messages,
        // no tools → model is forced to answer in text
+        signal: this._turnAbort.signal,
      });
+      const rawContent = resp.content?.trim() ?? "";
+      const cleaned = stripHallucinatedToolMarkup(rawContent);
      const summary =
-        resp.content?.trim() ||
-        "(model returned no text; try a narrower question or raise --max-tool-iters)";
-      const reasonPrefix =
-        opts.reason === "aborted"
-          ? "[aborted by user (Esc) — summarizing what I found so far]"
-          : `[tool-call budget (${this.maxToolIters}) reached — forcing summary from what I found]`;
+        cleaned ||
+        "(model emitted fake tool-call markup instead of a prose summary — try /retry with a narrower question, or /think to inspect R1's reasoning)";
+      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 });
@@ -580,13 +891,11 @@ export class CacheFirstLoop {
        role: "assistant_final",
        content: annotated,
        stats: summaryStats,
+        forcedSummary: true,
      };
      yield { turn: this._turn, role: "done", content: summary };
    } catch (err) {
-      const label =
-        opts.reason === "aborted"
-          ? "aborted by user"
-          : `tool-call budget (${this.maxToolIters}) reached`;
+      const label = errorLabelFor(opts.reason, this.maxToolIters);
      yield {
        turn: this._turn,
        role: "error",
@@ -614,6 +923,45 @@ export class CacheFirstLoop {
  }
 }

+/**
+ * R1 occasionally hallucinates tool-call markup as plain text when the
+ * real tool channel has been closed — typically our forced-summary
+ * path, where `tools: undefined` is supposed to force prose but isn't
+ * always respected. The markup isn't parsed by our tool-call path
+ * (the API response's structured `tool_calls` field is empty), so
+ * it's just noise in the user's view. Strip known envelope shapes.
+ *
+ * Exported so tests can exercise it against concrete R1 outputs.
+ */
+export function stripHallucinatedToolMarkup(s: string): string {
+  let out = s;
+  // DeepSeek's DSML envelope (both the full-width "｜" character and
+  // the ASCII-only fallback we've seen — the full-width form is the
+  // one R1 emits in practice)
+  out = out.replace(/<｜DSML｜function_calls>[\s\S]*?<\/?｜DSML｜function_calls>/g, "");
+  out = out.replace(/<\|DSML\|function_calls>[\s\S]*?<\/?\|DSML\|function_calls>/g, "");
+  // Anthropic / generic XML-ish envelope
+  out = out.replace(/<function_calls>[\s\S]*?<\/function_calls>/g, "");
+  // Lone unpaired DSML opener left over after the closer was on a
+  // different line (seen when R1 truncates mid-call).
+  out = out.replace(/<｜DSML｜[\s\S]*$/g, "");
+  return out.trim();
+}
+
+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") {
+    return "[context budget running low — summarizing before the next call would overflow]";
+  }
+  return `[tool-call budget (${iterCap}) reached — forcing summary from what I found]`;
+}
+
+function errorLabelFor(reason: "budget" | "aborted" | "context-guard", iterCap: number): string {
+  if (reason === "aborted") return "aborted by user";
+  if (reason === "context-guard") return "context-guard triggered (prompt > 80% of window)";
+  return `tool-call budget (${iterCap}) reached`;
+}
+
 function summarizeBranch(chosen: BranchSample, samples: BranchSample[]): BranchSummary {
  return {
    budget: samples.length,
@@ -629,7 +977,13 @@ function summarizeBranch(chosen: BranchSample, samples: BranchSample[]): BranchS
 * always small, (b) truncating user prompts would corrupt conversational
 * intent in a way the user didn't author. Exported for tests.
 */
-export function healLoadedMessages(
+/**
+ * Shrink oversized tool results only — the original compact concern.
+ * Separated from `healLoadedMessages` so `/compact` (live, mid-session)
+ * doesn't accidentally strip structural tail that belongs in the
+ * current turn's state.
+ */
+export function shrinkOversizedToolResults(
  messages: ChatMessage[],
  maxChars: number,
 ): { messages: ChatMessage[]; healedCount: number; healedFrom: number } {
@@ -646,6 +1000,79 @@ export function healLoadedMessages(
  return { messages: out, healedCount, healedFrom };
 }

+export function healLoadedMessages(
+  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.
+  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]!;
+    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]!;
+        if (nxt.role !== "tool") break;
+        const id = nxt.tool_call_id ?? "";
+        if (!needed.has(id)) break;
+        needed.delete(id);
+        candidates.push(nxt);
+        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
+      } 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;
+      }
+      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 };
+}
+
 /**
 * Annotate the `DeepSeek 400: … maximum context length …` error the API
 * returns when a session's history has grown past 131,072 tokens. The
@@ -8,15 +8,25 @@ import type { McpTransport } from "./stdio.js";
 import {
  type CallToolParams,
  type CallToolResult,
+  type GetPromptParams,
+  type GetPromptResult,
  type InitializeParams,
  type InitializeResult,
  type JsonRpcId,
  type JsonRpcMessage,
  type JsonRpcRequest,
  type JsonRpcResponse,
+  type ListPromptsParams,
+  type ListPromptsResult,
+  type ListResourcesParams,
+  type ListResourcesResult,
  type ListToolsResult,
  MCP_PROTOCOL_VERSION,
  type McpClientInfo,
+  type McpProgressHandler,
+  type ProgressNotificationParams,
+  type ReadResourceParams,
+  type ReadResourceResult,
  isJsonRpcError,
 } from "./types.js";

@@ -42,6 +52,16 @@ export class McpClient {
  private readerStarted = false;
  private initialized = false;
  private _serverCapabilities: InitializeResult["capabilities"] = {};
+  private _serverInfo: InitializeResult["serverInfo"] = { name: "", version: "" };
+  private _protocolVersion = "";
+  private _instructions: string | undefined;
+  // Progress-token → handler for notifications/progress routing. Tokens
+  // are minted per call when the caller supplies an onProgress
+  // callback; cleared when the final response lands (or the pending
+  // request rejects). No leaks — the `try/finally` in callTool
+  // guarantees cleanup even on timeout.
+  private readonly progressHandlers = new Map<string | number, McpProgressHandler>();
+  private nextProgressToken = 1;

  constructor(opts: McpClientOptions) {
    this.transport = opts.transport;
@@ -54,6 +74,21 @@ export class McpClient {
    return this._serverCapabilities;
  }

+  /** Server's self-reported name + version, available after initialize(). */
+  get serverInfo(): InitializeResult["serverInfo"] {
+    return this._serverInfo;
+  }
+
+  /** Protocol version the server agreed to during the handshake. */
+  get protocolVersion(): string {
+    return this._protocolVersion;
+  }
+
+  /** Optional free-form instructions the server provides at handshake. */
+  get serverInstructions(): string | undefined {
+    return this._instructions;
+  }
+
  /**
   * Complete the initialize → initialized handshake. Must be called
   * before any other method (otherwise compliant servers reject).
@@ -63,10 +98,18 @@ export class McpClient {
    this.startReaderIfNeeded();
    const result = await this.request<InitializeResult>("initialize", {
      protocolVersion: MCP_PROTOCOL_VERSION,
-      capabilities: { tools: {} },
+      // Advertise every method the client can consume so servers know
+      // they can send listChanged notifications etc. Sub-feature flags
+      // (e.g. `resources.subscribe`) are omitted — we don't implement
+      // those yet and the empty object means "method-level support, no
+      // sub-features."
+      capabilities: { tools: {}, resources: {}, prompts: {} },
      clientInfo: this.clientInfo,
    } satisfies InitializeParams);
    this._serverCapabilities = result.capabilities ?? {};
+    this._serverInfo = result.serverInfo ?? { name: "", version: "" };
+    this._protocolVersion = result.protocolVersion ?? "";
+    this._instructions = result.instructions;
    // Per spec: client sends notifications/initialized after receiving the
    // initialize response. Only then is the connection live for other
    // methods.
@@ -84,13 +127,83 @@ export class McpClient {
    return this.request<ListToolsResult>("tools/list", {});
  }

-  /** Invoke a tool by name. Returns the raw MCP result (caller unwraps content). */
-  async callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult> {
+  /**
+   * Invoke a tool by name. When `onProgress` is supplied, attaches a
+   * fresh progress token so the server can send incremental updates
+   * via `notifications/progress`; they're routed to the callback until
+   * the final response arrives (or the request times out, in which
+   * case the handler is simply dropped — no extra notification).
+   *
+   * When `signal` is supplied, aborting it:
+   *   1) fires `notifications/cancelled` to the server (MCP 2024-11-05
+   *      way of saying "forget this request, I no longer care"), and
+   *   2) rejects the pending promise immediately with an AbortError,
+   *      so the caller doesn't have to wait for the subprocess to
+   *      finish its in-flight file write or network request.
+   * The server MAY still emit a late response; we drop it in dispatch
+   * since the request id is gone from `pending`.
+   */
+  async callTool(
+    name: string,
+    args?: Record<string, unknown>,
+    opts: { onProgress?: McpProgressHandler; signal?: AbortSignal } = {},
+  ): Promise<CallToolResult> {
    this.assertInitialized();
-    return this.request<CallToolResult>("tools/call", {
+    const params: CallToolParams = { name, arguments: args ?? {} };
+    let token: number | undefined;
+    if (opts.onProgress) {
+      token = this.nextProgressToken++;
+      this.progressHandlers.set(token, opts.onProgress);
+      params._meta = { progressToken: token };
+    }
+    try {
+      return await this.request<CallToolResult>("tools/call", params, opts.signal);
+    } finally {
+      if (token !== undefined) this.progressHandlers.delete(token);
+    }
+  }
+
+  /**
+   * List resources the server exposes. Supports a pagination cursor;
+   * callers interested in the full set should loop on `nextCursor`.
+   * Servers that don't support resources respond with method-not-found
+   * (−32601) — we surface that as a thrown Error so callers can gate
+   * on the `serverCapabilities.resources` field first.
+   */
+  async listResources(cursor?: string): Promise<ListResourcesResult> {
+    this.assertInitialized();
+    return this.request<ListResourcesResult>("resources/list", {
+      ...(cursor ? { cursor } : {}),
+    } satisfies ListResourcesParams);
+  }
+
+  /** Read the contents of a resource by URI. */
+  async readResource(uri: string): Promise<ReadResourceResult> {
+    this.assertInitialized();
+    return this.request<ReadResourceResult>("resources/read", {
+      uri,
+    } satisfies ReadResourceParams);
+  }
+
+  /** List prompt templates the server exposes. */
+  async listPrompts(cursor?: string): Promise<ListPromptsResult> {
+    this.assertInitialized();
+    return this.request<ListPromptsResult>("prompts/list", {
+      ...(cursor ? { cursor } : {}),
+    } satisfies ListPromptsParams);
+  }
+
+  /**
+   * Fetch a rendered prompt by name. `args` supplies values for any
+   * required template arguments; the server validates. Returns messages
+   * ready to prepend to the model's input.
+   */
+  async getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult> {
+    this.assertInitialized();
+    return this.request<GetPromptResult>("prompts/get", {
      name,
-      arguments: args ?? {},
-    } satisfies CallToolParams);
+      ...(args ? { arguments: args } : {}),
+    } satisfies GetPromptParams);
  }

  /** Close the transport and reject any outstanding requests. */
@@ -109,12 +222,14 @@ export class McpClient {
    if (!this.initialized) throw new Error("MCP client not initialized — call initialize() first");
  }

-  private async request<R>(method: string, params: unknown): Promise<R> {
+  private async request<R>(method: string, params: unknown, signal?: AbortSignal): Promise<R> {
    const id = this.nextId++;
    const frame: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+    let abortHandler: (() => void) | null = null;
    const promise = new Promise<R>((resolve, reject) => {
      const timeout = setTimeout(() => {
        this.pending.delete(id);
+        if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
        reject(
          new Error(`MCP request ${method} (id=${id}) timed out after ${this.requestTimeoutMs}ms`),
        );
@@ -124,9 +239,49 @@ export class McpClient {
        reject,
        timeout,
      });
+      // Wire up cancellation: when signal fires, send an MCP cancellation
+      // notification to the server (so it can stop whatever it was doing)
+      // and reject the caller immediately — no need to wait for the
+      // subprocess to finish its in-flight work. Late responses from the
+      // server are dropped by `dispatch` because the id is gone from
+      // `pending`.
+      if (signal) {
+        if (signal.aborted) {
+          this.pending.delete(id);
+          clearTimeout(timeout);
+          reject(new Error(`MCP request ${method} (id=${id}) aborted before send`));
+          return;
+        }
+        abortHandler = () => {
+          this.pending.delete(id);
+          clearTimeout(timeout);
+          void this.transport
+            .send({
+              jsonrpc: "2.0",
+              method: "notifications/cancelled",
+              params: { requestId: id, reason: "aborted by user" },
+            })
+            .catch(() => {
+              // Transport may already be closing — swallow; we still
+              // reject the caller below so they unblock.
+            });
+          reject(new Error(`MCP request ${method} (id=${id}) aborted by user`));
+        };
+        signal.addEventListener("abort", abortHandler, { once: true });
+      }
    });
-    await this.transport.send(frame);
-    return promise;
+    try {
+      await this.transport.send(frame);
+    } catch (err) {
+      this.pending.delete(id);
+      if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+      throw err;
+    }
+    try {
+      return await promise;
+    } finally {
+      if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
+    }
  }

  private startReaderIfNeeded(): void {
@@ -152,9 +307,20 @@ export class McpClient {
  }

  private dispatch(msg: JsonRpcMessage): void {
-    // We only care about responses (have an `id`) for now. Server-initiated
-    // notifications are dropped until we support resources/prompts.
-    if (!("id" in msg) || msg.id === null || msg.id === undefined) return;
+    // Notifications (no `id`): route by method. Progress notifications
+    // go to the per-call handler if one was registered; everything
+    // else is dropped silently (we don't yet handle tools/list_changed
+    // or resources/list_changed).
+    if (!("id" in msg) || msg.id === null || msg.id === undefined) {
+      if ("method" in msg && msg.method === "notifications/progress") {
+        const p = msg.params as ProgressNotificationParams | undefined;
+        if (!p || p.progressToken === undefined) return;
+        const handler = this.progressHandlers.get(p.progressToken);
+        if (!handler) return; // late notification after the call resolved
+        handler({ progress: p.progress, total: p.total, message: p.message });
+      }
+      return;
+    }
    if (!("result" in msg) && !("error" in msg)) return; // it's a request from server
    const pending = this.pending.get(msg.id);
    if (!pending) return; // late response after timeout; drop
@@ -0,0 +1,71 @@
+/**
+ * Gather a full inspection report from an initialized MCP client:
+ * server info, capabilities, tools, resources, prompts. Methods the
+ * server doesn't support come back as `{ supported: false }` instead
+ * of throwing, so a CLI or UI can render a consistent "what this
+ * server exposes" summary even against minimal implementations.
+ *
+ * Pure with respect to I/O beyond the passed-in client — the CLI
+ * layer owns argument parsing, connection setup, and printing.
+ */
+
+import type { McpClient } from "./client.js";
+import type { McpPrompt, McpResource, McpTool } from "./types.js";
+
+export interface InspectionReport {
+  protocolVersion: string;
+  serverInfo: { name: string; version: string };
+  capabilities: Record<string, unknown>;
+  instructions?: string;
+  tools: SectionResult<McpTool>;
+  resources: SectionResult<McpResource>;
+  prompts: SectionResult<McpPrompt>;
+}
+
+export type SectionResult<T> =
+  | { supported: true; items: T[] }
+  | { supported: false; reason: string };
+
+/**
+ * Run an inspection against a **already-initialized** client. Caller
+ * is responsible for `initialize()` before this and `close()` after.
+ * We keep this pure so unit tests can feed in a FakeMcpTransport and
+ * verify the aggregate shape without spinning up a real process.
+ */
+export async function inspectMcpServer(client: McpClient): Promise<InspectionReport> {
+  // We always *try* the three listings so the client learns whether a
+  // server without explicit capability flags still serves them —
+  // some servers omit capabilities but still respond to the methods.
+  const tools = await trySection<McpTool>(() => client.listTools().then((r) => r.tools));
+  const resources = await trySection<McpResource>(() =>
+    client.listResources().then((r) => r.resources),
+  );
+  const prompts = await trySection<McpPrompt>(() => client.listPrompts().then((r) => r.prompts));
+
+  return {
+    protocolVersion: client.protocolVersion || "(unknown)",
+    serverInfo: client.serverInfo,
+    capabilities: client.serverCapabilities ?? {},
+    instructions: client.serverInstructions,
+    tools,
+    resources,
+    prompts,
+  };
+}
+
+async function trySection<T>(load: () => Promise<T[]>): Promise<SectionResult<T>> {
+  try {
+    const items = await load();
+    return { supported: true, items };
+  } catch (err) {
+    const msg = (err as Error).message ?? String(err);
+    // -32601 is JSON-RPC "method not found" — the canonical response
+    // from a server that doesn't implement this family. Treat it as
+    // "not supported" rather than a hard error, so the CLI can render
+    // a clean summary instead of aborting on the first missing method.
+    if (/-32601/.test(msg) || /method not found/i.test(msg)) {
+      return { supported: false, reason: "method not found (-32601)" };
+    }
+    return { supported: false, reason: msg };
+  }
+}
@@ -36,6 +36,19 @@ export interface BridgeOptions {
   * legitimately want bigger payloads can raise it explicitly.
   */
  maxResultChars?: number;
+  /**
+   * Callback fired for every `notifications/progress` frame the server
+   * emits during any bridged tool call. Includes the registered
+   * (prefix-applied) tool name so a multi-server UI can attribute
+   * progress correctly. Absent → no `_meta.progressToken` is sent and
+   * the server won't emit progress for these calls.
+   */
+  onProgress?: (info: {
+    toolName: string;
+    progress: number;
+    total?: number;
+    message?: string;
+  }) => void;
 }

 /**
@@ -80,8 +93,22 @@ export async function bridgeMcpTools(
      name: registeredName,
      description: mcpTool.description ?? "",
      parameters: mcpTool.inputSchema as JSONSchema,
-      fn: async (args: Record<string, unknown>) => {
-        const toolResult = await client.callTool(mcpTool.name, args);
+      fn: async (args: Record<string, unknown>, ctx) => {
+        const toolResult = await client.callTool(mcpTool.name, args, {
+          // Forward server-side progress frames to the bridge caller,
+          // tagged with the registered name so multi-server UIs can
+          // disambiguate. No-op when `onProgress` isn't configured —
+          // the client then also omits the _meta.progressToken and
+          // the server won't emit progress.
+          onProgress: opts.onProgress
+            ? (info) => opts.onProgress!({ toolName: registeredName, ...info })
+            : undefined,
+          // Thread the tool-dispatch AbortSignal all the way down to
+          // the MCP request so Esc truly cancels in flight — the
+          // client will emit notifications/cancelled AND reject the
+          // pending promise immediately, no "wait for subprocess".
+          signal: ctx?.signal,
+        });
        return flattenMcpResult(toolResult, { maxChars: maxResultChars });
      },
    });
@@ -10,8 +10,9 @@
 *     insulated as long as we keep up with the spec itself.
 *
 * Spec reference: https://spec.modelcontextprotocol.io/ (2024-11-05 draft
- * at time of writing). Only the subset Reasonix consumes is modeled here —
- * tools list/call + init handshake. Resources and prompts are deferred.
+ * at time of writing). Reasonix models the subset it consumes: tools
+ * list/call, resources list/read, prompts list/get, plus the init
+ * handshake. Sampling and progress notifications remain deferred.
 *
 * Transport note: the wire format for stdio MCP is **newline-delimited
 * JSON** (NDJSON), not the LSP-style Content-Length header framing that
@@ -66,7 +67,11 @@ export interface McpClientInfo {
 export interface McpClientCapabilities {
  /** Empty object advertises support without any optional sub-features. */
  tools?: Record<string, never>;
-  // resources / prompts / sampling would go here — deferred.
+  /** Advertised when the client can consume `resources/list` + `resources/read`. */
+  resources?: Record<string, never>;
+  /** Advertised when the client can consume `prompts/list` + `prompts/get`. */
+  prompts?: Record<string, never>;
+  // sampling would go here — deferred.
 }

 export interface InitializeParams {
@@ -111,8 +116,38 @@ export interface ListToolsResult {
 export interface CallToolParams {
  name: string;
  arguments?: Record<string, unknown>;
+  /**
+   * MCP's `_meta` envelope carries out-of-band protocol metadata.
+   * Setting `progressToken` here tells the server "send me progress
+   * notifications back using this token"; the server must then emit
+   * `notifications/progress` frames until the response arrives.
+   */
+  _meta?: { progressToken?: string | number };
 }

+/**
+ * Server → client notification emitted during a long-running request
+ * that the client subscribed to via `_meta.progressToken`. `progress`
+ * and `total` are typically matched units (files scanned, bytes
+ * processed, etc.); `total` may be missing when the server can't
+ * estimate the upper bound up front.
+ */
+export interface ProgressNotificationParams {
+  progressToken: string | number;
+  progress: number;
+  total?: number;
+  message?: string;
+}
+
+/** Values a `ProgressHandler` receives — `progressToken` is already matched away. */
+export interface McpProgressInfo {
+  progress: number;
+  total?: number;
+  message?: string;
+}
+
+export type McpProgressHandler = (info: McpProgressInfo) => void;
+
 export interface McpContentBlockText {
  type: "text";
  text: string;
@@ -133,6 +168,112 @@ export interface CallToolResult {
  isError?: boolean;
 }

+// ---------- MCP resources ----------
+
+/**
+ * A resource the server can expose — think "file the model can read."
+ * The URI is opaque to the client: servers may use `file://`, custom
+ * schemes, or bare strings. Reasonix doesn't interpret them.
+ */
+export interface McpResource {
+  uri: string;
+  name: string;
+  description?: string;
+  /** Hint for the content type (e.g. "text/markdown"). Purely informational. */
+  mimeType?: string;
+}
+
+export interface ListResourcesParams {
+  /** Pagination cursor from a previous listResources response. */
+  cursor?: string;
+}
+
+export interface ListResourcesResult {
+  resources: McpResource[];
+  nextCursor?: string;
+}
+
+export interface ReadResourceParams {
+  uri: string;
+}
+
+/**
+ * One resource can return multiple content blobs (e.g. the file + a
+ * side-car). `text` is the common case for UTF-8 content; `blob` is
+ * base64-encoded bytes for binary content. Servers populate exactly
+ * one of the two for each entry.
+ */
+export interface McpResourceContentsText {
+  uri: string;
+  mimeType?: string;
+  text: string;
+}
+
+export interface McpResourceContentsBlob {
+  uri: string;
+  mimeType?: string;
+  blob: string;
+}
+
+export type McpResourceContents = McpResourceContentsText | McpResourceContentsBlob;
+
+export interface ReadResourceResult {
+  contents: McpResourceContents[];
+}
+
+// ---------- MCP prompts ----------
+
+/**
+ * A parameterizable prompt template the server exposes. Clients fetch
+ * it with `prompts/get` and pass the result to the model as-is.
+ */
+export interface McpPromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface McpPrompt {
+  name: string;
+  description?: string;
+  arguments?: McpPromptArgument[];
+}
+
+export interface ListPromptsParams {
+  cursor?: string;
+}
+
+export interface ListPromptsResult {
+  prompts: McpPrompt[];
+  nextCursor?: string;
+}
+
+export interface GetPromptParams {
+  name: string;
+  arguments?: Record<string, string>;
+}
+
+/**
+ * MCP prompt messages are modeled after chat completions: role + content.
+ * Content can be a text block OR (per the spec) a resource/image block;
+ * Reasonix cares about text in v1, but surfaces the raw array so callers
+ * can render other kinds if they need to.
+ */
+export interface McpPromptMessage {
+  role: "user" | "assistant";
+  content: McpContentBlock | McpPromptResourceBlock;
+}
+
+export interface McpPromptResourceBlock {
+  type: "resource";
+  resource: McpResourceContents;
+}
+
+export interface GetPromptResult {
+  description?: string;
+  messages: McpPromptMessage[];
+}
+
 // ---------- convenience ----------

 /** Current MCP protocol version Reasonix is coded against. */
@@ -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}
+\`\`\`
+`;
+}
@@ -49,6 +49,7 @@ export class ToolCallRepair {
  process(
    declaredCalls: ToolCall[],
    reasoningContent: string | null,
+    content: string | null = null,
  ): { calls: ToolCall[]; report: RepairReport } {
    const report: RepairReport = {
      scavenged: 0,
@@ -58,7 +59,13 @@ export class ToolCallRepair {
    };

    // 1. Scavenge — only add calls whose (name,args) signature is novel.
-    const scavenged = scavengeToolCalls(reasoningContent, {
+    // Scan both channels: reasoning (where R1 leaks JSON calls into
+    // <think>) AND content (where it emits DSML markup in regular
+    // turns). Joined with a newline so the scanners see the blobs as
+    // independent bodies. Dedup below keeps us from inflating if the
+    // same call shows up in both — first seen wins.
+    const combined = [reasoningContent ?? "", content ?? ""].filter(Boolean).join("\n");
+    const scavenged = scavengeToolCalls(combined || null, {
      allowedNames: this.opts.allowedToolNames,
      maxCalls: this.opts.maxScavenge ?? 4,
    });
@@ -30,7 +30,28 @@ export function scavengeToolCalls(
  const notes: string[] = [];
  const out: ToolCall[] = [];

-  for (const candidate of iterateJsonObjects(reasoningContent)) {
+  // Pattern A: DSML invoke blocks. R1 sometimes emits tool calls as
+  // its chat-template markup in the content channel instead of the
+  // proper `tool_calls` field. 0.4.3 stripped these from display;
+  // here we actually turn them back into proper ToolCalls so the
+  // model's intent isn't lost.
+  for (const invoke of iterateDsmlInvokes(reasoningContent)) {
+    if (out.length >= max) break;
+    if (!opts.allowedNames.has(invoke.name)) continue;
+    out.push({
+      function: {
+        name: invoke.name,
+        arguments: JSON.stringify(invoke.args),
+      },
+    });
+    notes.push(`scavenged DSML call: ${invoke.name}`);
+  }
+
+  // Pattern B: raw JSON objects (the original three shapes). Strip
+  // any DSML blocks we already processed so parameter JSON buried
+  // inside them doesn't get re-scavenged as a standalone call.
+  const nonDsml = stripDsmlBlocks(reasoningContent);
+  for (const candidate of iterateJsonObjects(nonDsml)) {
    if (out.length >= max) break;
    const call = coerceToToolCall(candidate, opts.allowedNames);
    if (call) {
@@ -41,6 +62,85 @@ export function scavengeToolCalls(
  return { calls: out, notes };
 }

+interface DsmlInvoke {
+  name: string;
+  args: Record<string, unknown>;
+}
+
+/**
+ * Yield DeepSeek DSML invoke blocks scavenged from text. R1's chat
+ * template uses these when the server-side tool-call serializer
+ * misfires — we see them verbatim in the content channel:
+ *
+ *   <｜DSML｜function_calls>
+ *     <｜DSML｜invoke name="filesystem_edit_file">
+ *       <｜DSML｜parameter name="path" string="true">F:/x.html</｜DSML｜parameter>
+ *       <｜DSML｜parameter name="edits" string="false">[…]</｜DSML｜parameter>
+ *     </｜DSML｜invoke>
+ *   </｜DSML｜function_calls>
+ *
+ * The wrapper class (｜ U+FF5C vs ASCII |) varies by model build, so
+ * we accept both. `string="true"` means the parameter value is a
+ * literal string; `string="false"` means it's JSON.
+ */
+/**
+ * Remove DSML invoke/function_calls blocks from text so the raw-JSON
+ * scanner below doesn't see parameter payloads as standalone calls.
+ * Mirrors the strip pass in `stripHallucinatedToolMarkup` but scoped
+ * to scavenge (we also want the `function_calls` wrapper gone —
+ * nothing useful to scavenge there).
+ */
+function stripDsmlBlocks(text: string): string {
+  let out = text;
+  out = out.replace(/<[｜|]DSML[｜|]function_calls>[\s\S]*?<\/?[｜|]DSML[｜|]function_calls>/g, "");
+  out = out.replace(/<[｜|]DSML[｜|]invoke\s+[^>]*>[\s\S]*?<\/[｜|]DSML[｜|]invoke>/g, "");
+  return out;
+}
+
+function* iterateDsmlInvokes(text: string): Generator<DsmlInvoke> {
+  // `｜` (U+FF5C) in practice; `|` (ASCII) as a fallback seen in a
+  // minority of builds. `[｜|]` inside the regex covers both.
+  const INVOKE_RE = /<[｜|]DSML[｜|]invoke\s+name="([^"]+)">([\s\S]*?)<\/[｜|]DSML[｜|]invoke>/g;
+  for (const match of text.matchAll(INVOKE_RE)) {
+    const name = match[1];
+    const body = match[2];
+    if (!name || body === undefined) continue;
+    yield { name, args: parseDsmlParameters(body) };
+  }
+}
+
+/**
+ * Parse the parameter children of a DSML invoke body into a plain
+ * object. We tolerate:
+ *   - `string="true"` → literal text; whitespace trimmed at the edges.
+ *   - `string="false"` → JSON-parsed; falls back to literal text if the
+ *     payload turns out to be malformed (better to hand a string
+ *     through than lose the parameter entirely).
+ *   - no `string="…"` attribute → treat as literal text (older/shorter
+ *     DSML shapes we haven't formally seen but want to handle).
+ */
+function parseDsmlParameters(body: string): Record<string, unknown> {
+  const PARAM_RE =
+    /<[｜|]DSML[｜|]parameter\s+name="([^"]+)"(?:\s+string="(true|false)")?\s*>([\s\S]*?)<\/[｜|]DSML[｜|]parameter>/g;
+  const args: Record<string, unknown> = {};
+  for (const m of body.matchAll(PARAM_RE)) {
+    const key = m[1];
+    const stringFlag = m[2];
+    const raw = (m[3] ?? "").trim();
+    if (!key) continue;
+    if (stringFlag === "false") {
+      try {
+        args[key] = JSON.parse(raw);
+        continue;
+      } catch {
+        // Fall through — keep as literal so the information isn't lost.
+      }
+    }
+    args[key] = raw;
+  }
+  return args;
+}
+
 /** Yield every top-level JSON object substring in `text`. */
 function* iterateJsonObjects(text: string): Generator<string> {
  for (let i = 0; i < text.length; i++) {
@@ -10,7 +10,14 @@
 */

 import { Usage } from "./client.js";
-import { type SessionSummary, type TurnStats, claudeEquivalentCost, costUsd } from "./telemetry.js";
+import {
+  type SessionSummary,
+  type TurnStats,
+  claudeEquivalentCost,
+  costUsd,
+  inputCostUsd,
+  outputCostUsd,
+} from "./telemetry.js";
 import { type ReadTranscriptResult, type TranscriptRecord, readTranscript } from "./transcript.js";

 /**
@@ -142,6 +149,8 @@ export function computeReplayStats(records: TranscriptRecord[]): ReplayStats {

 function summarizeTurns(turns: TurnStats[]): SessionSummary {
  const totalCost = turns.reduce((s, t) => s + t.cost, 0);
+  const totalInput = turns.reduce((s, t) => s + inputCostUsd(t.model, t.usage), 0);
+  const totalOutput = turns.reduce((s, t) => s + outputCostUsd(t.model, t.usage), 0);
  const totalClaude = turns.reduce((s, t) => s + claudeEquivalentCost(t.usage), 0);
  let hit = 0;
  let miss = 0;
@@ -155,6 +164,8 @@ function summarizeTurns(turns: TurnStats[]): SessionSummary {
  return {
    turns: turns.length,
    totalCostUsd: round(totalCost, 6),
+    totalInputCostUsd: round(totalInput, 6),
+    totalOutputCostUsd: round(totalOutput, 6),
    claudeEquivalentUsd: round(totalClaude, 6),
    savingsVsClaudePct: round(savingsVsClaude * 100, 2),
    cacheHitRatio: round(cacheHitRatio, 4),
@@ -37,6 +37,24 @@ export function costUsd(model: string, usage: Usage): number {
  );
 }

+/** Input-side cost only (prompt, cache hit + miss). Used for the panel breakdown. */
+export function inputCostUsd(model: string, usage: Usage): number {
+  const p = DEEPSEEK_PRICING[model];
+  if (!p) return 0;
+  return (
+    (usage.promptCacheHitTokens * p.inputCacheHit +
+      usage.promptCacheMissTokens * p.inputCacheMiss) /
+    1_000_000
+  );
+}
+
+/** Output-side cost only (completion tokens). Used for the panel breakdown. */
+export function outputCostUsd(model: string, usage: Usage): number {
+  const p = DEEPSEEK_PRICING[model];
+  if (!p) return 0;
+  return (usage.completionTokens * p.output) / 1_000_000;
+}
+
 export function claudeEquivalentCost(usage: Usage): number {
  return (
    (usage.promptTokens * CLAUDE_SONNET_PRICING.input +
@@ -56,7 +74,17 @@ export interface TurnStats {
 export interface SessionSummary {
  turns: number;
  totalCostUsd: number;
+  /**
+   * Input-side (prompt) cost aggregated across the session. Split
+   * from totalCostUsd so the panel can render "cost $X (in $Y · out
+   * $Z)" — users asked for visibility into where the spend lands.
+   */
+  totalInputCostUsd: number;
+  /** Output-side (completion) cost aggregated across the session. */
+  totalOutputCostUsd: number;
+  /** @deprecated Claude reference; kept for benchmarks + replay compat, no longer surfaced in the TUI. */
  claudeEquivalentUsd: number;
+  /** @deprecated. Same as claudeEquivalentUsd — synthetic ratio, not a real measurement. */
  savingsVsClaudePct: number;
  cacheHitRatio: number;
  /**
@@ -97,6 +125,14 @@ export class SessionStats {
    return c > 0 ? 1 - this.totalCost / c : 0;
  }

+  get totalInputCost(): number {
+    return this.turns.reduce((sum, t) => sum + inputCostUsd(t.model, t.usage), 0);
+  }
+
+  get totalOutputCost(): number {
+    return this.turns.reduce((sum, t) => sum + outputCostUsd(t.model, t.usage), 0);
+  }
+
  get aggregateCacheHitRatio(): number {
    let hit = 0;
    let miss = 0;
@@ -113,6 +149,8 @@ export class SessionStats {
    return {
      turns: this.turns.length,
      totalCostUsd: round(this.totalCost, 6),
+      totalInputCostUsd: round(this.totalInputCost, 6),
+      totalOutputCostUsd: round(this.totalOutputCost, 6),
      claudeEquivalentUsd: round(this.totalClaudeEquivalent, 6),
      savingsVsClaudePct: round(this.savingsVsClaude * 100, 2),
      cacheHitRatio: round(this.aggregateCacheHitRatio, 4),
@@ -1,11 +1,23 @@
 import { analyzeSchema, flattenSchema, nestArguments } from "./repair/flatten.js";
 import type { JSONSchema, ToolSpec } from "./types.js";

+/**
+ * Per-call context a tool `fn` can optionally consume. Today the only
+ * field is `signal`, plumbed through so long-running tools (MCP calls,
+ * HTTP requests) can abort when the user presses Esc. Omitted fields
+ * stay optional — tools written against the pre-0.4.9 signature keep
+ * working; they just ignore cancellation, which is fine for fast
+ * local work where "await finishes" happens before the next tick anyway.
+ */
+export interface ToolCallContext {
+  signal?: AbortSignal;
+}
+
 export interface ToolDefinition<A = any, R = any> {
  name: string;
  description?: string;
  parameters?: JSONSchema;
-  fn: (args: A) => R | Promise<R>;
+  fn: (args: A, ctx?: ToolCallContext) => R | Promise<R>;
 }

 interface InternalTool extends ToolDefinition {
@@ -76,7 +88,11 @@ export class ToolRegistry {
    }));
  }

-  async dispatch(name: string, argumentsRaw: string | Record<string, unknown>): Promise<string> {
+  async dispatch(
+    name: string,
+    argumentsRaw: string | Record<string, unknown>,
+    opts: { signal?: AbortSignal } = {},
+  ): Promise<string> {
    const tool = this._tools.get(name);
    if (!tool) {
      return JSON.stringify({ error: `unknown tool: ${name}` });
@@ -105,7 +121,7 @@ export class ToolRegistry {
    }

    try {
-      const result = await tool.fn(args);
+      const result = await tool.fn(args, { signal: opts.signal });
      return typeof result === "string" ? result : JSON.stringify(result);
    } catch (err) {
      return JSON.stringify({
@@ -0,0 +1,445 @@
+/**
+ * Built-in filesystem tools for `reasonix code`.
+ *
+ * Why native instead of the official `@modelcontextprotocol/server-filesystem`:
+ *   - No subprocess overhead — every call is 50-200 ms cheaper.
+ *   - Schema shapes tuned for R1: `edit_file` takes a single
+ *     SEARCH/REPLACE string instead of `string="false"`-encoded
+ *     JSON arrays, which was the biggest single source of DSML
+ *     hallucinations in 0.4.x.
+ *   - Sandbox enforcement lives here so Reasonix can reason about
+ *     it (tests cover path-traversal, symlink-escape, and the
+ *     cwd-outside-root case) rather than trusting an external server.
+ *   - No `npx install` / network dependency in `reasonix code`.
+ *
+ * Tool names + argument shapes intentionally mirror the official
+ * filesystem server so R1's muscle memory carries over. The only
+ * intentional divergence is `edit_file`, noted above.
+ */
+
+import { promises as fs } from "node:fs";
+import * as pathMod from "node:path";
+import type { ToolRegistry } from "../tools.js";
+
+export interface FilesystemToolsOptions {
+  /** Absolute directory the tools may read/write. Paths outside this are refused. */
+  rootDir: string;
+  /**
+   * When `false`, register only read-side tools (read_file, list_directory,
+   * search_files, get_file_info, directory_tree). Useful for read-only
+   * workflows where the model should never mutate the tree. Default: true.
+   */
+  allowWriting?: boolean;
+  /**
+   * Cap for a single file read, in bytes. Prevents a stray `read_file`
+   * on a multi-GB blob from OOM'ing Node. 2 MB is enough for any realistic
+   * source file (the biggest single-file TypeScript project checked in to
+   * GitHub is ~500 KB); pass higher when working with data files.
+   */
+  maxReadBytes?: number;
+  /**
+   * Cap for total bytes returned from search_files / directory_tree /
+   * grep, so the model can't accidentally pull down the whole tree as
+   * one giant string. 256 KB by default.
+   */
+  maxListBytes?: number;
+}
+
+const DEFAULT_MAX_READ_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_LIST_BYTES = 256 * 1024;
+
+export function registerFilesystemTools(
+  registry: ToolRegistry,
+  opts: FilesystemToolsOptions,
+): ToolRegistry {
+  const rootDir = pathMod.resolve(opts.rootDir);
+  const allowWriting = opts.allowWriting !== false;
+  const maxReadBytes = opts.maxReadBytes ?? DEFAULT_MAX_READ_BYTES;
+  const maxListBytes = opts.maxListBytes ?? DEFAULT_MAX_LIST_BYTES;
+
+  /** Resolve path, enforce it's under rootDir, return absolute. */
+  const safePath = (raw: unknown): string => {
+    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);
+    const normRoot = pathMod.resolve(rootDir);
+    // Use relative() to catch any `..` segments that escape.
+    const rel = pathMod.relative(normRoot, resolved);
+    if (rel.startsWith("..") || pathMod.isAbsolute(rel)) {
+      throw new Error(`path escapes sandbox root (${normRoot}): ${raw}`);
+    }
+    return resolved;
+  };
+
+  registry.register({
+    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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to read (relative to rootDir or absolute)." },
+        head: { type: "integer", description: "If set, return only the first N lines." },
+        tail: { type: "integer", description: "If set, return only the last N lines." },
+      },
+      required: ["path"],
+    },
+    fn: async (args: { path: string; head?: number; tail?: number }) => {
+      const abs = safePath(args.path);
+      const stat = await fs.stat(abs);
+      if (stat.isDirectory()) {
+        throw new Error(`not a file: ${args.path} (it's a directory)`);
+      }
+      const raw = await fs.readFile(abs);
+      if (raw.length > maxReadBytes) {
+        const head = raw.slice(0, maxReadBytes).toString("utf8");
+        return `${head}\n\n[…truncated ${raw.length - maxReadBytes} bytes — file is ${raw.length} B, cap ${maxReadBytes} B. Retry with head/tail for targeted view.]`;
+      }
+      const text = raw.toString("utf8");
+      if (typeof args.head === "number" && args.head > 0) {
+        return text.split(/\r?\n/).slice(0, args.head).join("\n");
+      }
+      if (typeof args.tail === "number" && args.tail > 0) {
+        let lines = text.split(/\r?\n/);
+        // Most files end with a final '\n', which splits into an empty
+        // trailing string. Drop it before slicing so tail=2 returns the
+        // last two *real* lines, not "last line + empty".
+        if (lines.length > 0 && lines[lines.length - 1] === "") lines = lines.slice(0, -1);
+        return lines.slice(Math.max(0, lines.length - args.tail)).join("\n");
+      }
+      return text;
+    },
+  });
+
+  registry.register({
+    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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory to list (default: root)." },
+      },
+    },
+    fn: async (args: { path?: string }) => {
+      const abs = safePath(args.path ?? ".");
+      const entries = await fs.readdir(abs, { withFileTypes: true });
+      const lines: string[] = [];
+      for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        lines.push(e.isDirectory() ? `${e.name}/` : e.name);
+      }
+      return lines.join("\n") || "(empty directory)";
+    },
+  });
+
+  registry.register({
+    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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Root of the tree (default: sandbox root)." },
+        maxDepth: { type: "integer", description: "Max recursion depth (default 4)." },
+      },
+    },
+    fn: async (args: { path?: string; maxDepth?: number }) => {
+      const startAbs = safePath(args.path ?? ".");
+      const maxDepth = typeof args.maxDepth === "number" ? args.maxDepth : 4;
+      const lines: string[] = [];
+      let totalBytes = 0;
+      let truncated = false;
+      const walk = async (dir: string, depth: number): Promise<void> => {
+        if (truncated) return;
+        if (depth > maxDepth) return;
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+          if (truncated) return;
+          const indent = "  ".repeat(depth);
+          const line = e.isDirectory() ? `${indent}${e.name}/` : `${indent}${e.name}`;
+          totalBytes += line.length + 1;
+          if (totalBytes > maxListBytes) {
+            lines.push(`  [… tree truncated at ${maxListBytes} bytes …]`);
+            truncated = true;
+            return;
+          }
+          lines.push(line);
+          if (e.isDirectory()) {
+            await walk(pathMod.join(dir, e.name), depth + 1);
+          }
+        }
+      };
+      await walk(startAbs, 0);
+      return lines.join("\n") || "(empty tree)";
+    },
+  });
+
+  registry.register({
+    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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory to start the search at (default: root)." },
+        pattern: {
+          type: "string",
+          description: "Substring (or regex) to match against filenames.",
+        },
+      },
+      required: ["pattern"],
+    },
+    fn: async (args: { path?: string; pattern: string }) => {
+      const startAbs = safePath(args.path ?? ".");
+      const needle = args.pattern.toLowerCase();
+      // Try as regex first (permits users who want patterns); fall
+      // back to plain substring when it's not a valid regex. Flag `i`
+      // so matching is case-insensitive regardless of path.
+      let re: RegExp | null = null;
+      try {
+        re = new RegExp(args.pattern, "i");
+      } catch {
+        re = null;
+      }
+      const matches: string[] = [];
+      let totalBytes = 0;
+      const walk = async (dir: string): Promise<void> => {
+        let entries: import("node:fs").Dirent[];
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch {
+          return;
+        }
+        for (const e of entries) {
+          const full = pathMod.join(dir, e.name);
+          const lower = e.name.toLowerCase();
+          const hit = re ? re.test(e.name) : lower.includes(needle);
+          if (hit) {
+            const rel = pathMod.relative(rootDir, full);
+            if (totalBytes + rel.length + 1 > maxListBytes) {
+              matches.push("[… search truncated — refine pattern …]");
+              return;
+            }
+            matches.push(rel);
+            totalBytes += rel.length + 1;
+          }
+          if (e.isDirectory()) await walk(full);
+        }
+      };
+      await walk(startAbs);
+      return matches.length === 0 ? "(no matches)" : 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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+      },
+      required: ["path"],
+    },
+    fn: async (args: { path: string }) => {
+      const abs = safePath(args.path);
+      const st = await fs.lstat(abs);
+      const type = st.isDirectory() ? "directory" : st.isSymbolicLink() ? "symlink" : "file";
+      return JSON.stringify({
+        type,
+        size: st.size,
+        mtime: st.mtime.toISOString(),
+      });
+    },
+  });
+
+  if (!allowWriting) return registry;
+
+  registry.register({
+    name: "write_file",
+    description:
+      "Create or overwrite a file under the sandbox root with the given content. Parent directories are created as needed.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        content: { type: "string" },
+      },
+      required: ["path", "content"],
+    },
+    fn: async (args: { path: string; content: string }) => {
+      const abs = safePath(args.path);
+      await fs.mkdir(pathMod.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, args.content, "utf8");
+      return `wrote ${args.content.length} chars to ${pathMod.relative(rootDir, abs)}`;
+    },
+  });
+
+  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.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        search: { type: "string", description: "Exact text to find (must be unique)." },
+        replace: { type: "string", description: "Text to substitute in place of `search`." },
+      },
+      required: ["path", "search", "replace"],
+    },
+    fn: async (args: { path: string; search: string; replace: string }) => {
+      const abs = safePath(args.path);
+      const before = await fs.readFile(abs, "utf8");
+      if (args.search.length === 0) {
+        throw new Error("edit_file: search cannot be empty");
+      }
+      const firstIdx = before.indexOf(args.search);
+      if (firstIdx < 0) {
+        throw new Error(`edit_file: search text not found in ${pathMod.relative(rootDir, abs)}`);
+      }
+      const nextIdx = before.indexOf(args.search, firstIdx + 1);
+      if (nextIdx >= 0) {
+        throw new Error(
+          `edit_file: search text appears multiple times in ${pathMod.relative(rootDir, abs)} — include more context to disambiguate`,
+        );
+      }
+      const after =
+        before.slice(0, firstIdx) + args.replace + before.slice(firstIdx + args.search.length);
+      await fs.writeFile(abs, after, "utf8");
+      const rel = pathMod.relative(rootDir, abs);
+      const header = `edited ${rel} (${args.search.length}→${args.replace.length} chars)`;
+      // Starting line number of the search block in the original
+      // file. `split/length` on the prefix gives a 1-based line
+      // count where the match begins, matching git-diff's @@ -N,M
+      // +N,M @@ header convention.
+      const startLine = before.slice(0, firstIdx).split(/\r?\n/).length;
+      const diff = renderEditDiff(args.search, args.replace, startLine);
+      return `${header}\n${diff}`;
+    },
+  });
+
+  registry.register({
+    name: "create_directory",
+    description: "Create a directory (and any missing parents) under the sandbox root.",
+    parameters: {
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+    },
+    fn: async (args: { path: string }) => {
+      const abs = safePath(args.path);
+      await fs.mkdir(abs, { recursive: true });
+      return `created ${pathMod.relative(rootDir, abs)}/`;
+    },
+  });
+
+  registry.register({
+    name: "move_file",
+    description: "Rename/move a file or directory under the sandbox root.",
+    parameters: {
+      type: "object",
+      properties: {
+        source: { type: "string" },
+        destination: { type: "string" },
+      },
+      required: ["source", "destination"],
+    },
+    fn: async (args: { source: string; destination: string }) => {
+      const src = safePath(args.source);
+      const dst = safePath(args.destination);
+      await fs.mkdir(pathMod.dirname(dst), { recursive: true });
+      await fs.rename(src, dst);
+      return `moved ${pathMod.relative(rootDir, src)} → ${pathMod.relative(rootDir, dst)}`;
+    },
+  });
+
+  return registry;
+}
+
+/**
+ * Format an edit_file change as a proper line-level diff, styled
+ * like `git diff`. Starts with a unified-diff hunk header —
+ * `@@ -startLine,oldCount +startLine,newCount @@` — so the user
+ * can tell where in the file the change lands. Body uses LCS
+ * (longest common subsequence) to mark lines as removed (`-`),
+ * added (`+`), or unchanged context (` `). Users were getting
+ * hundreds of `-` followed by hundreds of `+` for tiny changes
+ * because the naive "dump both sides" format can't tell what
+ * actually moved vs. stayed — this fixes that and adds line-
+ * number context on top.
+ */
+function renderEditDiff(search: string, replace: string, startLine: number): string {
+  const a = search.split(/\r?\n/);
+  const b = replace.split(/\r?\n/);
+  const diff = lineDiff(a, b);
+  const hunk = `@@ -${startLine},${a.length} +${startLine},${b.length} @@`;
+  const body = diff.map((d) => `${d.op === " " ? " " : d.op} ${d.line}`).join("\n");
+  return `${hunk}\n${body}`;
+}
+
+/**
+ * Compute a line-level diff via classic LCS dynamic programming.
+ * Good enough for SEARCH/REPLACE blocks where both sides are
+ * typically under a few hundred lines — O(n*m) space + time. For
+ * huge blocks we'd want Myers' algorithm, but the caller already
+ * caps the inline-display size and `/tool N` shows the full result,
+ * so quadratic is fine in practice.
+ *
+ * Exported so tests can exercise the diff logic without spinning
+ * up the full tool dispatch path.
+ */
+export function lineDiff(
+  a: readonly string[],
+  b: readonly string[],
+): Array<{ op: "-" | "+" | " "; line: string }> {
+  const n = a.length;
+  const m = b.length;
+  // dp[i][j] = LCS length of a[0..i) and b[0..j).
+  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      if (a[i - 1] === b[j - 1]) dp[i]![j] = dp[i - 1]![j - 1]! + 1;
+      else dp[i]![j] = Math.max(dp[i - 1]![j]!, dp[i]![j - 1]!);
+    }
+  }
+  // Backtrack to recover the op sequence.
+  const out: Array<{ op: "-" | "+" | " "; line: string }> = [];
+  let i = n;
+  let j = m;
+  while (i > 0 && j > 0) {
+    if (a[i - 1] === b[j - 1]) {
+      out.unshift({ op: " ", line: a[i - 1]! });
+      i--;
+      j--;
+    } else if ((dp[i - 1]![j] ?? 0) > (dp[i]![j - 1] ?? 0)) {
+      out.unshift({ op: "-", line: a[i - 1]! });
+      i--;
+    } else {
+      // Tie-break goes here (strictly less or equal): take the
+      // insertion first during backtrack so the final forward order
+      // renders removals BEFORE additions for a substitution —
+      // matches git-diff convention of `- old / + new`.
+      out.unshift({ op: "+", line: b[j - 1]! });
+      j--;
+    }
+  }
+  while (i > 0) {
+    out.unshift({ op: "-", line: a[i - 1]! });
+    i--;
+  }
+  while (j > 0) {
+    out.unshift({ op: "+", line: b[j - 1]! });
+    j--;
+  }
+  return out;
+}
@@ -0,0 +1,317 @@
+/**
+ * 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 * 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"]`.
+   */
+  extraAllowed?: 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;
+}
+
+/**
+ * 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 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,
+  };
+
+  return await new Promise<RunCommandResult>((resolve, reject) => {
+    let child: import("node:child_process").ChildProcess;
+    try {
+      child = spawn(argv[0]!, argv.slice(1), spawnOpts);
+    } 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 });
+    });
+  });
+}
+
+/** 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;
+  const extraAllowed = opts.extraAllowed ?? [];
+  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. Read-only and test commands (git status, ls, npm test, pytest, cargo test, grep, etc.) run immediately. Anything that could mutate state (npm install, git commit, rm, chmod) is refused and the user has to confirm in the TUI. Prefer this over asking the user to run a command manually — after edits, run the project's tests to verify.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description:
+            "Full command line, e.g. 'npm test' or 'git diff src/foo.ts'. Tokenized with POSIX-ish quoting; no shell expansion, no pipes, no redirects.",
+        },
+        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, extraAllowed)) {
+        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;
+}
@@ -0,0 +1,299 @@
+/**
+ * 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.",
+    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.",
+    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");
+}
@@ -0,0 +1,50 @@
+/**
+ * Tests for `codeSystemPrompt` — the .gitignore injection helper.
+ * 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";
+
+describe("codeSystemPrompt", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-prompt-"));
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("returns the base prompt unchanged when no .gitignore exists", () => {
+    expect(codeSystemPrompt(root)).toBe(CODE_SYSTEM_PROMPT);
+  });
+
+  it("appends the .gitignore content as a fenced block", () => {
+    writeFileSync(join(root, ".gitignore"), "node_modules/\ndist/\n.env\n", "utf8");
+    const out = codeSystemPrompt(root);
+    expect(out.length).toBeGreaterThan(CODE_SYSTEM_PROMPT.length);
+    expect(out).toMatch(/# Project \.gitignore/);
+    expect(out).toContain("node_modules/");
+    expect(out).toContain(".env");
+  });
+
+  it("truncates a .gitignore larger than 2000 chars", () => {
+    const huge = `${"# comment ".repeat(500)}\n`; // ~5000 chars
+    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);
+  });
+
+  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/);
+  });
+});
@@ -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([]);
+  });
 });
@@ -0,0 +1,265 @@
+/**
+ * Unit tests for SEARCH/REPLACE parsing + application.
+ *
+ * Filesystem tests use a fresh temp dir per test so they don't collide
+ * or leak across runs.
+ */
+
+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 {
+  applyEditBlock,
+  applyEditBlocks,
+  parseEditBlocks,
+  restoreSnapshots,
+  snapshotBeforeEdits,
+} from "../src/code/edit-blocks.js";
+
+describe("parseEditBlocks", () => {
+  it("parses a single block", () => {
+    const text = [
+      "Here is the edit:",
+      "",
+      "src/foo.ts",
+      "<<<<<<< SEARCH",
+      "const x = 1;",
+      "=======",
+      "const x = 2;",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const blocks = parseEditBlocks(text);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toMatchObject({
+      path: "src/foo.ts",
+      search: "const x = 1;",
+      replace: "const x = 2;",
+    });
+  });
+
+  it("parses multiple blocks in one response", () => {
+    const text = [
+      "src/a.ts",
+      "<<<<<<< SEARCH",
+      "old_a",
+      "=======",
+      "new_a",
+      ">>>>>>> REPLACE",
+      "",
+      "src/b.ts",
+      "<<<<<<< SEARCH",
+      "old_b",
+      "=======",
+      "new_b",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const blocks = parseEditBlocks(text);
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]!.path).toBe("src/a.ts");
+    expect(blocks[1]!.path).toBe("src/b.ts");
+  });
+
+  it("handles multi-line SEARCH and REPLACE bodies", () => {
+    const text = [
+      "src/foo.ts",
+      "<<<<<<< SEARCH",
+      "line one",
+      "line two",
+      "line three",
+      "=======",
+      "line one modified",
+      "NEW line",
+      "line three",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const [block] = parseEditBlocks(text);
+    expect(block!.search).toBe("line one\nline two\nline three");
+    expect(block!.replace).toBe("line one modified\nNEW line\nline three");
+  });
+
+  it("recognizes an empty SEARCH (new-file sentinel)", () => {
+    const text = [
+      "src/new.ts",
+      "<<<<<<< SEARCH",
+      "=======",
+      "brand new file",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const [block] = parseEditBlocks(text);
+    expect(block!.search).toBe("");
+    expect(block!.replace).toBe("brand new file");
+  });
+
+  it("returns an empty list when there are no blocks", () => {
+    expect(parseEditBlocks("just prose, no edits here")).toEqual([]);
+  });
+
+  it("ignores stray 7-char runs that aren't part of a real block", () => {
+    // A JS file that happens to contain the marker string in an unrelated context.
+    const text = 'const note = "<<<<<<< not an edit block";\nmore prose';
+    expect(parseEditBlocks(text)).toEqual([]);
+  });
+});
+
+describe("applyEditBlock", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-edit-"));
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("applies a simple replacement", () => {
+    writeFileSync(join(root, "a.txt"), "hello world\n", "utf8");
+    const result = applyEditBlock(
+      { path: "a.txt", search: "hello", replace: "goodbye", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("applied");
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("goodbye world\n");
+  });
+
+  it("creates a new file when SEARCH is empty and file doesn't exist", () => {
+    const result = applyEditBlock(
+      { path: "new/nested/file.ts", search: "", replace: "export const x = 1;\n", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("created");
+    expect(existsSync(join(root, "new/nested/file.ts"))).toBe(true);
+    expect(readFileSync(join(root, "new/nested/file.ts"), "utf8")).toBe("export const x = 1;\n");
+  });
+
+  it("reports not-found when SEARCH doesn't match", () => {
+    writeFileSync(join(root, "a.txt"), "hello world\n", "utf8");
+    const result = applyEditBlock(
+      { path: "a.txt", search: "NOT THERE", replace: "x", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("not-found");
+    // File unchanged.
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("hello world\n");
+  });
+
+  it("reports file-missing when SEARCH is non-empty and file absent", () => {
+    const result = applyEditBlock(
+      { path: "missing.txt", search: "something", replace: "x", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("file-missing");
+  });
+
+  it("refuses paths that escape rootDir", () => {
+    const result = applyEditBlock(
+      { path: "../escape.txt", search: "", replace: "boom", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("path-escape");
+    expect(existsSync(join(root, "..", "escape.txt"))).toBe(false);
+  });
+
+  it("replaces only the first occurrence when SEARCH appears twice", () => {
+    writeFileSync(join(root, "a.txt"), "foo bar foo\n", "utf8");
+    const result = applyEditBlock(
+      { path: "a.txt", search: "foo", replace: "FOO", offset: 0 },
+      root,
+    );
+    expect(result.status).toBe("applied");
+    // First "foo" replaced, second left alone.
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("FOO bar foo\n");
+  });
+});
+
+describe("snapshotBeforeEdits + restoreSnapshots", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-undo-"));
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("restores a modified file to its pre-edit content", () => {
+    writeFileSync(join(root, "a.txt"), "original\n", "utf8");
+    const block = { path: "a.txt", search: "original", replace: "CHANGED", offset: 0 };
+    const snaps = snapshotBeforeEdits([block], root);
+    applyEditBlocks([block], root);
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("CHANGED\n");
+
+    const undoResults = restoreSnapshots(snaps, root);
+    expect(undoResults).toHaveLength(1);
+    expect(undoResults[0]!.status).toBe("applied");
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("original\n");
+  });
+
+  it("deletes a file that was newly created by the edit", () => {
+    const block = { path: "fresh.ts", search: "", replace: "new content", offset: 0 };
+    const snaps = snapshotBeforeEdits([block], root);
+    applyEditBlocks([block], root);
+    expect(existsSync(join(root, "fresh.ts"))).toBe(true);
+
+    restoreSnapshots(snaps, root);
+    expect(existsSync(join(root, "fresh.ts"))).toBe(false);
+  });
+
+  it("de-duplicates per path even when a batch has multiple blocks for the same file", () => {
+    writeFileSync(join(root, "a.txt"), "one two three\n", "utf8");
+    const blocks = [
+      { path: "a.txt", search: "one", replace: "ONE", offset: 0 },
+      { path: "a.txt", search: "two", replace: "TWO", offset: 10 },
+    ];
+    const snaps = snapshotBeforeEdits(blocks, root);
+    expect(snaps).toHaveLength(1); // not 2 — same file
+    expect(snaps[0]!.prevContent).toBe("one two three\n");
+  });
+
+  it("restores multiple files in a single batch independently", () => {
+    writeFileSync(join(root, "a.txt"), "aa\n", "utf8");
+    writeFileSync(join(root, "b.txt"), "bb\n", "utf8");
+    const blocks = [
+      { path: "a.txt", search: "aa", replace: "AAA", offset: 0 },
+      { path: "b.txt", search: "bb", replace: "BBB", offset: 10 },
+    ];
+    const snaps = snapshotBeforeEdits(blocks, root);
+    applyEditBlocks(blocks, root);
+
+    restoreSnapshots(snaps, root);
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("aa\n");
+    expect(readFileSync(join(root, "b.txt"), "utf8")).toBe("bb\n");
+  });
+
+  it("refuses to restore a snapshot whose path escapes rootDir", () => {
+    const fakeSnap = [{ path: "../escape.txt", prevContent: "boom" }];
+    const results = restoreSnapshots(fakeSnap, root);
+    expect(results[0]!.status).toBe("path-escape");
+    expect(existsSync(join(root, "..", "escape.txt"))).toBe(false);
+  });
+});
+
+describe("applyEditBlocks (batch)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "reasonix-edit-"));
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("applies a two-file batch; each result is independent", () => {
+    writeFileSync(join(root, "a.txt"), "alpha\n", "utf8");
+    writeFileSync(join(root, "b.txt"), "bravo\n", "utf8");
+    const results = applyEditBlocks(
+      [
+        { path: "a.txt", search: "alpha", replace: "ALPHA", offset: 0 },
+        { path: "b.txt", search: "NOPE", replace: "X", offset: 10 },
+      ],
+      root,
+    );
+    expect(results).toHaveLength(2);
+    expect(results[0]!.status).toBe("applied");
+    expect(results[1]!.status).toBe("not-found");
+    expect(readFileSync(join(root, "a.txt"), "utf8")).toBe("ALPHA\n");
+    expect(readFileSync(join(root, "b.txt"), "utf8")).toBe("bravo\n"); // untouched
+  });
+});
@@ -0,0 +1,343 @@
+import { promises as fs } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ToolRegistry } from "../src/tools.js";
+import { lineDiff, registerFilesystemTools } from "../src/tools/filesystem.js";
+
+describe("filesystem tools (built-in, sandbox-enforced)", () => {
+  let root: string;
+  let tools: ToolRegistry;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "reasonix-fs-"));
+    tools = new ToolRegistry();
+    registerFilesystemTools(tools, { rootDir: root });
+    await fs.writeFile(join(root, "hello.txt"), "line 1\nline 2\nline 3\n");
+    await fs.mkdir(join(root, "src"), { recursive: true });
+    await fs.writeFile(join(root, "src", "index.ts"), "export const x = 1;\n");
+    await fs.writeFile(join(root, "src", "util.ts"), "export const y = 2;\n");
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  describe("read_file", () => {
+    it("reads the full contents", async () => {
+      const out = await tools.dispatch("read_file", JSON.stringify({ path: "hello.txt" }));
+      expect(out).toContain("line 1");
+      expect(out).toContain("line 3");
+    });
+
+    it("honors head=N to return only the first N lines", async () => {
+      const out = await tools.dispatch("read_file", JSON.stringify({ path: "hello.txt", head: 2 }));
+      expect(out).toBe("line 1\nline 2");
+    });
+
+    it("honors tail=N", async () => {
+      const out = await tools.dispatch("read_file", JSON.stringify({ path: "hello.txt", tail: 2 }));
+      expect(out).toContain("line 2");
+      expect(out).toContain("line 3");
+      expect(out).not.toContain("line 1");
+    });
+
+    it("rejects paths outside the sandbox root", async () => {
+      const out = await tools.dispatch(
+        "read_file",
+        JSON.stringify({ path: "../../../etc/passwd" }),
+      );
+      expect(out).toMatch(/escapes sandbox/);
+    });
+
+    it("rejects absolute paths outside root", async () => {
+      const out = await tools.dispatch("read_file", JSON.stringify({ path: "/etc/passwd" }));
+      expect(out).toMatch(/escapes sandbox/);
+    });
+
+    it("returns a truncation notice when file exceeds maxReadBytes", async () => {
+      const tiny = new ToolRegistry();
+      registerFilesystemTools(tiny, { rootDir: root, maxReadBytes: 10 });
+      const out = await tiny.dispatch("read_file", JSON.stringify({ path: "hello.txt" }));
+      expect(out).toMatch(/truncated/);
+    });
+
+    it("refuses to read a directory as a file", async () => {
+      const out = await tools.dispatch("read_file", JSON.stringify({ path: "src" }));
+      expect(out).toMatch(/not a file/);
+    });
+  });
+
+  describe("list_directory / directory_tree", () => {
+    it("list_directory shows entries with trailing slash for dirs", async () => {
+      const out = await tools.dispatch("list_directory", JSON.stringify({ path: "." }));
+      expect(out).toContain("hello.txt");
+      expect(out).toContain("src/");
+    });
+
+    it("directory_tree recurses", async () => {
+      const out = await tools.dispatch("directory_tree", JSON.stringify({ path: "." }));
+      expect(out).toContain("hello.txt");
+      expect(out).toContain("src/");
+      expect(out).toContain("index.ts");
+      expect(out).toContain("util.ts");
+    });
+
+    it("directory_tree respects maxDepth", async () => {
+      const out = await tools.dispatch(
+        "directory_tree",
+        JSON.stringify({ path: ".", maxDepth: 0 }),
+      );
+      // With depth 0 we list the top level only — no descent into src/.
+      expect(out).toContain("src/");
+      expect(out).not.toContain("index.ts");
+    });
+  });
+
+  describe("search_files", () => {
+    it("finds matching filenames recursively", async () => {
+      const out = await tools.dispatch("search_files", JSON.stringify({ pattern: "index" }));
+      expect(out).toContain("index.ts");
+    });
+
+    it("is case-insensitive", async () => {
+      const out = await tools.dispatch("search_files", JSON.stringify({ pattern: "HELLO" }));
+      expect(out).toContain("hello.txt");
+    });
+
+    it("reports no-matches cleanly", async () => {
+      const out = await tools.dispatch("search_files", JSON.stringify({ pattern: "nothing123" }));
+      expect(out).toBe("(no matches)");
+    });
+  });
+
+  describe("get_file_info", () => {
+    it("returns type + size + mtime as JSON", async () => {
+      const out = await tools.dispatch("get_file_info", JSON.stringify({ path: "hello.txt" }));
+      const parsed = JSON.parse(out);
+      expect(parsed.type).toBe("file");
+      expect(parsed.size).toBeGreaterThan(0);
+      expect(parsed.mtime).toMatch(/\d{4}-\d{2}-\d{2}/);
+    });
+
+    it("reports directories", async () => {
+      const out = await tools.dispatch("get_file_info", JSON.stringify({ path: "src" }));
+      expect(JSON.parse(out).type).toBe("directory");
+    });
+  });
+
+  describe("write_file", () => {
+    it("creates a new file with contents", async () => {
+      const out = await tools.dispatch(
+        "write_file",
+        JSON.stringify({ path: "new.md", content: "hi" }),
+      );
+      expect(out).toMatch(/wrote 2 chars/);
+      const disk = await fs.readFile(join(root, "new.md"), "utf8");
+      expect(disk).toBe("hi");
+    });
+
+    it("creates parent directories as needed", async () => {
+      await tools.dispatch("write_file", JSON.stringify({ path: "a/b/c/deep.txt", content: "x" }));
+      const disk = await fs.readFile(join(root, "a", "b", "c", "deep.txt"), "utf8");
+      expect(disk).toBe("x");
+    });
+
+    it("rejects writes outside the sandbox", async () => {
+      const out = await tools.dispatch(
+        "write_file",
+        JSON.stringify({ path: "../escape.txt", content: "bad" }),
+      );
+      expect(out).toMatch(/escapes sandbox/);
+    });
+  });
+
+  describe("edit_file (flat SEARCH/REPLACE — the anti-DSML shape)", () => {
+    it("replaces a unique search string", async () => {
+      await fs.writeFile(join(root, "a.txt"), "foo bar baz");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search: "bar", replace: "QUX" }),
+      );
+      expect(out).toMatch(/edited/);
+      const disk = await fs.readFile(join(root, "a.txt"), "utf8");
+      expect(disk).toBe("foo QUX baz");
+    });
+
+    it("includes a git-style @@ -N,M +N,M @@ hunk header with the real starting line", async () => {
+      // File has 4 pre-existing lines; SEARCH starts at line 3.
+      // Expected hunk header: @@ -3,1 +3,2 @@ (1 old line → 2 new).
+      await fs.writeFile(join(root, "a.txt"), "alpha\nbeta\nTARGET\ntail\n");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search: "TARGET", replace: "TARGET\nextra" }),
+      );
+      expect(out).toMatch(/@@ -3,1 \+3,2 @@/);
+    });
+
+    it("returns a proper LCS diff with context lines, not just - old / + new", async () => {
+      // The user-reported case: SEARCH is a single line, REPLACE keeps
+      // that line and adds three more below it. A naive dump-both-sides
+      // would show "- line\n+ line\n+ new1\n+ new2\n+ new3" (redundant
+      // `-` for the unchanged line). Proper LCS shows the first line
+      // as context (` `) and only the additions as `+`.
+      await fs.writeFile(
+        join(root, "a.txt"),
+        "const a = doc.getElementById('a');\nconst b = doc.getElementById('b');",
+      );
+      const search = "const a = doc.getElementById('a');";
+      const replace = [
+        "const a = doc.getElementById('a');",
+        "const b2 = doc.getElementById('b2');",
+        "const c = doc.getElementById('c');",
+      ].join("\n");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search, replace }),
+      );
+      // The unchanged first line appears as context (space-prefixed),
+      // NOT as a `-` / `+` pair.
+      expect(out).toContain("  const a = doc.getElementById('a');");
+      // The new lines are `+` prefixed.
+      expect(out).toContain("+ const b2 = doc.getElementById('b2');");
+      expect(out).toContain("+ const c = doc.getElementById('c');");
+      // No line should appear as both `-` and `+` for the preserved
+      // one — that was the old broken behavior.
+      const minuses = out.split("\n").filter((l) => l.startsWith("- "));
+      expect(minuses.some((l) => l.includes("getElementById('a')"))).toBe(false);
+    });
+
+    it("refuses when the search text is not found", async () => {
+      await fs.writeFile(join(root, "a.txt"), "foo bar");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search: "baz", replace: "x" }),
+      );
+      expect(out).toMatch(/not found/);
+    });
+
+    it("refuses when the search text appears multiple times", async () => {
+      await fs.writeFile(join(root, "a.txt"), "cat cat cat");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search: "cat", replace: "dog" }),
+      );
+      expect(out).toMatch(/multiple times/);
+      // File unchanged.
+      const disk = await fs.readFile(join(root, "a.txt"), "utf8");
+      expect(disk).toBe("cat cat cat");
+    });
+
+    it("refuses an empty search", async () => {
+      await fs.writeFile(join(root, "a.txt"), "x");
+      const out = await tools.dispatch(
+        "edit_file",
+        JSON.stringify({ path: "a.txt", search: "", replace: "y" }),
+      );
+      expect(out).toMatch(/search cannot be empty/);
+    });
+  });
+
+  describe("create_directory + move_file", () => {
+    it("create_directory is idempotent (mkdir -p)", async () => {
+      const a = await tools.dispatch("create_directory", JSON.stringify({ path: "d/e/f" }));
+      expect(a).toMatch(/created/);
+      const b = await tools.dispatch("create_directory", JSON.stringify({ path: "d/e/f" }));
+      expect(b).toMatch(/created/);
+      const st = await fs.stat(join(root, "d", "e", "f"));
+      expect(st.isDirectory()).toBe(true);
+    });
+
+    it("move_file renames", async () => {
+      const out = await tools.dispatch(
+        "move_file",
+        JSON.stringify({ source: "hello.txt", destination: "bye.txt" }),
+      );
+      expect(out).toMatch(/moved/);
+      const disk = await fs.readFile(join(root, "bye.txt"), "utf8");
+      expect(disk).toContain("line 1");
+      await expect(fs.stat(join(root, "hello.txt"))).rejects.toThrow();
+    });
+
+    it("move_file into a new subdir creates the parent", async () => {
+      await tools.dispatch(
+        "move_file",
+        JSON.stringify({ source: "hello.txt", destination: "archive/old.txt" }),
+      );
+      const disk = await fs.readFile(join(root, "archive", "old.txt"), "utf8");
+      expect(disk).toContain("line 1");
+    });
+  });
+
+  describe("allowWriting=false (read-only mode)", () => {
+    it("skips registering write_file / edit_file / create_directory / move_file", async () => {
+      const ro = new ToolRegistry();
+      registerFilesystemTools(ro, { rootDir: root, allowWriting: false });
+      expect(ro.has("read_file")).toBe(true);
+      expect(ro.has("list_directory")).toBe(true);
+      expect(ro.has("write_file")).toBe(false);
+      expect(ro.has("edit_file")).toBe(false);
+      expect(ro.has("create_directory")).toBe(false);
+      expect(ro.has("move_file")).toBe(false);
+    });
+  });
+});
+
+describe("lineDiff — LCS line-level diff used by edit_file", () => {
+  it("pure insertion: common prefix as context, new lines as +", () => {
+    const d = lineDiff(["a"], ["a", "b", "c"]);
+    expect(d).toEqual([
+      { op: " ", line: "a" },
+      { op: "+", line: "b" },
+      { op: "+", line: "c" },
+    ]);
+  });
+
+  it("pure deletion: kept lines as context, dropped as -", () => {
+    const d = lineDiff(["a", "b", "c"], ["a"]);
+    expect(d).toEqual([
+      { op: " ", line: "a" },
+      { op: "-", line: "b" },
+      { op: "-", line: "c" },
+    ]);
+  });
+
+  it("substitution: line-in-line-out without touching neighbors", () => {
+    const d = lineDiff(["a", "old", "c"], ["a", "new", "c"]);
+    // "a" and "c" stay as context; "old" → "new" is a -/+ pair.
+    expect(d.map((o) => o.op).join("")).toBe(" -+ ");
+    expect(d.map((o) => o.line)).toEqual(["a", "old", "new", "c"]);
+  });
+
+  it("identical arrays produce pure context (no +/- ops)", () => {
+    const lines = ["a", "b", "c"];
+    const d = lineDiff(lines, lines);
+    expect(d.every((o) => o.op === " ")).toBe(true);
+  });
+
+  it("empty search → all replace lines are added", () => {
+    const d = lineDiff([], ["x", "y"]);
+    expect(d).toEqual([
+      { op: "+", line: "x" },
+      { op: "+", line: "y" },
+    ]);
+  });
+
+  it("handles the user's real case: one-line search → multi-line replace with the line preserved", () => {
+    const search = [
+      "const prestigePointsGainElement = doc.getElementById('prestige-points-gain');",
+    ];
+    const replace = [
+      "const prestigePointsGainElement = doc.getElementById('prestige-points-gain');",
+      "const bonusClickElement = doc.getElementById('bonus-click');",
+      "const bonusCpsElement = doc.getElementById('bonus-cps');",
+    ];
+    const d = lineDiff(search, replace);
+    // First line is context — not a -/+ redundant pair.
+    expect(d[0]!.op).toBe(" ");
+    expect(d[0]!.line).toContain("prestigePointsGainElement");
+    // The rest are pure additions.
+    expect(d.slice(1).every((o) => o.op === "+")).toBe(true);
+  });
+});
@@ -5,7 +5,7 @@
 */

 import { describe, expect, it } from "vitest";
-import { formatLoopError, healLoadedMessages } from "../src/loop.js";
+import { formatLoopError, healLoadedMessages, stripHallucinatedToolMarkup } from "../src/loop.js";
 import type { ChatMessage } from "../src/types.js";

 describe("formatLoopError", () => {
@@ -37,9 +37,15 @@ describe("formatLoopError", () => {
 describe("healLoadedMessages", () => {
  it("truncates a giant tool result, leaves user/assistant messages alone", () => {
    const big = "X".repeat(80_000);
+    // Needs a proper assistant.tool_calls + matching tool response so
+    // the 0.4.12+ validator doesn't prune the tool as stray.
    const messages: ChatMessage[] = [
      { role: "user", content: "read the big file" },
-      { role: "assistant", content: "", tool_calls: [] },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "t1", type: "function", function: { name: "read", arguments: "{}" } }],
+      },
      { role: "tool", tool_call_id: "t1", content: big },
      { role: "assistant", content: "here's what I found" },
    ];
@@ -54,18 +60,30 @@ describe("healLoadedMessages", () => {
    expect(healed[3]).toEqual(messages[3]); // trailing assistant untouched
  });

-  it("is a no-op when every message fits", () => {
+  it("is a no-op when every message fits AND pairing is valid", () => {
    const messages: ChatMessage[] = [
      { role: "user", content: "hi" },
-      { role: "tool", tool_call_id: "t1", content: "small result" },
+      { role: "assistant", content: "hi back" },
    ];
    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
    expect(healedCount).toBe(0);
-    expect(healed).toEqual(messages); // structural equality, same strings
+    expect(healed).toEqual(messages);
  });

-  it("heals multiple oversized tool messages in one pass", () => {
+  it("heals multiple oversized tool messages in one pass (all properly paired)", () => {
+    // Each oversized tool MUST be the response to a preceding
+    // assistant.tool_calls, otherwise the 0.4.12 validator prunes it.
    const messages: ChatMessage[] = [
+      { role: "user", content: "do three things" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [
+          { id: "t1", type: "function", function: { name: "x", arguments: "{}" } },
+          { id: "t2", type: "function", function: { name: "x", arguments: "{}" } },
+          { id: "t3", type: "function", function: { name: "x", arguments: "{}" } },
+        ],
+      },
      { role: "tool", tool_call_id: "t1", content: "A".repeat(40_000) },
      { role: "tool", tool_call_id: "t2", content: "B".repeat(50_000) },
      { role: "tool", tool_call_id: "t3", content: "small" },
@@ -74,4 +92,140 @@ describe("healLoadedMessages", () => {
    expect(healedCount).toBe(2);
    expect(healedFrom).toBe(90_000);
  });
+
+  it("drops stray tool messages that have no preceding assistant.tool_calls", () => {
+    // This is the shape that triggered the "tool must be a response
+    // to a preceding tool_calls" 400 — a tool entry with no opener.
+    const messages: ChatMessage[] = [
+      { role: "user", content: "hi" },
+      { role: "tool", tool_call_id: "stray", content: "orphan result" },
+      { role: "assistant", content: "sure" },
+    ];
+    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
+    expect(healedCount).toBe(1);
+    expect(healed.map((m) => m.role)).toEqual(["user", "assistant"]);
+  });
+
+  it("drops an assistant.tool_calls whose response set is incomplete", () => {
+    // tool_calls declares [a, b], but only tool[a] follows. The
+    // validator can't deliver this to DeepSeek — drops the pair.
+    const messages: ChatMessage[] = [
+      { role: "user", content: "hi" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [
+          { id: "a", type: "function", function: { name: "x", arguments: "{}" } },
+          { id: "b", type: "function", function: { name: "x", arguments: "{}" } },
+        ],
+      },
+      { role: "tool", tool_call_id: "a", content: "partial" },
+      { role: "assistant", content: "trailing note" },
+    ];
+    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
+    expect(healedCount).toBeGreaterThan(0);
+    // Assistant.tool_calls and its partial tool response both dropped;
+    // the trailing plain assistant note survives.
+    expect(healed.map((m) => m.role)).toEqual(["user", "assistant"]);
+    expect(healed[1]!.content).toBe("trailing note");
+  });
+
+  it("strips a dangling assistant-with-tool_calls tail (pre-0.4.12 session files)", () => {
+    const messages: ChatMessage[] = [
+      { role: "user", content: "analyze" },
+      { role: "assistant", content: "sure" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "t1", type: "function", function: { name: "probe", arguments: "{}" } }],
+      },
+      // NO tool response follows — this is the corrupted shape that
+      // DeepSeek 400s on the next user message. Heal must drop it.
+    ];
+    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
+    expect(healedCount).toBe(1);
+    expect(healed).toHaveLength(2);
+    expect(healed[healed.length - 1]!.role).toBe("assistant");
+    expect(healed[healed.length - 1]!.content).toBe("sure");
+  });
+
+  it("strips MULTIPLE trailing assistant-with-tool_calls entries (stacked corruption)", () => {
+    const messages: ChatMessage[] = [
+      { role: "user", content: "go" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "a", type: "function", function: { name: "x", arguments: "{}" } }],
+      },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "b", type: "function", function: { name: "x", arguments: "{}" } }],
+      },
+    ];
+    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
+    // Both dangling assistant entries trimmed; user message survives.
+    expect(healedCount).toBe(2);
+    expect(healed).toHaveLength(1);
+    expect(healed[0]!.role).toBe("user");
+  });
+
+  it("keeps a PAIRED assistant.tool_calls + tool response intact", () => {
+    const messages: ChatMessage[] = [
+      { role: "user", content: "go" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [{ id: "t1", type: "function", function: { name: "x", arguments: "{}" } }],
+      },
+      { role: "tool", tool_call_id: "t1", content: "ok" },
+    ];
+    const { messages: healed, healedCount } = healLoadedMessages(messages, 32_000);
+    expect(healedCount).toBe(0);
+    expect(healed).toEqual(messages);
+  });
+});
+
+describe("stripHallucinatedToolMarkup", () => {
+  it("removes a full DSML function_calls block (the R1 hallucination we saw live)", () => {
+    const input = [
+      "Let me look at the file structure.",
+      "",
+      '<｜DSML｜function_calls> <｜DSML｜invoke name="filesystem_edit_file">',
+      '  <｜DSML｜parameter name="path" string="true">F:.html</｜DSML｜parameter>',
+      '  <｜DSML｜parameter name="edits" string="false">[...]</｜DSML｜parameter>',
+      "</｜DSML｜invoke> </｜DSML｜function_calls>",
+      "",
+      "Saved.",
+    ].join("\n");
+    const out = stripHallucinatedToolMarkup(input);
+    expect(out).toContain("Let me look at the file structure.");
+    expect(out).toContain("Saved.");
+    expect(out).not.toContain("DSML");
+    expect(out).not.toContain("filesystem_edit_file");
+  });
+
+  it("removes an Anthropic-style <function_calls> block", () => {
+    const input = "Here is the plan.\n<function_calls>\n<tool>...</tool>\n</function_calls>\nDone.";
+    const out = stripHallucinatedToolMarkup(input);
+    expect(out).toContain("Here is the plan.");
+    expect(out).toContain("Done.");
+    expect(out).not.toContain("function_calls");
+  });
+
+  it("strips a truncated DSML opener that never gets closed", () => {
+    const input = 'Before the junk.\n<｜DSML｜function_calls> <｜DSML｜invoke name="x"> ...';
+    const out = stripHallucinatedToolMarkup(input);
+    expect(out).toBe("Before the junk.");
+  });
+
+  it("leaves plain prose completely alone", () => {
+    const input = "Just a normal summary with no markup anywhere.";
+    expect(stripHallucinatedToolMarkup(input)).toBe(input);
+  });
+
+  it("returns empty string when ALL content was hallucinated markup", () => {
+    const input = "<｜DSML｜function_calls>garbage</｜DSML｜function_calls>";
+    expect(stripHallucinatedToolMarkup(input)).toBe("");
+  });
 });
@@ -156,6 +156,48 @@ describe("CacheFirstLoop (non-streaming)", () => {
    expect(loop.stats.turns.length).toBe(2); // two model round-trips
  });

+  it("yields tool_start before each tool dispatch so the TUI can show 'running…'", async () => {
+    const client = makeClient([
+      {
+        content: "",
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "add", arguments: '{"a":1,"b":2}' },
+          },
+        ],
+      },
+      { content: "done" },
+    ]);
+    const tools = new ToolRegistry();
+    tools.register<{ a: number; b: number }, number>({
+      name: "add",
+      parameters: {
+        type: "object",
+        properties: { a: { type: "integer" }, b: { type: "integer" } },
+        required: ["a", "b"],
+      },
+      fn: ({ a, b }) => a + b,
+    });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: tools.specs() }),
+      tools,
+      stream: false,
+    });
+
+    const roleOrder: { role: string; toolName?: string }[] = [];
+    for await (const ev of loop.step("go")) {
+      if (ev.role === "tool_start" || ev.role === "tool") {
+        roleOrder.push({ role: ev.role, toolName: ev.toolName });
+      }
+    }
+    // tool_start must precede the matching tool result.
+    expect(roleOrder[0]).toEqual({ role: "tool_start", toolName: "add" });
+    expect(roleOrder[1]).toEqual({ role: "tool", toolName: "add" });
+  });
+
  it("immutable prefix is preserved across turns (cache-stability invariant)", async () => {
    const sharedFetch = fakeFetch([{ content: "a" }, { content: "b" }]);
    const client = new DeepSeekClient({ apiKey: "sk-test", fetch: sharedFetch });
@@ -220,7 +262,7 @@ describe("CacheFirstLoop (non-streaming)", () => {
    expect(warnings[0]).toMatch(/Esc/);
  });

-  it("abort() mid-step diverts to the summary path with an 'aborted' prefix", async () => {
+  it("abort() mid-step stops immediately without a follow-up API call", async () => {
    const reg = new ToolRegistry();
    reg.register({
      name: "probe",
@@ -232,11 +274,15 @@ describe("CacheFirstLoop (non-streaming)", () => {
      content: "",
      tool_calls: [{ id: "c", type: "function", function: { name: "probe", arguments: "{}" } }],
    };
-    // Only one chaining response — after the abort fires on its tool
-    // event, the loop's next API call IS the forced-summary request, so
-    // the summary response needs to be index 1.
-    const responses: FakeResponseShape[] = [chainingToolCall, { content: "partial findings." }];
-    const client = makeClient(responses);
+    // Only one chaining response needed — abort should stop the loop
+    // before any follow-up model call. A second response in the array
+    // would indicate the loop made an unwanted extra API call.
+    const fetchSpy = vi.fn() as unknown as typeof fetch;
+    const responses: FakeResponseShape[] = [chainingToolCall];
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      fetch: fakeFetch(responses) as unknown as typeof fetch,
+    });
    const loop = new CacheFirstLoop({
      client,
      prefix: new ImmutablePrefix({ system: "s", toolSpecs: reg.specs() }),
@@ -247,22 +293,33 @@ describe("CacheFirstLoop (non-streaming)", () => {

    // Call abort AFTER the first tool event fires — simulates the user
    // hitting Esc while the loop is exploring.
-    const events: { role: string; content?: string }[] = [];
+    const events: { role: string; content?: string; forcedSummary?: boolean }[] = [];
    let aborted = false;
    for await (const ev of loop.step("go")) {
-      events.push({ role: ev.role, content: ev.content });
+      events.push({ role: ev.role, content: ev.content, forcedSummary: ev.forcedSummary });
      if (!aborted && ev.role === "tool") {
        aborted = true;
        loop.abort();
      }
    }

+    // Warning fires with the abort notice.
    const warnings = events.filter((e) => e.role === "warning");
-    expect(warnings.some((w) => /aborted/.test(w.content ?? ""))).toBe(true);
+    expect(warnings.some((w) => /aborted at iter/.test(w.content ?? ""))).toBe(true);
+
+    // Synthetic assistant_final is tagged forcedSummary and carries
+    // the stopped-message text. It should NOT contain any model
+    // output because no second API call was made.
    const finals = events.filter((e) => e.role === "assistant_final");
-    const summary = finals[finals.length - 1];
-    expect(summary!.content).toMatch(/aborted by user/);
-    expect(summary!.content).toContain("partial findings.");
+    const stopped = finals[finals.length - 1]!;
+    expect(stopped.forcedSummary).toBe(true);
+    expect(stopped.content).toMatch(/aborted by user \(Esc\)/);
+    expect(stopped.content).toMatch(/no summary produced/);
+
+    // Suite ends with `done`.
+    expect(events[events.length - 1]!.role).toBe("done");
+    // Silence unused-var warning.
+    void fetchSpy;
  });

  it("forces a summary when maxToolIters is exhausted, instead of stopping silently", async () => {
@@ -318,6 +375,152 @@ describe("CacheFirstLoop (non-streaming)", () => {
    expect(events[events.length - 1]!.role).toBe("done");
  });

+  it("context-guard diverts to summary when promptTokens > 80% of the window, tagging forcedSummary", async () => {
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "probe",
+      description: "no-op",
+      parameters: { type: "object", properties: {} },
+      fn: async () => "ok",
+    });
+    // First response: chaining tool call with a prompt-token count
+    // deliberately over 80% of DeepSeek's 131k window (131k * 0.8 = 104_857).
+    // 120k trips the guard.
+    const responses: FakeResponseShape[] = [
+      {
+        content: "",
+        tool_calls: [{ id: "c", type: "function", function: { name: "probe", arguments: "{}" } }],
+        usage: {
+          prompt_tokens: 120_000,
+          completion_tokens: 50,
+          total_tokens: 120_050,
+          prompt_cache_hit_tokens: 90_000,
+          prompt_cache_miss_tokens: 30_000,
+        },
+      },
+      // Forced-summary response (no tools)
+      { content: "based on what I saw, X." },
+    ];
+    const client = makeClient(responses);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: reg.specs() }),
+      tools: reg,
+      stream: false,
+      maxToolIters: 64,
+    });
+
+    const events: { role: string; forcedSummary?: boolean; content?: string }[] = [];
+    for await (const ev of loop.step("analyze the repo")) {
+      events.push({ role: ev.role, forcedSummary: ev.forcedSummary, content: ev.content });
+    }
+
+    // A warning must fire about the context guard. Accept both the
+    // auto-compact-saved-us variant and the nothing-to-compact variant
+    // — the message format shifted in 0.4.11 when we added the
+    // auto-compact attempt before forcing summary.
+    const warn = events.find((e) => e.role === "warning");
+    expect(warn).toBeDefined();
+    expect(warn!.content).toMatch(/context [\d,]+\/[\d,]+/);
+
+    // The final assistant_final must be tagged forcedSummary and carry the context-guard prefix.
+    const finals = events.filter((e) => e.role === "assistant_final");
+    const summary = finals[finals.length - 1];
+    expect(summary!.forcedSummary).toBe(true);
+    expect(summary!.content).toMatch(/context budget running low/);
+  });
+
+  it("context-guard auto-compacts oversized tool results and continues instead of jumping to summary", async () => {
+    // Pre-seed the log with an oversized tool result so compact has
+    // something to shrink. Then the model requests another tool call;
+    // the returned prompt_tokens trips the 80% guard. We expect compact
+    // to run, the warning to mention shrinking, and the loop to
+    // continue with the tool dispatch — no forced summary.
+    const reg = new ToolRegistry();
+    reg.register({
+      name: "probe",
+      description: "no-op",
+      parameters: { type: "object", properties: {} },
+      fn: async () => "ok",
+    });
+    const responses: FakeResponseShape[] = [
+      // Iter 0: chains a tool call, usage trips the guard.
+      {
+        content: "",
+        tool_calls: [{ id: "c1", type: "function", function: { name: "probe", arguments: "{}" } }],
+        usage: {
+          prompt_tokens: 120_000,
+          completion_tokens: 10,
+          total_tokens: 120_010,
+          prompt_cache_hit_tokens: 100_000,
+          prompt_cache_miss_tokens: 20_000,
+        },
+      },
+      // Iter 1: model wraps up normally after the tool result.
+      { content: "done analyzing." },
+    ];
+    const client = makeClient(responses);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: reg.specs() }),
+      tools: reg,
+      stream: false,
+      maxToolIters: 64,
+    });
+    // Put a big tool message into the log so compact has work to do.
+    loop.log.append({ role: "user", content: "do stuff" });
+    loop.log.append({
+      role: "tool",
+      tool_call_id: "prior",
+      content: "Z".repeat(60_000),
+    });
+
+    const events: { role: string; forcedSummary?: boolean; content?: string }[] = [];
+    for await (const ev of loop.step("continue")) {
+      events.push({ role: ev.role, forcedSummary: ev.forcedSummary, content: ev.content });
+    }
+
+    const warn = events.find((e) => e.role === "warning");
+    expect(warn).toBeDefined();
+    expect(warn!.content).toMatch(/auto-compacted \d+ oversized tool result/);
+    // Tool was actually dispatched (we didn't force-summary).
+    expect(events.find((e) => e.role === "tool")).toBeDefined();
+    // Final assistant_final should NOT be tagged forcedSummary — we
+    // took the happy path through the tool and a normal wrap-up.
+    const finals = events.filter((e) => e.role === "assistant_final");
+    const last = finals[finals.length - 1];
+    expect(last!.forcedSummary).toBeFalsy();
+  });
+
+  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
+    // that used to crash the forced-summary call with DeepSeek's
+    // 'insufficient tool messages following tool_calls' error.
+    const client = makeClient([{ content: "summary text" }]);
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s" }),
+      stream: false,
+    });
+    loop.log.append({ role: "user", content: "hi" });
+    loop.log.append({
+      role: "assistant",
+      content: "",
+      tool_calls: [{ id: "x", type: "function", function: { name: "noop", arguments: "{}" } }],
+    });
+    // A chat turn from here should succeed, not 400, because
+    // buildMessages strips the unpaired tail.
+    const events: { role: string; content?: string }[] = [];
+    for await (const ev of loop.step("continue")) {
+      events.push({ role: ev.role, content: ev.content });
+    }
+    expect(events.find((e) => e.role === "error")).toBeUndefined();
+    // The fake fetch echoes the messages it received — no unpaired
+    // assistant+tool_calls should be in there.
+    expect(events.find((e) => e.role === "assistant_final")?.content).toContain("summary text");
+  });
+
  it("surfaces an error event when the HTTP call fails with a non-retryable status", async () => {
    // 401 is non-retryable (bad key). Using this avoids multi-retry waits.
    const errFetch = vi.fn(async () => new Response("boom", { status: 401 }));
@@ -339,3 +542,57 @@ describe("CacheFirstLoop (non-streaming)", () => {
    expect(roles).toContain("error");
  });
 });
+
+describe("CacheFirstLoop (streaming) — tool_call_delta emission", () => {
+  it("yields tool_call_delta events carrying growing arg-char count", async () => {
+    const client = new DeepSeekClient({
+      apiKey: "sk-test",
+      // Fake fetch that streams an SSE body with a multi-chunk tool call.
+      fetch: (async (_url: any, _init: any) => {
+        const frames = [
+          `data: ${JSON.stringify({ choices: [{ delta: { tool_calls: [{ index: 0, id: "c1", function: {} }] } }] })}\n\n`,
+          `data: ${JSON.stringify({ choices: [{ delta: { tool_calls: [{ index: 0, function: { name: "edit_file", arguments: '{"path":"a.txt","search":"' } }] } }] })}\n\n`,
+          `data: ${JSON.stringify({ choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: 'old","replace":"new"}' } }] } }] })}\n\n`,
+          `data: ${JSON.stringify({ choices: [{ finish_reason: "tool_calls", delta: {} }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2, prompt_cache_hit_tokens: 0, prompt_cache_miss_tokens: 1 } })}\n\n`,
+          "data: [DONE]\n\n",
+        ];
+        const body = new ReadableStream({
+          start(ctrl) {
+            for (const f of frames) ctrl.enqueue(new TextEncoder().encode(f));
+            ctrl.close();
+          },
+        });
+        return new Response(body, {
+          status: 200,
+          headers: { "Content-Type": "text/event-stream" },
+        });
+      }) as unknown as typeof fetch,
+    });
+
+    const tools = new ToolRegistry();
+    tools.register({
+      name: "edit_file",
+      parameters: { type: "object", properties: {}, required: [] },
+      fn: () => "ok",
+    });
+    const loop = new CacheFirstLoop({
+      client,
+      prefix: new ImmutablePrefix({ system: "s", toolSpecs: tools.specs() }),
+      tools,
+      stream: true,
+      maxToolIters: 1,
+    });
+
+    const deltas: Array<{ name?: string; chars?: number }> = [];
+    for await (const ev of loop.step("do it")) {
+      if (ev.role === "tool_call_delta") {
+        deltas.push({ name: ev.toolName, chars: ev.toolCallArgsChars });
+      }
+      if (ev.role === "tool_start") break;
+    }
+
+    expect(deltas.length).toBeGreaterThanOrEqual(2);
+    expect(deltas[0]!.name).toBe("edit_file");
+    expect(deltas[deltas.length - 1]!.chars).toBeGreaterThan(deltas[0]!.chars!);
+  });
+});
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { stripMath } from "../src/cli/ui/markdown.js";
+import { parseBlocks, stripMath } from "../src/cli/ui/markdown.js";

 describe("stripMath", () => {
  it("converts \\frac, \\dfrac, \\tfrac uniformly", () => {
@@ -67,3 +67,202 @@ describe("stripMath", () => {
    expect(out).toContain("(d)/(30)");
  });
 });
+
+describe("parseBlocks — SEARCH/REPLACE detection", () => {
+  it("extracts a single SEARCH/REPLACE block into a first-class edit-block", () => {
+    const text = [
+      "Here is the fix:",
+      "",
+      "src/foo.ts",
+      "<<<<<<< SEARCH",
+      "const x = 1;",
+      "=======",
+      "const x = 2;",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const blocks = parseBlocks(text);
+    const edit = blocks.find((b) => b.kind === "edit-block");
+    expect(edit).toBeDefined();
+    if (edit?.kind !== "edit-block") throw new Error("unreachable");
+    expect(edit.filename).toBe("src/foo.ts");
+    expect(edit.search).toBe("const x = 1;");
+    expect(edit.replace).toBe("const x = 2;");
+  });
+
+  it("preserves multi-line SEARCH and REPLACE verbatim (no markdown mangling)", () => {
+    // The original user-reported shape: JSDoc comments inside SEARCH.
+    // Before this fix, `/** ... */` got eaten by bold/italic regex and
+    // `para.join(" ")` collapsed newlines.
+    const text = [
+      "src/code/edit-blocks.ts",
+      "<<<<<<< SEARCH",
+      "/** Edit landed on disk. */",
+      "| 'applied'",
+      "=======",
+      "/** Edit landed on disk. */",
+      "| 'applied-new'",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const [edit] = parseBlocks(text).filter((b) => b.kind === "edit-block");
+    if (edit?.kind !== "edit-block") throw new Error("expected edit-block");
+    // The `/** ... */` and `|` chars survive intact — no `*`-eating,
+    // no newline-flattening.
+    expect(edit.search).toContain("/** Edit landed on disk. */");
+    expect(edit.search).toContain("\n");
+    expect(edit.replace).toContain("'applied-new'");
+  });
+
+  it("recognizes new-file (empty SEARCH) blocks", () => {
+    const text = [
+      "src/new.ts",
+      "<<<<<<< SEARCH",
+      "=======",
+      "export const x = 1;",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const [edit] = parseBlocks(text).filter((b) => b.kind === "edit-block");
+    if (edit?.kind !== "edit-block") throw new Error("expected edit-block");
+    expect(edit.search).toBe("");
+    expect(edit.replace).toBe("export const x = 1;");
+  });
+
+  it("ignores a stray <<<<<<< SEARCH without a filename or close marker", () => {
+    const text = "just some prose with <<<<<<< SEARCH left over in the middle";
+    const blocks = parseBlocks(text);
+    expect(blocks.find((b) => b.kind === "edit-block")).toBeUndefined();
+  });
+
+  it("extracts multiple edit-blocks in one response, keeping the prose between them", () => {
+    const text = [
+      "First change:",
+      "src/a.ts",
+      "<<<<<<< SEARCH",
+      "old_a",
+      "=======",
+      "new_a",
+      ">>>>>>> REPLACE",
+      "",
+      "And second:",
+      "src/b.ts",
+      "<<<<<<< SEARCH",
+      "old_b",
+      "=======",
+      "new_b",
+      ">>>>>>> REPLACE",
+    ].join("\n");
+    const blocks = parseBlocks(text);
+    const edits = blocks.filter((b) => b.kind === "edit-block");
+    expect(edits).toHaveLength(2);
+    const paragraphs = blocks.filter((b) => b.kind === "paragraph");
+    expect(paragraphs.map((p) => (p.kind === "paragraph" ? p.text : ""))).toEqual(
+      expect.arrayContaining(["First change:", "And second:"]),
+    );
+  });
+});
+
+describe("parseBlocks — GFM tables", () => {
+  it("recognizes a simple table with header + separator + rows", () => {
+    const md = [
+      "Intro paragraph.",
+      "",
+      "| 声望点 | 加成效果 |",
+      "|--------|----------|",
+      "| 每2点 | +1 点击力 |",
+      "| 每3点 | +10% CPS 乘数 |",
+      "",
+      "Trailing text.",
+    ].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(["每2点", "+1 点击力"]);
+      expect(table.rows[1]).toEqual(["每3点", "+10% CPS 乘数"]);
+    }
+    // Surrounding paragraphs still parsed as separate blocks.
+    expect(
+      blocks.find((b) => b.kind === "paragraph" && b.text === "Intro paragraph."),
+    ).toBeDefined();
+    expect(blocks.find((b) => b.kind === "paragraph" && b.text === "Trailing text.")).toBeDefined();
+  });
+
+  it("accepts alignment colons in the separator without breaking", () => {
+    const md = ["| col1 | col2 |", "|:-----|-----:|", "| a    | b    |"].join("\n");
+    const [t] = parseBlocks(md).filter((b) => b.kind === "table");
+    expect(t).toBeDefined();
+    if (t && t.kind === "table") {
+      expect(t.header).toEqual(["col1", "col2"]);
+      expect(t.rows[0]).toEqual(["a", "b"]);
+    }
+  });
+
+  it("accepts tables without leading/trailing pipes", () => {
+    const md = ["col1 | col2", "-----|-----", "a    | b"].join("\n");
+    const [t] = parseBlocks(md).filter((b) => b.kind === "table");
+    expect(t).toBeDefined();
+    if (t && t.kind === "table") {
+      expect(t.header).toEqual(["col1", "col2"]);
+      expect(t.rows[0]).toEqual(["a", "b"]);
+    }
+  });
+
+  it("does NOT trigger on a bare '|' in prose when next line is not a separator", () => {
+    const md = ["Use the pipe | operator to chain.", "Second paragraph."].join("\n");
+    const blocks = parseBlocks(md);
+    expect(blocks.find((b) => b.kind === "table")).toBeUndefined();
+  });
+
+  it("preserves escaped pipes inside cell content", () => {
+    const md = ["| a | b |", "|---|---|", "| x \\| y | z |"].join("\n");
+    const [t] = parseBlocks(md).filter((b) => b.kind === "table");
+    expect(t).toBeDefined();
+    if (t && t.kind === "table") {
+      expect(t.rows[0]).toEqual(["x | y", "z"]);
+    }
+  });
+});
+
+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')");
+  });
+});
@@ -0,0 +1,229 @@
+/**
+ * Tests for inspectMcpServer (pure, runs against the fake transport).
+ * We don't unit-test the CLI wrapper — that's just argv parsing and
+ * stdout printing, covered by the integration story of "types compile".
+ */
+
+import { describe, expect, it } from "vitest";
+import { McpClient } from "../src/mcp/client.js";
+import { inspectMcpServer } from "../src/mcp/inspect.js";
+import type { McpTransport } from "../src/mcp/stdio.js";
+import {
+  type JsonRpcMessage,
+  type JsonRpcRequest,
+  MCP_PROTOCOL_VERSION,
+} from "../src/mcp/types.js";
+
+// A minimal in-process transport that answers methods from a handler
+// map. Simpler than the FakeMcpTransport in mcp.test.ts — we only
+// care about shape-of-response here, not call ordering.
+class HandlerTransport implements McpTransport {
+  private readonly queue: JsonRpcMessage[] = [];
+  private readonly waiters: Array<(m: JsonRpcMessage | null) => void> = [];
+  private closed = false;
+  constructor(private readonly handlers: Record<string, (req: JsonRpcRequest) => JsonRpcMessage>) {}
+
+  async send(msg: JsonRpcMessage): Promise<void> {
+    if (this.closed) throw new Error("closed");
+    if (!("id" in msg) || !("method" in msg)) return; // notification from client
+    const req = msg as JsonRpcRequest;
+    const handler = this.handlers[req.method];
+    const response = handler
+      ? handler(req)
+      : {
+          jsonrpc: "2.0",
+          id: req.id,
+          error: { code: -32601, message: `method not found: ${req.method}` },
+        };
+    const w = this.waiters.shift();
+    if (w) w(response as JsonRpcMessage);
+    else this.queue.push(response as JsonRpcMessage);
+  }
+
+  async *messages(): AsyncIterableIterator<JsonRpcMessage> {
+    while (true) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift()!;
+        continue;
+      }
+      if (this.closed) return;
+      const next = await new Promise<JsonRpcMessage | null>((resolve) => {
+        this.waiters.push(resolve);
+      });
+      if (next === null) return;
+      yield next;
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    while (this.waiters.length > 0) this.waiters.shift()!(null);
+  }
+}
+
+function initOk(req: JsonRpcRequest): JsonRpcMessage {
+  return {
+    jsonrpc: "2.0",
+    id: req.id,
+    result: {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      serverInfo: { name: "test-server", version: "1.2.3" },
+      capabilities: { tools: {}, resources: {}, prompts: {} },
+      instructions: "Use tool X before Y.",
+    },
+  };
+}
+
+describe("inspectMcpServer", () => {
+  it("reports server info, capabilities, tools, resources, prompts — full-support server", async () => {
+    const transport = new HandlerTransport({
+      initialize: initOk,
+      "tools/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: {
+          tools: [
+            { name: "echo", description: "echoes", inputSchema: { type: "object" } },
+            { name: "add", description: "a+b", inputSchema: { type: "object" } },
+          ],
+        },
+      }),
+      "resources/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: {
+          resources: [
+            { uri: "file:///a.md", name: "a", mimeType: "text/markdown" },
+            { uri: "custom://b", name: "b" },
+          ],
+        },
+      }),
+      "prompts/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: {
+          prompts: [
+            {
+              name: "summarize",
+              description: "summarize a doc",
+              arguments: [{ name: "lang", required: true }],
+            },
+          ],
+        },
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const report = await inspectMcpServer(client);
+
+    expect(report.protocolVersion).toBe(MCP_PROTOCOL_VERSION);
+    expect(report.serverInfo).toEqual({ name: "test-server", version: "1.2.3" });
+    expect(report.instructions).toBe("Use tool X before Y.");
+    expect(report.tools).toEqual({
+      supported: true,
+      items: expect.arrayContaining([expect.objectContaining({ name: "echo" })]),
+    });
+    expect(report.resources.supported).toBe(true);
+    if (report.resources.supported) {
+      expect(report.resources.items.map((r) => r.name)).toEqual(["a", "b"]);
+    }
+    expect(report.prompts.supported).toBe(true);
+    if (report.prompts.supported) {
+      expect(report.prompts.items[0]!.arguments?.[0]?.name).toBe("lang");
+    }
+
+    await client.close();
+  });
+
+  it("marks resources+prompts as not supported when server returns -32601", async () => {
+    // Tools-only server: init returns, tools/list works, resources/list
+    // + prompts/list fall through to the default -32601 in HandlerTransport.
+    const transport = new HandlerTransport({
+      initialize: initOk,
+      "tools/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: { tools: [] },
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const report = await inspectMcpServer(client);
+
+    expect(report.tools.supported).toBe(true);
+    expect(report.resources.supported).toBe(false);
+    expect(report.prompts.supported).toBe(false);
+    if (!report.resources.supported) {
+      expect(report.resources.reason).toMatch(/-32601/);
+    }
+    if (!report.prompts.supported) {
+      expect(report.prompts.reason).toMatch(/-32601/);
+    }
+
+    await client.close();
+  });
+
+  it("forwards non-32601 errors as the section reason so user sees real diagnostics", async () => {
+    const transport = new HandlerTransport({
+      initialize: initOk,
+      "tools/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        error: { code: -32000, message: "server is overloaded" },
+      }),
+      "resources/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: { resources: [] },
+      }),
+      "prompts/list": (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: { prompts: [] },
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const report = await inspectMcpServer(client);
+
+    expect(report.tools.supported).toBe(false);
+    if (!report.tools.supported) {
+      expect(report.tools.reason).toMatch(/overloaded/);
+    }
+    // Resources and prompts are supported and empty — should not be affected.
+    expect(report.resources.supported).toBe(true);
+    expect(report.prompts.supported).toBe(true);
+
+    await client.close();
+  });
+});
+
+describe("McpClient: initialize records serverInfo + protocolVersion + instructions", () => {
+  it("exposes server info, protocol version, instructions from the handshake", async () => {
+    const transport = new HandlerTransport({ initialize: initOk });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    expect(client.serverInfo).toEqual({ name: "test-server", version: "1.2.3" });
+    expect(client.protocolVersion).toBe(MCP_PROTOCOL_VERSION);
+    expect(client.serverInstructions).toBe("Use tool X before Y.");
+    await client.close();
+  });
+
+  it("leaves serverInstructions undefined when absent from the init result", async () => {
+    const transport = new HandlerTransport({
+      initialize: (req) => ({
+        jsonrpc: "2.0",
+        id: req.id,
+        result: {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          serverInfo: { name: "minimal", version: "0" },
+          capabilities: { tools: {} },
+        },
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    expect(client.serverInstructions).toBeUndefined();
+    await client.close();
+  });
+});
@@ -49,7 +49,7 @@ describe("MCP integration — real subprocess against bundled demo server", () =

    const { tools } = await client.listTools();
    const names = tools.map((t) => t.name).sort();
-    expect(names).toEqual(["add", "echo", "get_time"]);
+    expect(names).toEqual(["add", "echo", "get_time", "slow_count"]);

    const echoResult = await client.callTool("echo", { msg: "hello" });
    const echoText = echoResult.content.map((c) => ("text" in c ? c.text : "")).join("");
@@ -70,7 +70,12 @@ describe("MCP integration — real subprocess against bundled demo server", () =
    await client.initialize();

    const { registry, registeredNames } = await bridgeMcpTools(client, { namePrefix: "demo_" });
-    expect(registeredNames.sort()).toEqual(["demo_add", "demo_echo", "demo_get_time"]);
+    expect(registeredNames.sort()).toEqual([
+      "demo_add",
+      "demo_echo",
+      "demo_get_time",
+      "demo_slow_count",
+    ]);

    // Dispatch through the registry — should round-trip through MCP
    const out = await registry.dispatch("demo_add", JSON.stringify({ a: 100, b: 1 }));
@@ -91,9 +96,9 @@ describe("MCP integration — real subprocess against bundled demo server", () =
      const shared = new ToolRegistry();
      const resA = await bridgeMcpTools(a, { registry: shared, namePrefix: "a_" });
      const resB = await bridgeMcpTools(b, { registry: shared, namePrefix: "b_" });
-      expect(resA.registeredNames).toHaveLength(3);
-      expect(resB.registeredNames).toHaveLength(3);
-      expect(shared.size).toBe(6);
+      expect(resA.registeredNames).toHaveLength(4);
+      expect(resB.registeredNames).toHaveLength(4);
+      expect(shared.size).toBe(8);

      const outA = await shared.dispatch("a_add", JSON.stringify({ a: 10, b: 20 }));
      expect(outA).toContain("30");
@@ -13,10 +13,14 @@ import { bridgeMcpTools, flattenMcpResult } from "../src/mcp/registry.js";
 import type { McpTransport } from "../src/mcp/stdio.js";
 import {
  type CallToolResult,
+  type GetPromptResult,
  type JsonRpcMessage,
  type JsonRpcRequest,
+  type ListPromptsResult,
+  type ListResourcesResult,
  MCP_PROTOCOL_VERSION,
  type McpTool,
+  type ReadResourceResult,
 } from "../src/mcp/types.js";

 // ---------- fake transport ----------
@@ -29,6 +33,16 @@ interface FakeServerOptions {
  errorFor?: Set<string>;
  /** Track every call the server received. */
  received?: JsonRpcRequest[];
+  /** resources/list response. Optional — omit to return empty. */
+  listResources?: () => ListResourcesResult;
+  /** resources/read response keyed by URI. Throw-returns method-not-found for unknowns. */
+  readResource?: (uri: string) => ReadResourceResult;
+  /** prompts/list response. */
+  listPrompts?: () => ListPromptsResult;
+  /** prompts/get response keyed by name. */
+  getPrompt?: (name: string, args?: Record<string, string>) => GetPromptResult;
+  /** Initialize capabilities override — defaults advertise tools only. */
+  capabilities?: Record<string, unknown>;
 }

 /**
@@ -87,7 +101,7 @@ class FakeMcpTransport implements McpTransport {
          result: {
            protocolVersion: MCP_PROTOCOL_VERSION,
            serverInfo: { name: "fake-mcp", version: "0.0.0" },
-            capabilities: { tools: { listChanged: false } },
+            capabilities: this.opts.capabilities ?? { tools: { listChanged: false } },
          },
        };
      case "tools/list":
@@ -110,6 +124,49 @@ class FakeMcpTransport implements McpTransport {
          : { content: [{ type: "text" as const, text: `called ${params.name}` }] };
        return { jsonrpc: "2.0", id: req.id, result };
      }
+      case "resources/list":
+        if (!this.opts.listResources) {
+          return {
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: -32601, message: "method not found: resources/list" },
+          };
+        }
+        return { jsonrpc: "2.0", id: req.id, result: this.opts.listResources() };
+      case "resources/read": {
+        if (!this.opts.readResource) {
+          return {
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: -32601, message: "method not found: resources/read" },
+          };
+        }
+        const { uri } = req.params as { uri: string };
+        return { jsonrpc: "2.0", id: req.id, result: this.opts.readResource(uri) };
+      }
+      case "prompts/list":
+        if (!this.opts.listPrompts) {
+          return {
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: -32601, message: "method not found: prompts/list" },
+          };
+        }
+        return { jsonrpc: "2.0", id: req.id, result: this.opts.listPrompts() };
+      case "prompts/get": {
+        if (!this.opts.getPrompt) {
+          return {
+            jsonrpc: "2.0",
+            id: req.id,
+            error: { code: -32601, message: "method not found: prompts/get" },
+          };
+        }
+        const { name, arguments: a } = req.params as {
+          name: string;
+          arguments?: Record<string, string>;
+        };
+        return { jsonrpc: "2.0", id: req.id, result: this.opts.getPrompt(name, a) };
+      }
      default:
        return {
          jsonrpc: "2.0",
@@ -352,3 +409,522 @@ describe("bridgeMcpTools: result-size cap", () => {
    void transport;
  });
 });
+
+describe("McpClient: abort via AbortSignal", () => {
+  /**
+   * Transport that answers initialize and then stalls on tools/call —
+   * never sends a response. Used to exercise client-side abort:
+   * with no response coming, the promise must still reject promptly
+   * when the signal fires.
+   */
+  function makeStallingTransport(): { transport: McpTransport; received: JsonRpcRequest[] } {
+    const received: JsonRpcRequest[] = [];
+    const queue: JsonRpcMessage[] = [];
+    const waiters: Array<(m: JsonRpcMessage | null) => void> = [];
+    let closed = false;
+    const push = (m: JsonRpcMessage) => {
+      const w = waiters.shift();
+      if (w) w(m);
+      else queue.push(m);
+    };
+    const transport: McpTransport = {
+      async send(msg) {
+        if (closed) throw new Error("closed");
+        if (!("id" in msg) || !("method" in msg)) {
+          received.push(msg as JsonRpcRequest);
+          return;
+        }
+        const req = msg as JsonRpcRequest;
+        received.push(req);
+        if (req.method === "initialize") {
+          push({
+            jsonrpc: "2.0",
+            id: req.id,
+            result: {
+              protocolVersion: MCP_PROTOCOL_VERSION,
+              serverInfo: { name: "stall", version: "0" },
+              capabilities: {},
+            },
+          });
+        }
+        // tools/call: no response, ever.
+      },
+      async *messages() {
+        while (true) {
+          if (queue.length > 0) {
+            yield queue.shift()!;
+            continue;
+          }
+          if (closed) return;
+          const next = await new Promise<JsonRpcMessage | null>((resolve) => {
+            waiters.push(resolve);
+          });
+          if (next === null) return;
+          yield next;
+        }
+      },
+      async close() {
+        closed = true;
+        while (waiters.length > 0) waiters.shift()!(null);
+      },
+    };
+    return { transport, received };
+  }
+
+  it("rejects the pending callTool promise when the signal aborts", async () => {
+    const { transport } = makeStallingTransport();
+    const client = new McpClient({ transport, requestTimeoutMs: 60_000 });
+    await client.initialize();
+    const ctrl = new AbortController();
+    const p = client.callTool("slow", {}, { signal: ctrl.signal });
+    // Fire the abort on the next microtask so the request actually
+    // reaches the transport before we cancel.
+    setTimeout(() => ctrl.abort(), 5);
+    await expect(p).rejects.toThrow(/aborted/);
+    await client.close();
+  });
+
+  it("emits notifications/cancelled with the request id on abort", async () => {
+    const { transport, received } = makeStallingTransport();
+    const client = new McpClient({ transport, requestTimeoutMs: 60_000 });
+    await client.initialize();
+    const ctrl = new AbortController();
+    const p = client.callTool("slow", {}, { signal: ctrl.signal });
+    setTimeout(() => ctrl.abort(), 5);
+    await p.catch(() => {});
+    const callReq = received.find((r) => r.method === "tools/call");
+    const cancelNotif = received.find((r) => r.method === "notifications/cancelled");
+    expect(callReq).toBeDefined();
+    expect(cancelNotif).toBeDefined();
+    expect((cancelNotif!.params as { requestId: number }).requestId).toBe(callReq!.id);
+    await client.close();
+  });
+
+  it("rejects immediately when called with an already-aborted signal", async () => {
+    const { transport } = makeStallingTransport();
+    const client = new McpClient({ transport, requestTimeoutMs: 60_000 });
+    await client.initialize();
+    const ctrl = new AbortController();
+    ctrl.abort();
+    await expect(client.callTool("slow", {}, { signal: ctrl.signal })).rejects.toThrow(/aborted/);
+    await client.close();
+  });
+});
+
+describe("McpClient: progress notifications", () => {
+  /**
+   * Build a transport where tools/call takes multiple "ticks" before
+   * responding — each tick emits a notifications/progress frame tied
+   * to the token the client sent in `_meta.progressToken`.
+   */
+  function makeProgressTransport(
+    progressFrames: Array<{ progress: number; total?: number; message?: string }>,
+  ): { transport: McpTransport; received: JsonRpcRequest[] } {
+    const received: JsonRpcRequest[] = [];
+    const queue: JsonRpcMessage[] = [];
+    const waiters: Array<(m: JsonRpcMessage | null) => void> = [];
+    let closed = false;
+    const push = (m: JsonRpcMessage) => {
+      const w = waiters.shift();
+      if (w) w(m);
+      else queue.push(m);
+    };
+    const transport: McpTransport = {
+      async send(msg) {
+        if (closed) throw new Error("closed");
+        if (!("id" in msg) || !("method" in msg)) return;
+        const req = msg as JsonRpcRequest;
+        received.push(req);
+        if (req.method === "initialize") {
+          push({
+            jsonrpc: "2.0",
+            id: req.id,
+            result: {
+              protocolVersion: MCP_PROTOCOL_VERSION,
+              serverInfo: { name: "fake", version: "0" },
+              capabilities: { tools: {} },
+            },
+          });
+          return;
+        }
+        if (req.method === "tools/call") {
+          const token = (req.params as { _meta?: { progressToken?: string | number } })._meta
+            ?.progressToken;
+          // Emit progress frames first (all with the same token), then
+          // the final response.
+          for (const frame of progressFrames) {
+            push({
+              jsonrpc: "2.0",
+              method: "notifications/progress",
+              params: { progressToken: token, ...frame },
+            });
+          }
+          push({
+            jsonrpc: "2.0",
+            id: req.id,
+            result: { content: [{ type: "text" as const, text: "done" }] },
+          });
+          return;
+        }
+        push({
+          jsonrpc: "2.0",
+          id: req.id,
+          error: { code: -32601, message: "method not found" },
+        });
+      },
+      async *messages() {
+        while (true) {
+          if (queue.length > 0) {
+            yield queue.shift()!;
+            continue;
+          }
+          if (closed) return;
+          const next = await new Promise<JsonRpcMessage | null>((resolve) => {
+            waiters.push(resolve);
+          });
+          if (next === null) return;
+          yield next;
+        }
+      },
+      async close() {
+        closed = true;
+        while (waiters.length > 0) waiters.shift()!(null);
+      },
+    };
+    return { transport, received };
+  }
+
+  it("routes progress notifications to the per-call onProgress callback", async () => {
+    const { transport } = makeProgressTransport([
+      { progress: 1, total: 3, message: "reading..." },
+      { progress: 2, total: 3 },
+      { progress: 3, total: 3, message: "done" },
+    ]);
+    const client = new McpClient({ transport });
+    await client.initialize();
+
+    const received: Array<{ progress: number; total?: number; message?: string }> = [];
+    const result = await client.callTool("scan", {}, { onProgress: (info) => received.push(info) });
+    expect(result.content[0]).toEqual({ type: "text", text: "done" });
+    expect(received).toEqual([
+      { progress: 1, total: 3, message: "reading..." },
+      { progress: 2, total: 3, message: undefined },
+      { progress: 3, total: 3, message: "done" },
+    ]);
+    await client.close();
+  });
+
+  it("omits _meta.progressToken when no onProgress callback is provided", async () => {
+    const { transport, received } = makeProgressTransport([]);
+    const client = new McpClient({ transport });
+    await client.initialize();
+    await client.callTool("x", { k: 1 });
+    const callReq = received.find((r) => r.method === "tools/call")!;
+    expect((callReq.params as { _meta?: unknown })._meta).toBeUndefined();
+    await client.close();
+  });
+
+  it("sets a distinct _meta.progressToken when onProgress IS provided", async () => {
+    const { transport, received } = makeProgressTransport([]);
+    const client = new McpClient({ transport });
+    await client.initialize();
+    await client.callTool("x", {}, { onProgress: () => {} });
+    const callReq = received.find((r) => r.method === "tools/call")!;
+    const token = (callReq.params as { _meta?: { progressToken?: number } })._meta?.progressToken;
+    expect(token).toBeTypeOf("number");
+  });
+
+  it("late progress frames after the call resolved are dropped silently", async () => {
+    // Use the handler-transport shape from progress-transport: we
+    // send the final result, THEN push a trailing progress frame.
+    // The client must not throw when the handler map is already empty.
+    const received: JsonRpcRequest[] = [];
+    const queue: JsonRpcMessage[] = [];
+    const waiters: Array<(m: JsonRpcMessage | null) => void> = [];
+    let closed = false;
+    const push = (m: JsonRpcMessage) => {
+      const w = waiters.shift();
+      if (w) w(m);
+      else queue.push(m);
+    };
+    let lastToken: string | number | undefined;
+    const transport: McpTransport = {
+      async send(msg) {
+        if (!("id" in msg) || !("method" in msg)) return;
+        const req = msg as JsonRpcRequest;
+        received.push(req);
+        if (req.method === "initialize") {
+          push({
+            jsonrpc: "2.0",
+            id: req.id,
+            result: {
+              protocolVersion: MCP_PROTOCOL_VERSION,
+              serverInfo: { name: "fake", version: "0" },
+              capabilities: {},
+            },
+          });
+        } else if (req.method === "tools/call") {
+          lastToken = (req.params as { _meta?: { progressToken?: string | number } })._meta
+            ?.progressToken;
+          // Final response first, then a trailing progress — mimics
+          // a race where the server finished but a progress frame
+          // was already in flight.
+          push({
+            jsonrpc: "2.0",
+            id: req.id,
+            result: { content: [] },
+          });
+          push({
+            jsonrpc: "2.0",
+            method: "notifications/progress",
+            params: { progressToken: lastToken, progress: 42 },
+          });
+        }
+      },
+      async *messages() {
+        while (true) {
+          if (queue.length > 0) {
+            yield queue.shift()!;
+            continue;
+          }
+          if (closed) return;
+          const next = await new Promise<JsonRpcMessage | null>((resolve) => {
+            waiters.push(resolve);
+          });
+          if (next === null) return;
+          yield next;
+        }
+      },
+      async close() {
+        closed = true;
+        while (waiters.length > 0) waiters.shift()!(null);
+      },
+    };
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const seen: number[] = [];
+    await client.callTool("x", {}, { onProgress: (i) => seen.push(i.progress) });
+    // Give the reader loop a tick to process the trailing
+    // notification — should be swallowed, not thrown.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(seen).toEqual([]); // the trailing frame was dropped
+    await client.close();
+  });
+});
+
+describe("bridgeMcpTools: progress pass-through", () => {
+  it("threads per-tool progress callbacks with the registered (prefixed) name", async () => {
+    const { transport } = (function makeProgressTransport(
+      frames: Array<{ progress: number; total?: number }>,
+    ) {
+      const queue: JsonRpcMessage[] = [];
+      const waiters: Array<(m: JsonRpcMessage | null) => void> = [];
+      let closed = false;
+      const push = (m: JsonRpcMessage) => {
+        const w = waiters.shift();
+        if (w) w(m);
+        else queue.push(m);
+      };
+      const t: McpTransport = {
+        async send(msg) {
+          if (!("id" in msg) || !("method" in msg)) return;
+          const req = msg as JsonRpcRequest;
+          if (req.method === "initialize") {
+            push({
+              jsonrpc: "2.0",
+              id: req.id,
+              result: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                serverInfo: { name: "fs", version: "0" },
+                capabilities: { tools: {} },
+              },
+            });
+          } else if (req.method === "tools/list") {
+            push({
+              jsonrpc: "2.0",
+              id: req.id,
+              result: {
+                tools: [{ name: "scan", description: "", inputSchema: { type: "object" } }],
+              },
+            });
+          } else if (req.method === "tools/call") {
+            const token = (req.params as { _meta?: { progressToken?: string | number } })._meta
+              ?.progressToken;
+            for (const f of frames) {
+              push({
+                jsonrpc: "2.0",
+                method: "notifications/progress",
+                params: { progressToken: token, ...f },
+              });
+            }
+            push({
+              jsonrpc: "2.0",
+              id: req.id,
+              result: { content: [{ type: "text" as const, text: "ok" }] },
+            });
+          }
+        },
+        async *messages() {
+          while (true) {
+            if (queue.length > 0) {
+              yield queue.shift()!;
+              continue;
+            }
+            if (closed) return;
+            const next = await new Promise<JsonRpcMessage | null>((resolve) => {
+              waiters.push(resolve);
+            });
+            if (next === null) return;
+            yield next;
+          }
+        },
+        async close() {
+          closed = true;
+          while (waiters.length > 0) waiters.shift()!(null);
+        },
+      };
+      return { transport: t };
+    })([{ progress: 5, total: 10 }]);
+
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const observed: Array<{ toolName: string; progress: number; total?: number }> = [];
+    const { registry } = await bridgeMcpTools(client, {
+      namePrefix: "fs_",
+      onProgress: ({ toolName, progress, total }) => observed.push({ toolName, progress, total }),
+    });
+    await registry.dispatch("fs_scan", "{}");
+    expect(observed).toEqual([{ toolName: "fs_scan", progress: 5, total: 10 }]);
+    await client.close();
+  });
+});
+
+describe("McpClient: resources", () => {
+  it("lists resources and reads one by URI", async () => {
+    const transport = new FakeMcpTransport({
+      tools: [],
+      capabilities: { tools: {}, resources: { listChanged: false } },
+      listResources: () => ({
+        resources: [
+          { uri: "file:///a.md", name: "a", mimeType: "text/markdown" },
+          { uri: "custom://b", name: "b" },
+        ],
+      }),
+      readResource: (uri) => ({
+        contents: [{ uri, mimeType: "text/plain", text: `body of ${uri}` }],
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+
+    const list = await client.listResources();
+    expect(list.resources).toHaveLength(2);
+    expect(list.resources[0]!.uri).toBe("file:///a.md");
+
+    const read = await client.readResource("file:///a.md");
+    expect(read.contents).toHaveLength(1);
+    const block = read.contents[0]!;
+    expect("text" in block ? block.text : "").toBe("body of file:///a.md");
+    expect(block.mimeType).toBe("text/plain");
+
+    await client.close();
+  });
+
+  it("surfaces method-not-found as an error when the server lacks resources support", async () => {
+    // Default FakeMcpTransport (no listResources handler) → −32601.
+    const transport = new FakeMcpTransport({ tools: [] });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    await expect(client.listResources()).rejects.toThrow(/-32601/);
+    await client.close();
+  });
+
+  it("advertises resources + prompts in the initialize capabilities payload", async () => {
+    const received: JsonRpcRequest[] = [];
+    const transport = new FakeMcpTransport({ tools: [], received });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    const init = received.find((r) => r.method === "initialize")!;
+    const params = init.params as { capabilities: Record<string, unknown> };
+    // The client now claims to support all three method families.
+    expect(params.capabilities).toHaveProperty("tools");
+    expect(params.capabilities).toHaveProperty("resources");
+    expect(params.capabilities).toHaveProperty("prompts");
+    await client.close();
+  });
+
+  it("propagates the pagination cursor to resources/list", async () => {
+    const received: JsonRpcRequest[] = [];
+    const transport = new FakeMcpTransport({
+      tools: [],
+      received,
+      listResources: () => ({ resources: [], nextCursor: undefined }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    await client.listResources("page2");
+    const listReq = received.find((r) => r.method === "resources/list")!;
+    expect((listReq.params as { cursor?: string }).cursor).toBe("page2");
+    await client.close();
+  });
+});
+
+describe("McpClient: prompts", () => {
+  it("lists prompts and fetches a rendered one with arguments", async () => {
+    const transport = new FakeMcpTransport({
+      tools: [],
+      capabilities: { tools: {}, prompts: { listChanged: false } },
+      listPrompts: () => ({
+        prompts: [
+          {
+            name: "summarize",
+            description: "summarize a document",
+            arguments: [{ name: "lang", required: true }],
+          },
+        ],
+      }),
+      getPrompt: (name, args) => ({
+        description: `rendered ${name}`,
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: `please summarize in ${args?.lang ?? "?"}` },
+          },
+        ],
+      }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+
+    const list = await client.listPrompts();
+    expect(list.prompts).toHaveLength(1);
+    expect(list.prompts[0]!.name).toBe("summarize");
+    expect(list.prompts[0]!.arguments?.[0]?.required).toBe(true);
+
+    const got = await client.getPrompt("summarize", { lang: "zh" });
+    expect(got.messages).toHaveLength(1);
+    const msg = got.messages[0]!;
+    expect(msg.role).toBe("user");
+    expect(msg.content.type).toBe("text");
+    if (msg.content.type === "text") {
+      expect(msg.content.text).toContain("zh");
+    }
+
+    await client.close();
+  });
+
+  it("omits the arguments field when caller passes no args", async () => {
+    const received: JsonRpcRequest[] = [];
+    const transport = new FakeMcpTransport({
+      tools: [],
+      received,
+      getPrompt: () => ({ messages: [] }),
+    });
+    const client = new McpClient({ transport });
+    await client.initialize();
+    await client.getPrompt("hello");
+    const getReq = received.find((r) => r.method === "prompts/get")!;
+    expect(getReq.params).toEqual({ name: "hello" });
+    await client.close();
+  });
+});
@@ -0,0 +1,245 @@
+import { describe, expect, it } from "vitest";
+import {
+  type MultilineKey,
+  lineAndColumn,
+  processMultilineKey,
+} from "../src/cli/ui/multiline-keys.js";
+
+function key(overrides: Partial<MultilineKey> = {}): MultilineKey {
+  return { input: "", ...overrides };
+}
+
+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 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);
+  });
+});
+
+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");
+  });
+
+  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("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("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 });
+  });
+});
@@ -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/);
+    });
+  });
+});
@@ -47,4 +47,33 @@ describe("ToolCallRepair pipeline", () => {
    expect(calls.length).toBe(1);
    expect(report.scavenged).toBe(0);
  });
+
+  it("scavenges DSML tool calls from the content channel (regular turn, not just reasoning)", () => {
+    // R1 sometimes emits the DSML envelope in the content stream
+    // instead of the proper tool_calls field. Before this wire-up,
+    // the model's intent was silently dropped.
+    const repair = new ToolCallRepair({
+      allowedToolNames: new Set(["filesystem_read_file"]),
+    });
+    const content = [
+      "I'll read the file next.",
+      '<｜DSML｜invoke name="filesystem_read_file">',
+      '  <｜DSML｜parameter name="path" string="true">README.md</｜DSML｜parameter>',
+      "</｜DSML｜invoke>",
+    ].join("\n");
+    const { calls, report } = repair.process([], null, content);
+    expect(calls.length).toBe(1);
+    expect(calls[0]!.function.name).toBe("filesystem_read_file");
+    expect(JSON.parse(calls[0]!.function.arguments)).toEqual({ path: "README.md" });
+    expect(report.scavenged).toBe(1);
+  });
+
+  it("does not double-count when DSML appears in both reasoning and content", () => {
+    const repair = new ToolCallRepair({ allowedToolNames: new Set(["search"]) });
+    const dsml =
+      '<｜DSML｜invoke name="search"><｜DSML｜parameter name="q" string="true">ts</｜DSML｜parameter></｜DSML｜invoke>';
+    const { calls, report } = repair.process([], dsml, dsml);
+    expect(calls.length).toBe(1);
+    expect(report.scavenged).toBe(1);
+  });
 });
@@ -44,4 +44,60 @@ describe("scavengeToolCalls", () => {
    const r = scavengeToolCalls(reasoning, { allowedNames: allowed, maxCalls: 2 });
    expect(r.calls.length).toBe(2);
  });
+
+  it("extracts a DSML invoke block with string + JSON parameters", () => {
+    const dsmlAllowed = new Set(["filesystem_edit_file"]);
+    const input = [
+      "Let me make the edit.",
+      "",
+      '<｜DSML｜function_calls> <｜DSML｜invoke name="filesystem_edit_file">',
+      '  <｜DSML｜parameter name="path" string="true">F:/x.html</｜DSML｜parameter>',
+      '  <｜DSML｜parameter name="edits" string="false">[{"oldText":"a","newText":"b"}]</｜DSML｜parameter>',
+      "</｜DSML｜invoke> </｜DSML｜function_calls>",
+    ].join("\n");
+    const r = scavengeToolCalls(input, { allowedNames: dsmlAllowed });
+    expect(r.calls.length).toBe(1);
+    const call = r.calls[0]!;
+    expect(call.function.name).toBe("filesystem_edit_file");
+    const args = JSON.parse(call.function.arguments);
+    expect(args.path).toBe("F:/x.html");
+    expect(args.edits).toEqual([{ oldText: "a", newText: "b" }]);
+    expect(r.notes[0]).toMatch(/DSML/);
+  });
+
+  it("accepts ASCII pipe DSML variant too", () => {
+    const dsmlAllowed = new Set(["search"]);
+    const input =
+      '<|DSML|invoke name="search"><|DSML|parameter name="q" string="true">ts</|DSML|parameter></|DSML|invoke>';
+    const r = scavengeToolCalls(input, { allowedNames: dsmlAllowed });
+    expect(r.calls.length).toBe(1);
+    expect(JSON.parse(r.calls[0]!.function.arguments)).toEqual({ q: "ts" });
+  });
+
+  it("DSML call with unknown tool name is skipped (allow-list guards us)", () => {
+    const input =
+      '<｜DSML｜invoke name="rm_rf_slash"><｜DSML｜parameter name="x" string="true">y</｜DSML｜parameter></｜DSML｜invoke>';
+    const r = scavengeToolCalls(input, { allowedNames: allowed });
+    expect(r.calls).toEqual([]);
+  });
+
+  it("DSML 'string=false' with malformed JSON falls back to literal text (loses no data)", () => {
+    const dsmlAllowed = new Set(["search"]);
+    const input =
+      '<｜DSML｜invoke name="search"><｜DSML｜parameter name="q" string="false">not valid json</｜DSML｜parameter></｜DSML｜invoke>';
+    const r = scavengeToolCalls(input, { allowedNames: dsmlAllowed });
+    expect(r.calls.length).toBe(1);
+    expect(JSON.parse(r.calls[0]!.function.arguments)).toEqual({ q: "not valid json" });
+  });
+
+  it("does not double-count: JSON args inside a DSML block don't become separate calls", () => {
+    const dsmlAllowed = new Set(["filesystem_edit_file"]);
+    // The inner JSON is a param value, not a standalone scavenge target.
+    const input =
+      '<｜DSML｜invoke name="filesystem_edit_file"><｜DSML｜parameter name="edits" string="false">{"name": "filesystem_edit_file", "arguments": {}}</｜DSML｜parameter></｜DSML｜invoke>';
+    const r = scavengeToolCalls(input, { allowedNames: dsmlAllowed });
+    // Expect exactly one call — the DSML wrapper. If Pattern B also
+    // fired on the inner JSON we'd see two.
+    expect(r.calls.length).toBe(1);
+  });
 });
@@ -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("");
+  });
+});
@@ -0,0 +1,220 @@
+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,
+  formatCommandResult,
+  isAllowed,
+  registerShellTools,
+  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("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");
+  });
+});
+
+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("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/);
+  });
+});
@@ -1,6 +1,14 @@
-import { describe, expect, it, vi } from "vitest";
-import { handleSlash, parseSlash } from "../src/cli/ui/slash.js";
-import { DeepSeekClient } from "../src/client.js";
+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,
+  handleSlash,
+  parseSlash,
+  suggestSlashCommands,
+} from "../src/cli/ui/slash.js";
+import { DeepSeekClient, Usage } from "../src/client.js";
 import { CacheFirstLoop } from "../src/loop.js";
 import { ImmutablePrefix } from "../src/memory.js";

@@ -35,8 +43,40 @@ describe("handleSlash", () => {
    expect(handleSlash("quit", [], loop).exit).toBe(true);
  });

-  it("/clear requests history clear", () => {
-    expect(handleSlash("clear", [], makeLoop()).clear).toBe(true);
+  it("/clear requests history clear + surfaces an info line about what it does", () => {
+    const r = handleSlash("clear", [], makeLoop());
+    expect(r.clear).toBe(true);
+    // Clear should also explain that context is NOT dropped — users
+    // keep confusing this with /new.
+    expect(r.info).toMatch(/visible scrollback only/);
+    expect(r.info).toMatch(/\/new/);
+  });
+
+  it("/new drops in-memory context AND clears scrollback", () => {
+    const loop = makeLoop();
+    loop.log.append({ role: "user", content: "message 1" });
+    loop.log.append({ role: "assistant", content: "reply 1" });
+    loop.log.append({ role: "user", content: "message 2" });
+    expect(loop.log.length).toBe(3);
+    const r = handleSlash("new", [], loop);
+    expect(r.clear).toBe(true);
+    expect(r.info).toMatch(/dropped 3/);
+    expect(loop.log.length).toBe(0);
+  });
+
+  it("/reset is an alias for /new (muscle memory)", () => {
+    const loop = makeLoop();
+    loop.log.append({ role: "user", content: "hi" });
+    const r = handleSlash("reset", [], loop);
+    expect(r.clear).toBe(true);
+    expect(loop.log.length).toBe(0);
+  });
+
+  it("/help distinguishes /clear (visual-only) from /new (drops context)", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/new/);
+    // Wording explicitly notes context is kept on /clear.
+    expect(r.info).toMatch(/clear displayed scrollback only/);
  });

  it("/help returns a multi-line message", () => {
@@ -49,7 +89,9 @@ describe("handleSlash", () => {
  it("/status reflects current loop config", () => {
    const loop = makeLoop();
    const r = handleSlash("status", [], loop);
-    expect(r.info).toMatch(/model=/);
+    // New format: indented table with labeled rows ("model", "flags",
+    // "ctx", "mcp", "session"). Harvest/branch live on the flags row.
+    expect(r.info).toMatch(/model\s+deepseek-/);
    expect(r.info).toMatch(/harvest=off/);
    expect(r.info).toMatch(/branch=off/);
  });
@@ -228,6 +270,307 @@ describe("handleSlash", () => {
    expect(r.info).toMatch(/\/setup/);
  });

+  it("/undo outside code mode says it's not available", () => {
+    const r = handleSlash("undo", [], makeLoop());
+    expect(r.info).toMatch(/only available inside .reasonix code/);
+  });
+
+  it("/undo in code mode invokes the callback", () => {
+    const r = handleSlash("undo", [], makeLoop(), {
+      codeUndo: () => "▸ restored 2 file(s)",
+    });
+    expect(r.info).toMatch(/restored 2 file/);
+  });
+
+  it("/help mentions /undo and /commit", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/undo/);
+    expect(r.info).toMatch(/\/commit/);
+  });
+
+  it("/commit outside code mode says it's not available", () => {
+    const r = handleSlash("commit", ["foo"], makeLoop());
+    expect(r.info).toMatch(/only available inside .reasonix code/);
+  });
+
+  it("/commit with no message prints usage", () => {
+    const r = handleSlash("commit", [], makeLoop(), { codeRoot: "/tmp" });
+    expect(r.info).toMatch(/usage: \/commit/);
+  });
+
+  it("/apply outside code mode says it's not available", () => {
+    const r = handleSlash("apply", [], makeLoop());
+    expect(r.info).toMatch(/only available inside .reasonix code/);
+  });
+
+  it("/apply in code mode invokes the callback", () => {
+    const r = handleSlash("apply", [], makeLoop(), {
+      codeApply: () => "▸ 2/2 edits applied",
+    });
+    expect(r.info).toMatch(/2\/2 edits applied/);
+  });
+
+  it("/discard outside code mode says it's not available", () => {
+    const r = handleSlash("discard", [], makeLoop());
+    expect(r.info).toMatch(/only available inside .reasonix code/);
+  });
+
+  it("/discard in code mode invokes the callback", () => {
+    const r = handleSlash("discard", [], makeLoop(), {
+      codeDiscard: () => "▸ discarded 3 pending",
+    });
+    expect(r.info).toMatch(/discarded 3 pending/);
+  });
+
+  it("/help mentions /apply and /discard", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/apply/);
+    expect(r.info).toMatch(/\/discard/);
+  });
+
+  it("/think says no reasoning cached when scratch is empty", () => {
+    const r = handleSlash("think", [], makeLoop());
+    expect(r.info).toMatch(/no reasoning cached/);
+  });
+
+  it("/think dumps the full reasoning when scratch has content", () => {
+    const loop = makeLoop();
+    loop.scratch.reasoning = "lots of R1 deliberation here over many sentences";
+    const r = handleSlash("think", [], loop);
+    expect(r.info).toMatch(/full thinking/);
+    expect(r.info).toContain("lots of R1 deliberation");
+  });
+
+  it("/help mentions /think", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/think/);
+  });
+
+  it("/retry returns info + resubmit when there's a prior user message", () => {
+    const loop = makeLoop();
+    loop.log.append({ role: "user", content: "hello" });
+    loop.log.append({ role: "assistant", content: "hi back" });
+    const r = handleSlash("retry", [], loop);
+    expect(r.resubmit).toBe("hello");
+    expect(r.info).toMatch(/retrying/);
+    // After retry, the log should be empty (last user message and
+    // everything after were dropped; user will be re-pushed on next
+    // successful turn).
+    expect(loop.log.length).toBe(0);
+  });
+
+  it("/retry says nothing to retry when log has no user messages", () => {
+    const r = handleSlash("retry", [], makeLoop());
+    expect(r.info).toMatch(/nothing to retry/);
+    expect(r.resubmit).toBeUndefined();
+  });
+
+  it("/help mentions /retry", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/retry/);
+  });
+
+  it("/tool with no history says none yet", () => {
+    const r = handleSlash("tool", [], makeLoop());
+    expect(r.info).toMatch(/no tool calls yet/);
+  });
+
+  it("/tool with history lists entries, most recent first", () => {
+    const r = handleSlash("tool", [], makeLoop(), {
+      toolHistory: () => [
+        { toolName: "fs_read_file", text: "old content" },
+        { toolName: "fs_list_directory", text: "newer content" },
+      ],
+    });
+    expect(r.info).toMatch(/Tool calls in this session \(2/);
+    // Most recent is #1 — the list must order so fs_list_directory
+    // (newer) appears before fs_read_file (older).
+    const idxNewer = r.info!.indexOf("fs_list_directory");
+    const idxOlder = r.info!.indexOf("fs_read_file");
+    expect(idxNewer).toBeGreaterThan(-1);
+    expect(idxOlder).toBeGreaterThan(idxNewer);
+  });
+
+  it("/tool N dumps the Nth-most-recent tool output in full", () => {
+    const big = "X".repeat(2000);
+    const r = handleSlash("tool", ["1"], makeLoop(), {
+      toolHistory: () => [
+        { toolName: "fs_read_file", text: "older" },
+        { toolName: "fs_list_directory", text: big },
+      ],
+    });
+    expect(r.info).toMatch(/tool<fs_list_directory>/);
+    expect(r.info).toMatch(/2000 chars/);
+    // Full 2000 X's included — not truncated.
+    expect(r.info).toContain(big);
+  });
+
+  it("/tool 2 reaches one call back from the most recent", () => {
+    const r = handleSlash("tool", ["2"], makeLoop(), {
+      toolHistory: () => [
+        { toolName: "fs_read_file", text: "target" },
+        { toolName: "fs_list_directory", text: "most recent" },
+      ],
+    });
+    expect(r.info).toMatch(/tool<fs_read_file>/);
+    expect(r.info).toContain("target");
+  });
+
+  it("/tool N past history length reports bounds", () => {
+    const r = handleSlash("tool", ["5"], makeLoop(), {
+      toolHistory: () => [{ toolName: "fs_read_file", text: "one" }],
+    });
+    expect(r.info).toMatch(/only 1 tool call/);
+  });
+
+  it("/tool with non-numeric arg returns usage", () => {
+    const r = handleSlash("tool", ["huh"], makeLoop(), {
+      toolHistory: () => [{ toolName: "fs_read_file", text: "one" }],
+    });
+    expect(r.info).toMatch(/usage: \/tool/);
+  });
+
+  it("/tool list trims the display to 10 most recent but hints at older", () => {
+    const many = Array.from({ length: 15 }, (_, i) => ({
+      toolName: `t${i}`,
+      text: `call-${i}`,
+    }));
+    const r = handleSlash("tool", [], makeLoop(), { toolHistory: () => many });
+    // Most recent (#1 = t14) and 10th back (#10 = t5) should be shown.
+    expect(r.info).toContain("t14");
+    expect(r.info).toContain("t5");
+    // t4 would be #11 — beyond the first-page cutoff.
+    expect(r.info).toMatch(/5 earlier.*reach with \/tool N/);
+  });
+
+  it("/help mentions /tool", () => {
+    const r = handleSlash("help", [], makeLoop());
+    expect(r.info).toMatch(/\/tool/);
+  });
+
+  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
+    // should also show up in suggestions — bump this list when
+    // adding.
+    const names = SLASH_COMMANDS.map((s) => s.cmd);
+    for (const required of [
+      "help",
+      "status",
+      "preset",
+      "model",
+      "branch",
+      "mcp",
+      "tool",
+      "memory",
+      "think",
+      "retry",
+      "compact",
+      "sessions",
+      "clear",
+      "exit",
+      "apply",
+      "discard",
+      "undo",
+      "commit",
+    ]) {
+      expect(names, `registry missing /${required}`).toContain(required);
+    }
+  });
+
+  it("suggestSlashCommands filters by prefix", () => {
+    expect(suggestSlashCommands("h").map((s) => s.cmd)).toEqual(["help", "harvest"]);
+    // Case-insensitive.
+    expect(suggestSlashCommands("HE").map((s) => s.cmd)).toEqual(["help"]);
+    // Empty prefix returns everything (non-contextual).
+    expect(suggestSlashCommands("").length).toBeGreaterThan(5);
+  });
+
+  it("suggestSlashCommands hides code-mode-only entries when codeMode=false", () => {
+    const names = suggestSlashCommands("", false).map((s) => s.cmd);
+    expect(names).not.toContain("apply");
+    expect(names).not.toContain("undo");
+  });
+
+  it("suggestSlashCommands shows code-mode-only entries when codeMode=true", () => {
+    const names = suggestSlashCommands("", true).map((s) => s.cmd);
+    expect(names).toContain("apply");
+    expect(names).toContain("undo");
+  });
+
+  it("/mcp with mcpServers renders per-server tools+resources+prompts", () => {
+    const r = handleSlash("mcp", [], makeLoop(), {
+      mcpServers: [
+        {
+          label: "fs",
+          spec: "fs=npx -y @scope/fs /tmp",
+          toolCount: 4,
+          report: {
+            protocolVersion: "2024-11-05",
+            serverInfo: { name: "fs-server", version: "1.0.0" },
+            capabilities: { tools: {}, resources: {} },
+            tools: { supported: true, items: [] },
+            resources: {
+              supported: true,
+              items: [
+                { uri: "file:///a", name: "docs" },
+                { uri: "file:///b", name: "readme" },
+              ],
+            },
+            prompts: { supported: false, reason: "method not found (-32601)" },
+          },
+        },
+      ],
+    });
+    expect(r.info).toMatch(/\[fs\].*fs-server v1\.0\.0/);
+    expect(r.info).toMatch(/tools\s+4/);
+    expect(r.info).toMatch(/resources\s+2\s+\[docs, readme\]/);
+    expect(r.info).toMatch(/prompts\s+\(not supported\)/);
+  });
+
+  it("/mcp falls back to the spec-only list when mcpServers is absent", () => {
+    const r = handleSlash("mcp", [], makeLoop(), {
+      mcpSpecs: ["filesystem=npx -y @scope/fs /tmp"],
+    });
+    expect(r.info).toMatch(/MCP servers \(1\)/);
+    expect(r.info).toMatch(/server-filesystem|fs/);
+  });
+
+  it("/status shows ctx / session / mcp / pending lines with rich detail", () => {
+    const loop = makeLoop();
+    // Make it look like one turn ran so lastPromptTokens > 0.
+    loop.stats.record(1, loop.model, new Usage(42_000, 50, 42_050, 40_000, 2_000));
+    loop.log.append({ role: "user", content: "hi" });
+    loop.log.append({ role: "assistant", content: "there" });
+    const r = handleSlash("status", [], loop, {
+      mcpSpecs: ["filesystem=npx -y @scope/fs /tmp", "mem=npx -y @scope/mem"],
+      pendingEditCount: 3,
+    });
+    expect(r.info).toMatch(/model\s+deepseek-/);
+    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("/status with pendingEditCount=0 hides the edits line", () => {
+    const r = handleSlash("status", [], makeLoop(), { pendingEditCount: 0 });
+    expect(r.info).not.toMatch(/pending/);
+  });
+
+  it("/commit strips surrounding double quotes from the message", () => {
+    // We can't exercise git without a real repo; instead, rely on the
+    // fact that /commit fails (no git repo at /nonexistent) but the
+    // failure output should reveal the stripped message in the
+    // arguments we passed. We mirror this by just confirming usage
+    // ISN'T printed — meaning the parser accepted a non-empty message.
+    const r = handleSlash("commit", ['"fix: tests"'], makeLoop(), { codeRoot: "/nonexistent" });
+    expect(r.info).not.toMatch(/usage: \/commit/);
+    // It WILL say git failed since /nonexistent isn't a git repo, but
+    // we don't assert the exact message — it varies by platform.
+    expect(r.info).toMatch(/git (add|commit) failed/);
+  });
+
  it("/sessions returns a hint when none exist", () => {
    const r = handleSlash("sessions", [], makeLoop());
    expect(r.info).toMatch(/no saved sessions yet|Saved sessions/);
@@ -239,4 +582,54 @@ 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 REASONIX.md exists", () => {
+      const r = handleSlash("memory", [], makeLoop(), { memoryRoot: root });
+      expect(r.info).toMatch(/no REASONIX\.md in/);
+      expect(r.info).toMatch(/pin notes/);
+    });
+
+    it("prints the file 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(/▸ project memory:/);
+      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(/project memory is disabled/);
+    });
+
+    it("refuses to guess a root when memoryRoot is absent", () => {
+      const r = handleSlash("memory", [], makeLoop());
+      expect(r.info).toMatch(/no project root/);
+    });
+  });
 });
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { Usage } from "../src/client.js";
-import { SessionStats, costUsd } from "../src/telemetry.js";
+import { SessionStats, costUsd, inputCostUsd, outputCostUsd } from "../src/telemetry.js";

 describe("Usage.cacheHitRatio", () => {
  it("computes hit ratio", () => {
@@ -51,4 +51,36 @@ describe("SessionStats", () => {
    stats.record(2, "deepseek-chat", new Usage(42_000, 200, 42_200, 40_000, 2_000));
    expect(stats.summary().lastPromptTokens).toBe(42_000);
  });
+
+  it("summary splits input + output costs — the new panel breakdown", () => {
+    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);
+    // Sum of input+output equals total (within rounding).
+    expect(s.totalInputCostUsd + s.totalOutputCostUsd).toBeCloseTo(s.totalCostUsd, 9);
+  });
+});
+
+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);
+  });
+
+  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);
+  });
+
+  it("both return 0 for an unknown model", () => {
+    const u = new Usage(1000, 100, 1100, 800, 200);
+    expect(inputCostUsd("unknown", u)).toBe(0);
+    expect(outputCostUsd("unknown", u)).toBe(0);
+  });
 });
@@ -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;
+    }
+  });
+});