chore(release): 0.30.0 (#349)

Switch the X-axis branch of `moveTo()` from CUF (relative cursor right,
`\x1b[NC`) to CHA (absolute column, `\x1b[N+1G`). Y-axis stays on
CUU/CUD since we don't track absolute terminal rows.

Relative column moves accumulate drift across frames: if any earlier
write miscounted cell width — wide-char disagreement (`▸` U+25B8 in
"narrow" fonts that render 2-cell), `▎` ambiguous-width on terminals
that font-detect East Asian width, OSC8 hyperlinks parsed as visible
chars, etc. — the cursor's actual column desyncs from what the
renderer thinks. The next CUF lands at the wrong column, ghost-rows
get written into hint lines, and the modal "shifts" as users navigate
(symptom in #346 issue screenshots).

Anthropic's Claude Code TUI hit the same class of bug
(anthropics/claude-code#14208) and the fix was the same: prefer CHA
over CUF/CUB so column targeting is immune to per-cell width
miscounts. Fix is invisible on terminals where our width math was
already correct; on terminals where it wasn't, no more accumulating
drift.

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: esengine

.github/workflows/ci.yml

@@ -32,8 +32,12 @@ jobs:
       - name: Typecheck
         run: npm run typecheck
 
-      - name: Test (vitest)
-        run: npm test
+      - name: Test (vitest + coverage)
+        run: npm run test:coverage
+
+      - name: Coverage job summary
+        if: always()
+        run: node scripts/coverage-summary.mjs
 
       - name: Build (tsup)
         run: npm run build

.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  analyze:
+    name: analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript-typescript]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-extended
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 coverage/
+.stryker-tmp/
 .env
 .env.local
 *.log

CHANGELOG.md

@@ -3,6 +3,268 @@
 All notable changes to Reasonix. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.0] — 2026-05-06
+
+**Headline:** slash commands grow first-class aliases, and the
+cell-diff renderer hardens column targeting against per-cell width
+miscounts. `/quit` and `/q` now resolve to `/exit` from a single
+declaration on the spec instead of ad-hoc handler mirrors; `/?` →
+`/help`, `/reset` → `/new`, `/lang` → `/language` follow the same
+path. The renderer's `moveTo()` now uses CHA absolute (`\x1b[N+1G`)
+for column targeting instead of CUF relative (`\x1b[NC`), making the
+diff stream immune to the cursor-drift class of bug Anthropic
+documented in `claude-code#14208`.
+
+**Features:**
+
+- feat(slash): `aliases?: readonly string[]` on `SlashCommandSpec`.
+  Adding a new alias is now a one-line edit to the canonical command
+  — dispatch, autocomplete, arg-context resolution, and the
+  dashboard `/api/slash` response all route through one
+  `resolveSlashAlias()` map built from `SLASH_COMMANDS` at module
+  init. Suggestion rows display aliases dimly (` · /quit /q`) so
+  they stay discoverable without doubling the autocomplete list.
+  Removes the per-handler alias mirrors that used to live in
+  `handlers/basic.ts` and `handlers/language.ts`. (#332, PR #347)
+
+**Bug fixes:**
+
+- fix(renderer): switch the X-axis branch of `moveTo()` from CUF
+  relative (`\x1b[NC`) to CHA absolute (`\x1b[N+1G`). Y-axis stays
+  on CUU/CUD since we don't track absolute terminal rows. Relative
+  column moves accumulate drift across frames whenever an earlier
+  write miscounts cell width — `▸` (U+25B8) rendered 2-cell on
+  fonts with East Asian fallback, ambiguous-width chars on
+  terminals that font-detect width, OSC8 hyperlinks parsed as
+  visible chars, etc. The next CUF lands at the wrong column,
+  ghost rows leak into adjacent hint lines, and the modal "shifts"
+  as users navigate. CHA targets the absolute column regardless of
+  what the terminal thinks — immune to the desync chain. Same fix
+  Anthropic shipped in claude-code per their issue #14208
+  post-mortem. (#346, PR #348)
+
+## [0.29.1] — 2026-05-06
+
+**Headline:** four user-reported bugs from the 0.29.0 release window.
+The markdown renderer no longer turns English abbreviations like
+`e.g.` into broken hyperlinks (which on cmd.exe / non-OSC-8 terminals
+showed up as visible `]8;;file://e.g…` garbage and on the cell-diff
+side desynced the renderer's prev-frame model). The cell-diff
+renderer now defensively trail-clears any row whose content shrank
+between frames. Resumed sessions keep their cumulative session cost
+instead of resetting to `$0`. The Approve plan modal now shows the
+plan body inline when the model didn't supply structured steps.
+Wide markdown tables fall back to row-grouped key/value lines
+instead of the previous column-grouped output.
+
+**Bug fixes:**
+
+- fix(markdown): stop linkifying English abbreviations + drop OSC 8
+  escape emission. The `FILE_REF_RE` extension class was too loose
+  (`{1,6}`), so `e.g`, `i.e`, `a.m` matched as file paths; `osc8()`
+  baked OSC 8 escape bytes into Text content, which the cell-diff
+  renderer's wrapLine stripped of zero-width chars but kept the
+  printable body — producing visible `]8;;file://e.ge.g]8;;` garbage
+  on every terminal. Tightened the regex (now requires path-shape,
+  line-number suffix, or extension >= 2 chars) and removed the OSC 8
+  escape — file refs still stand out via color + underline. (#330,
+  PR #341)
+- fix(renderer): trail-clear rows that shrank between frames in the
+  cell-diff diff. The diff skipped cells where prev and next were
+  byte-equal (including trailing EMPTY cells), so any earlier ANSI
+  desync left stale chars in shrunken rows — manifested as the
+  shell-confirm modal showing `allow always` + `mand, ask again next
+  time` after Up/Down navigation. New `clearToEOL` patch type and a
+  per-row sweep after `diffEach`. (#330, PR #341)
+- fix(stats): carry session cost / turn count across resume. The
+  TUI's `$X session` figure reset to `$0` on every resume even
+  though the disk meta still held the cumulative `totalCostUsd`.
+  `SessionStats` gains `seedCarryover()`; `CacheFirstLoop` reads the
+  meta on resume and seeds the carryover when prior messages exist.
+  (#333, PR #342)
+- fix(plan): show the plan body in the Approve plan modal. When the
+  model called `submit_plan` with a markdown body but no structured
+  `steps`, the modal showed only the choice list — users had no way
+  to see what they were approving without scrolling back. The modal
+  now renders the body via `MarkdownView`, capped at 24 lines with
+  an overflow hint. (#336, PR #343)
+- fix(markdown): row-group the table fallback layout. When a table
+  was too wide for the viewport, the fallback flattened it as N
+  "Component:" lines, then N "What:" lines, then N "Manual TCs:"
+  lines — the reader couldn't tell which value belonged to which
+  row. Swapped to row-first iteration with a blank separator
+  between rows. (#340, PR #344)
+
+## [0.29.0] — 2026-05-06
+
+**Headline:** tool dispatch is no longer strictly serial. When the model
+emits multiple `parallelSafe`-annotated tool calls in one turn (multiple
+`read_file`, multiple `spawn_subagent`, etc.), the loop now races them
+together via `Promise.allSettled`; a non-`parallelSafe` call ends the
+chunk and runs alone, so read-after-write ordering still holds. Tool
+yields and history append still land in declared order regardless of
+which call settles first — the model and UI see the same shape they
+would under serial dispatch. The TUI's `SubagentRow` becomes
+`SubagentLiveStack`, rendering 1 → rich card, 2..max → compact rows,
+> max → "+N more running…" fold. Closes umbrella #325.
+
+**Tool dispatch:**
+
+- feat(tools): `ToolDefinition.parallelSafe?: boolean` — opt-in
+  annotation, default `false`. `ToolRegistry.isParallelSafe(name)` for
+  the dispatcher to query; unknown / unannotated tools resolve to
+  `false` so third-party MCP tools must explicitly opt in. Built-in
+  read-only filesystem (`read_file`, `list_directory`,
+  `directory_tree`, `search_files`, `search_content`,
+  `get_file_info`), web (`web_search`, `web_fetch`), `recall_memory`,
+  `semantic_search`, isolated child loops (`run_skill`,
+  `spawn_subagent`), and in-memory job queries (`job_output`,
+  `list_jobs`) are annotated. Mutating tools stay default. (PR #326)
+- feat(loop): chunked parallel tool dispatch. Replaces `for...of +
+  await` in the dispatch loop with a chunking loop that groups
+  consecutive `parallelSafe` calls and races them; unsafe calls form
+  serial barriers. `runOneToolCall` extracts per-call lifecycle
+  (PreToolUse + dispatch + PostToolUse) so the chunk can fan out via
+  `Promise.allSettled` while the loop body keeps yielding events in
+  declared order. Two new env knobs: `REASONIX_PARALLEL_MAX` (chunk
+  size cap, default 3, hard max 16) and `REASONIX_TOOL_DISPATCH=serial`
+  (escape hatch). Tests cover parallel timing, serial barrier on mixed
+  safe/unsafe, declared-order yields under racey completion, and both
+  env-knob overrides. (PR #327)
+
+**TUI:**
+
+- feat(ui): `SubagentEvent` carries a stable `runId` per spawn so the
+  sink can key concurrent runs apart instead of overwriting one shared
+  row. `useSubagent` keeps an array of in-flight activities;
+  `SubagentLiveStack` renders 1 → rich card (unchanged), 2..max →
+  compact rows with per-row spinner + iter + last tool, > max →
+  compact rows + "+N more running…" fold. (PR #327)
+
+**Docs:**
+
+- docs(architecture): `docs/ARCHITECTURE.md` Pillar 1 gains a
+  "Parallel tool dispatch" section explaining the chunking rule, both
+  env knobs, and the list of built-in tools that opt in. (PR #328)
+
+## [0.28.0] — 2026-05-06
+
+**Headline:** subagent capability sharpened on three axes — skills can
+now scope a child to a specific tool subset via `allowed-tools`
+frontmatter, callers can request a per-spawn iter budget via the new
+`max_iters` arg (clamped 1-32), and two built-in personas (`explore`,
+`verify`) are selectable inline via a `type` arg without writing a
+skill. Closes umbrella #316.
+
+**Subagent:**
+
+- feat(subagent): honor skill `allowed-tools` frontmatter when forking
+  the child registry. The field was parsed but ignored ("Unused in v1");
+  now it scopes the subagent to the named tools only. New
+  `forkRegistryWithAllowList` helper alongside `forkRegistryExcluding`;
+  `NEVER_INHERITED` (`spawn_subagent` / `submit_plan`) still wins so
+  depth=1 + plan-mode guarantees hold even if a skill names them. An
+  allow-list naming a tool the parent doesn't have returns a structured
+  error result (no API call burned). (#317, PR #320)
+- feat(subagent): expose `max_iters` on the `spawn_subagent` tool
+  schema. Clamped to 1-32 at the boundary; floats round down; non-numeric
+  / missing falls back to the registration-time default (still 16).
+  Verify-style tasks can ask for 6-8, explore-style can ask for 24+.
+  (#318, PR #321)
+- feat(subagent): two built-in personas selectable via `type` arg —
+  `explore` (wide-net read-only investigation, 20-iter budget) and
+  `verify` (narrow yes/no with evidence, 8-iter budget). Caller's
+  explicit `system` / `max_iters` override the type's defaults. Prompts
+  live in new `src/tools/subagent-types.ts` so `subagent.ts` stays
+  under the 500-line target. (#319, PR #322)
+
+## [0.27.3] — 2026-05-06
+
+**Headline:** USD-account users now see `$` instead of `¥` everywhere
+money is shown in the TUI — wallet balance, turn cost, session cost,
+top-bar cost label, subagent end-event cost suffix, and the UsageCard
+header / body / wallet line. Pre-fix a USD wallet rendered
+`¥0.0352 turn · ¥0.461 session · wallet ¥0.91`; now it renders
+`$0.0308 turn · $0.064 session · wallet $0.91`. The display follows
+the wallet currency reported by the DeepSeek API (`currency: "USD"|"CNY"`),
+not the UI language — a CNY account on an English UI still sees `¥`,
+and vice versa. Originally reported in #278 by @Explosion-Scratch.
+
+**UI / currency:**
+
+- fix(ui): USD wallets render `$` for wallet balance, turn cost, and
+  session cost. State + event schemas now carry `balanceCurrency`
+  through `App.tsx → reducer → StatusBar` so every render site sees
+  the wallet symbol the API reported. Originally drafted by @wviana
+  in #272; the TUI plumbing through state.ts / cards.ts / events.ts /
+  reducer.ts / useScrollback.ts / slash/types.ts was the bulk of the
+  fix.
+- fix(ui): balance color threshold checks USD against the CNY scale
+  (`$0.91 ≈ ¥6.55`) rather than treating `0.91` as `< ¥5 → red`. USD
+  wallets now correctly show yellow at low-but-not-empty balances.
+- fix(ui): `StatsPanel.ChromeRow` cost label and `useSubagent`
+  end-event cost suffix follow the wallet currency too — pre-fix
+  these always rendered `$`. (#313)
+- refactor(ui): seven currency helpers in `theme/tokens.ts`
+  (`formatCNY` / `formatBalance` / `formatBalanceLabel` /
+  `formatWalletDisplay` / `formatCost` / `balanceColorCny` /
+  `balanceColorForBalance`) collapsed to three: `formatBalance`,
+  `formatCost`, `balanceColor`. Undefined currency defaults to CNY
+  (matches pre-fix unconditional `¥`) so the transient first-turn
+  case where balance arrived but currency hasn't is consistent.
+- chore(ui): remove orphan `ChromeBar.tsx` (258 lines). `App.tsx`
+  mounts `StatsPanel`'s diverged `ChromeRow`, which is the bar users
+  actually see. The two formatter helpers ChromeBar once owned now
+  live in `theme/tokens.ts`. (#314)
+
+**Loop:**
+
+- refactor(loop): `loop.ts` 1331 → 1219 (−112). Three sibling files
+  under `src/loop/`: `messages.ts` (pure ChatMessage builders),
+  `turn-failure-tracker.ts` (per-turn failure count + threshold
+  tipping), `force-summary.ts` (forced-summary generator behind a
+  small DI context). Continues the #308 / #309 cadence — small
+  per-helper extractions, no behavior change. (#311)
+
+**Known follow-up:** `SessionPicker` still hardcodes `¥` for
+per-session cost in the session-history list, tracked in #312
+(good-first-issue).
+
+## [0.25.1] — 2026-05-05
+
+**Headline:** `run_command` learns the four common shell chain
+operators (`|`, `||`, `&&`, `;`) and the seven file redirect
+operators (`>`, `>>`, `<`, `2>`, `2>>`, `2>&1`, `&>`). Parsed and
+spawned natively — no shell is invoked, so semantics are identical
+on Windows / macOS / Linux; PowerShell 5.1's `&&` parse error and
+the object-vs-bytes pipe gap are sidestepped. Each chain segment is
+allowlist-checked independently, so `git status | grep main` now
+auto-runs when both halves are individually allowed. Driven by
+discussion #231.
+
+**Shell:**
+
+- feat(shell): support `|`, `||`, `&&`, `;` chain operators in
+  `run_command` via split-and-spawn. The chain is segmented at
+  whitespace-bounded operators (preserves embedded `&` / `|` inside
+  arg values like `--flag=1&2`), each segment runs through the
+  existing lenient tokenizer, and segments are executed with proper
+  short-circuit semantics for `&&` / `||`. Each segment hits the
+  allowlist independently — `git status | grep main` runs when both
+  halves are allowed individually. (#233, #234)
+- feat(shell): support file redirects in `run_command` — `>` (truncate),
+  `>>` (append), `<` (stdin from file), `2>` (stderr truncate), `2>>`
+  (stderr append), `2>&1` (merge stderr into wherever stdout points),
+  `&>` (both → file). Targets resolve relative to the project root.
+  Mid-pipe `2>&1` correctly merges stderr into the next segment's
+  stdin without truncating on stdout-end. (#235)
+- fix(shell): chain parser stays consistent with the project's
+  long-standing lenient tokenizer — `cargo run -- --flag=1&2` and
+  similar embedded-operator args stay literal instead of getting
+  POSIX-strict-rejected. shell-quote dependency dropped;
+  `splitOnChainOps` is whitespace-bounded like the existing
+  `detectShellOperator`. (#234)
+
 ## [0.24.1] — 2026-05-04
 
 **Headline:** Two TUI fixes on top of the 0.24.0 cell-diff renderer.

README.md

@@ -1,123 +1,169 @@
 <p align="center">
-  <img src="docs/logo.svg" alt="Reasonix — DeepSeek-native agent framework" width="640"/>
+  <img src="docs/logo.svg" alt="Reasonix" width="640"/>
 </p>
 
 <p align="center">
-  <strong>English</strong> · <a href="./README.zh-CN.md">简体中文</a> · <a href="https://esengine.github.io/reasonix/">Website</a>
+  <strong>English</strong>
+  &nbsp;·&nbsp;
+  <a href="./README.zh-CN.md">简体中文</a>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/reasonix/">Website</a>
+  &nbsp;·&nbsp;
+  <a href="./docs/ARCHITECTURE.md">Architecture</a>
+  &nbsp;·&nbsp;
+  <a href="./benchmarks/">Benchmarks</a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg" alt="npm version"/></a>
-  <a href="https://github.com/esengine/reasonix/actions/workflows/ci.yml"><img src="https://github.com/esengine/reasonix/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg" alt="license"/></a>
-  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/dm/reasonix.svg" alt="downloads"/></a>
-  <a href="./package.json"><img src="https://img.shields.io/node/v/reasonix.svg" alt="node"/></a>
-  <a href="https://github.com/esengine/reasonix/stargazers"><img src="https://img.shields.io/github/stars/esengine/reasonix.svg?style=flat&logo=github&label=stars" alt="GitHub stars"/></a>
-  <a href="https://github.com/esengine/reasonix/discussions"><img src="https://img.shields.io/github/discussions/esengine/reasonix.svg?logo=github&label=discussions" alt="Discussions"/></a>
+  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="npm version"/></a>
+  <a href="https://github.com/esengine/reasonix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/reasonix/ci.yml?style=flat-square&label=ci&color=0d1117&labelColor=161b22" alt="CI"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="license"/></a>
+  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/dm/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="downloads"/></a>
+  <a href="./package.json"><img src="https://img.shields.io/node/v/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="node"/></a>
+  <a href="https://github.com/esengine/reasonix/stargazers"><img src="https://img.shields.io/github/stars/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="GitHub stars"/></a>
+  <a href="https://github.com/esengine/reasonix/graphs/contributors"><img src="https://img.shields.io/github/contributors/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="contributors"/></a>
+  <a href="https://github.com/esengine/reasonix/discussions"><img src="https://img.shields.io/github/discussions/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="Discussions"/></a>
 </p>
 
+<br/>
+
+<h3 align="center">A DeepSeek-native AI coding agent for your terminal.</h3>
+<p align="center">Engineered around prefix-cache stability — so token costs stay low across long sessions, and you can leave it running.</p>
+
+<br/>
+
 <p align="center">
-  <strong>A DeepSeek-native AI coding agent for your terminal.</strong> Engineered around DeepSeek's prefix-cache, so the savings are real and the loop stays cheap enough to leave on.
+  <img src="docs/assets/hero-terminal.svg" alt="Reasonix code mode — assistant proposes a SEARCH/REPLACE edit; nothing on disk until /apply" width="860"/>
 </p>
 
-<p align="center">
-  <img src="docs/assets/hero-stats.svg" alt="94% live prefix-cache hit · ~30× cheaper per task vs Claude Code · MIT terminal-native" width="860"/>
-</p>
+<br/>
 
----
+> [!TIP]
+> **Cache stability isn't a feature you turn on; it's an invariant the loop is designed around.** That's the whole reason Reasonix is DeepSeek-only — every layer is tuned to the byte-stable prefix-cache mechanic.
 
-## Quick start
+<br/>
+
+## Install
 
 ```bash
 cd my-project
 npx reasonix code   # paste a DeepSeek API key on first run; persists after
 ```
 
+Requires Node ≥ 22. Tested on macOS · Linux · Windows (PowerShell · Git Bash · Windows Terminal). Get a [DeepSeek API key →](https://platform.deepseek.com/api_keys) · `reasonix code --help` for flags.
+
+<br/>
+
+## What makes Reasonix different
+
+The loop is organized around four pillars. Each one solves a problem generic agent frameworks don't even see — because they were designed for a different cache mechanic.
+
 <p align="center">
-  <img src="docs/assets/hero-terminal.svg" alt="Reasonix code mode — assistant proposes a SEARCH/REPLACE edit; nothing on disk until /apply" width="860"/>
+  <a href="./docs/ARCHITECTURE.md"><img src="docs/assets/pillars.svg" alt="Reasonix four pillars — Cache-first loop, R1 thought harvesting, Tool-call repair, Cost control" width="880"/></a>
 </p>
 
-Requires Node ≥ 22. Tested on macOS, Linux, and Windows (PowerShell, Git Bash, Windows Terminal). Get a [DeepSeek API key →](https://platform.deepseek.com/api_keys) · `reasonix code --help` for flags.
+<sub align="center">
 
----
+Click any card to read the full architecture writeup → [Pillar 1](./docs/ARCHITECTURE.md#pillar-1--cache-first-loop) · [Pillar 2](./docs/ARCHITECTURE.md#pillar-2--r1-thought-harvesting-opt-in) · [Pillar 3](./docs/ARCHITECTURE.md#pillar-3--tool-call-repair) · [Pillar 4](./docs/ARCHITECTURE.md#pillar-4--cost-control-v06)
+
+</sub>
+
+<br/>
+
+## Capabilities
+
+<p align="center">
+  <img src="docs/assets/feature-grid.svg" alt="Reasonix capabilities — cell-diff renderer, MCP, plan mode, permissions, dashboard, persistent sessions, hooks/skills/memory, semantic search, auto-checkpoints, /effort knob, transcript replay, event log" width="880"/>
+</p>
+
+<br/>
 
 ## How it compares
 
-|                                   | Reasonix         | Claude Code     | Cursor             | Aider            |
-|-----------------------------------|------------------|-----------------|--------------------|------------------|
-| Backend                           | DeepSeek V4      | Anthropic       | OpenAI / Anthropic | any (OpenRouter) |
-| **Cost / typical task**           | **~¥0.01–0.04**  | ~¥0.40–4        | ¥150/mo + usage    | varies           |
-| License                           | **MIT**          | closed          | closed             | Apache 2         |
-| **DeepSeek prefix-cache hit**     | **94%** (live)   | n/a             | n/a                | ~33% (baseline)  |
-| Embedded web dashboard            | yes              | —               | n/a (IDE)          | —                |
-| Persistent per-workspace sessions | yes              | partial         | n/a                | —                |
+|                                   | Reasonix         | Claude Code       | Cursor              | Aider              |
+|-----------------------------------|------------------|-------------------|---------------------|--------------------|
+| Backend                           | DeepSeek         | Anthropic         | OpenAI / Anthropic  | any (OpenRouter)   |
+| License                           | **MIT**          | closed            | closed              | Apache 2           |
+| Cost profile                      | **low per task** | premium           | subscription + use  | varies             |
+| DeepSeek prefix-cache             | **engineered**   | not applicable    | not applicable      | incidental         |
+| Embedded web dashboard            | yes              | —                 | n/a (IDE)           | —                  |
+| Persistent per-workspace sessions | yes              | partial           | n/a                 | —                  |
+| Plan mode · MCP · hooks · skills  | yes              | yes               | yes                 | partial            |
+| Open community development        | yes              | —                 | —                   | yes                |
 
-Plan mode, edit review, MCP, skills, hooks, and sandboxing are all `yes` for Reasonix and most peers — see the feature grid below for what they actually do here.
+For live cache-hit rates, costs, and methodology, see [`benchmarks/`](./benchmarks/) — the numbers move with model pricing, so they live with the harness, not in the README.
 
-Numbers from `benchmarks/tau-bench-lite` (8 multi-turn tasks × 3 repeats, live `deepseek-chat`). [Committed transcripts →](./benchmarks/)
+<br/>
 
-<details>
-<summary><strong>Why DeepSeek-only? — the cache economics</strong></summary>
+## Documentation
 
-Cheap tokens alone is half the story. DeepSeek's prefix-cache is **byte-stable**: the cache fingerprints from byte 0 of the prompt. Reasonix's loop is engineered around that — append-only growth, no re-ordering, no marker-based compaction — so the cache prefix survives every tool call.
+- [**Architecture**](./docs/ARCHITECTURE.md) — the four pillars, cache-first loop, harvesting, scaffolds
+- [**Benchmarks**](./benchmarks/) — τ-bench-lite harness, transcripts, cost methodology
+- [**Website**](https://esengine.github.io/reasonix/) — getting started, dashboard mockup, TUI mockup
+- [**Contributing**](./CONTRIBUTING.md) — comment policy, error-handling rules, library-over-hand-rolled
+- [**Code of Conduct**](./CODE_OF_CONDUCT.md) · [**Security policy**](./SECURITY.md)
 
-By comparison, Claude Code is built around Anthropic's `cache_control` markers (a fundamentally different mechanic). Pointing it at DeepSeek's Anthropic-compat endpoint keeps the cheap tokens but loses the cache hits — markers are ignored, and the underlying prefix isn't byte-stable. Generic-backend tools (Aider / Cline / Continue) hit the same wall from the other direction: their compaction patterns destroy byte stability.
+<br/>
 
-At DeepSeek's pricing — $0.07/Mtok uncached, $0.014/Mtok cached — **the difference between 50% and 94% hit is roughly 2.5× on input cost alone.** Same model, same API; the loop's invariants are what changed.
+## Community
 
-A few DeepSeek-specific fixes generic loops miss:
+> [!NOTE]
+> Reasonix is open source and community-developed. The contributors wall below isn't decoration — every avatar is a real PR that shipped.
 
-| Generic loops assume | DeepSeek actually does | Reasonix's fix |
-|---|---|---|
-| Reasoning emitted as a structured `thinking` block | R1 sometimes leaks tool-call JSON inside `<think>` tags | a `scavenge` pass that pulls escaped tool calls back out |
-| Tool schemas validated strictly | DeepSeek silently drops deeply-nested object/array params | auto-flatten — nested params get rewritten to single-level prefixed names |
-| Tool-call args are well-formed JSON | DeepSeek occasionally produces `string="false"` and other malformed fragments | dedicated `ToolCallRepair` heals the common shapes before dispatch |
-| Reasoning depth tuned via system-level switches | V4 exposes a `reasoning_effort` knob (`max` / `high`) | `/effort` slash + `--effort` flag for cheap turns |
+Scoped starter tickets — each with background, code pointers, acceptance criteria, and hints — live under the [`good first issue`](https://github.com/esengine/reasonix/labels/good%20first%20issue) label. Pick anything open.
 
-Cache stability isn't a feature you turn on; it's an invariant the loop is designed around. That's the entire reason Reasonix is DeepSeek-only.
+**Open Discussions — opinions wanted:**
 
-</details>
-
----
-
-## What's in the box
-
-<p align="center">
-  <img src="docs/assets/feature-grid.svg" alt="Feature grid — cache-first loop, plan mode, MCP first-class, sessions and dashboard, hooks, memory and skills" width="860"/>
-</p>
-
-Permissions (`allow` / `ask` / `deny`), tool-call repair (flatten · scavenge · truncation · storm), and `/effort` for cheap turns round out the loop. [Architecture →](./docs/ARCHITECTURE.md) · [Dashboard mockup →](https://esengine.github.io/reasonix/design/agent-dashboard.html) · [TUI mockup →](https://esengine.github.io/reasonix/design/agent-tui-terminal.html) · [Website →](https://esengine.github.io/reasonix/)
-
----
-
-## Contributing
-
-Reasonix is solo-maintained but designed to grow. Scoped starter tickets — each with background, code pointers, acceptance criteria, and hints — live under the [`good first issue`](https://github.com/esengine/reasonix/labels/good%20first%20issue) label. Pick anything open.
-
-**Open Discussions** — opinions wanted:
 - [#20 · CLI / TUI design](https://github.com/esengine/reasonix/discussions/20) — what's broken, what's missing, what would you change?
 - [#21 · Dashboard design](https://github.com/esengine/reasonix/discussions/21) — react against the [proposed mockup](https://esengine.github.io/reasonix/design/agent-dashboard.html)
 - [#22 · Future feature wishlist](https://github.com/esengine/reasonix/discussions/22) — what would you build into Reasonix next?
 
-**Before your first PR**: read [`CONTRIBUTING.md`](./CONTRIBUTING.md) — short, strict project rules (comments, errors, libraries-over-hand-rolled). `tests/comment-policy.test.ts` enforces the comment ones; `npm run verify` is the pre-push gate. By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues → [SECURITY.md](./SECURITY.md).
+**Already using Reasonix and willing to help others discover it?** Publish blog posts, articles, screenshots, talks, or videos to [**Show and tell**](https://github.com/esengine/reasonix/discussions/categories/show-and-tell). The project has no marketing budget — community word of mouth is how new users find it. Sustained advocates earn the badge below, displayed next to the contributors wall once awarded:
 
-### Contributors
+<p align="center">
+  <a href="https://github.com/esengine/reasonix/discussions/categories/show-and-tell">
+    <img src="https://img.shields.io/badge/REASONIX-📣%20ADVOCATE-c4b5fd?style=for-the-badge&labelColor=0d1117" alt="Reasonix Advocate badge — earned by sustained advocates"/>
+  </a>
+</p>
 
-<a href="https://github.com/esengine/reasonix/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=esengine/reasonix" alt="Contributors to esengine/reasonix"/>
-</a>
+**Before your first PR**: read [`CONTRIBUTING.md`](./CONTRIBUTING.md) — short, strict rules (comments, errors, libraries-over-hand-rolled). `tests/comment-policy.test.ts` enforces the comment ones; `npm run verify` is the pre-push gate. By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues → [SECURITY.md](./SECURITY.md).
 
----
+<p align="center">
+  <a href="https://github.com/esengine/reasonix/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=esengine/reasonix&max=100&columns=12" alt="Contributors to esengine/reasonix" width="860"/>
+  </a>
+</p>
+
+<br/>
 
 ## Non-goals
 
-- **Multi-provider flexibility.** DeepSeek-only on purpose — every layer is tuned around DeepSeek's specific cache mechanic and pricing. Coupling to one backend is the feature.
-- **IDE integration.** Terminal-first; the diff lives in `git diff`, the file tree in `ls`. The dashboard is a companion, not a Cursor replacement.
-- **Hardest-leaderboard reasoning.** Claude Opus still wins some benchmarks. DeepSeek V4 is competitive on coding; if your work is "solve this PhD proof" rather than "fix this auth bug," start with Claude.
+> [!IMPORTANT]
+> Reasonix is opinionated. Some things it deliberately *doesn't* do — listed here so you can pick the right tool for your work.
+
+- **Multi-provider flexibility.** DeepSeek-only on purpose. Coupling to one backend is the feature, not a limitation.
+- **IDE integration.** Terminal-first. The diff lives in `git diff`, the file tree in `ls`. The dashboard is a companion, not a Cursor replacement.
+- **Hardest-leaderboard reasoning.** Claude Opus still wins some benchmarks. DeepSeek is competitive on coding; if your work is "solve this PhD proof" rather than "fix this auth bug," start with Claude.
 - **Air-gapped / fully-free.** Reasonix needs a paid DeepSeek API key. For air-gapped or zero-cost runs see Aider + Ollama or [Continue](https://continue.dev).
 
+<br/>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=esengine%2Freasonix&type=timeline&logscale=&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&logscale&legend=top-left" />
+ </picture>
+</a>
+
+<br/>
+
 ---
 
-## License
-
-MIT — see [LICENSE](./LICENSE).
+<p align="center">
+  <sub>MIT — see <a href="./LICENSE">LICENSE</a></sub>
+  <br/>
+  <sub>Built by the community at <a href="https://github.com/esengine/reasonix/graphs/contributors">esengine/reasonix</a></sub>
+</p>

README.zh-CN.md

@@ -1,123 +1,169 @@
 <p align="center">
-  <img src="docs/logo.svg" alt="Reasonix — DeepSeek 原生的 agent 框架" width="640"/>
+  <img src="docs/logo.svg" alt="Reasonix" width="640"/>
 </p>
 
 <p align="center">
-  <a href="./README.md">English</a> · <strong>简体中文</strong> · <a href="https://esengine.github.io/reasonix/">官方网站</a>
+  <a href="./README.md">English</a>
+  &nbsp;·&nbsp;
+  <strong>简体中文</strong>
+  &nbsp;·&nbsp;
+  <a href="https://esengine.github.io/reasonix/">官方网站</a>
+  &nbsp;·&nbsp;
+  <a href="./docs/ARCHITECTURE.md">架构文档</a>
+  &nbsp;·&nbsp;
+  <a href="./benchmarks/">基准测试</a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg" alt="npm version"/></a>
-  <a href="https://github.com/esengine/reasonix/actions/workflows/ci.yml"><img src="https://github.com/esengine/reasonix/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg" alt="license"/></a>
-  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/dm/reasonix.svg" alt="downloads"/></a>
-  <a href="./package.json"><img src="https://img.shields.io/node/v/reasonix.svg" alt="node"/></a>
-  <a href="https://github.com/esengine/reasonix/stargazers"><img src="https://img.shields.io/github/stars/esengine/reasonix.svg?style=flat&logo=github&label=stars" alt="GitHub stars"/></a>
-  <a href="https://github.com/esengine/reasonix/discussions"><img src="https://img.shields.io/github/discussions/esengine/reasonix.svg?logo=github&label=discussions" alt="Discussions"/></a>
+  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/v/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="npm version"/></a>
+  <a href="https://github.com/esengine/reasonix/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esengine/reasonix/ci.yml?style=flat-square&label=ci&color=0d1117&labelColor=161b22" alt="CI"/></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="license"/></a>
+  <a href="https://www.npmjs.com/package/reasonix"><img src="https://img.shields.io/npm/dm/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="downloads"/></a>
+  <a href="./package.json"><img src="https://img.shields.io/node/v/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22" alt="node"/></a>
+  <a href="https://github.com/esengine/reasonix/stargazers"><img src="https://img.shields.io/github/stars/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="GitHub stars"/></a>
+  <a href="https://github.com/esengine/reasonix/graphs/contributors"><img src="https://img.shields.io/github/contributors/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="contributors"/></a>
+  <a href="https://github.com/esengine/reasonix/discussions"><img src="https://img.shields.io/github/discussions/esengine/reasonix.svg?style=flat-square&color=0d1117&labelColor=161b22&logo=github" alt="Discussions"/></a>
 </p>
 
+<br/>
+
+<h3 align="center">DeepSeek 原生的终端 AI 编程代理。</h3>
+<p align="center">围绕前缀缓存稳定性设计 —— 长会话下 token 成本始终低位运行，可以一直开着。</p>
+
+<br/>
+
 <p align="center">
-  <strong>DeepSeek 原生的终端 AI 编程代理。</strong> 围绕 DeepSeek 的前缀缓存机制打造——省钱是真省，loop 便宜到可以一直开着。
+  <img src="docs/assets/hero-terminal.zh-CN.svg" alt="Reasonix code 模式预览 — 助手提出 SEARCH/REPLACE 编辑，未 /apply 不落盘" width="860"/>
 </p>
 
-<p align="center">
-  <img src="docs/assets/hero-stats.zh-CN.svg" alt="94% 实测前缀缓存命中 · 单任务比 Claude Code 便宜 ~30 倍 · MIT 终端原生" width="860"/>
-</p>
+<br/>
 
----
+> [!TIP]
+> **缓存稳定不是开关，而是循环要围绕设计的不变量。** 这就是 Reasonix 只支持 DeepSeek 的根本原因 —— 每一层都为 DeepSeek 字节稳定的前缀缓存机制调过。
 
-## 快速上手
+<br/>
+
+## 安装
 
 ```bash
 cd my-project
 npx reasonix code   # 首次运行粘贴 DeepSeek API Key，之后会记住
 ```
 
+要求 Node ≥ 22。已在 macOS · Linux · Windows（PowerShell · Git Bash · Windows Terminal）测过。[去拿 DeepSeek API Key →](https://platform.deepseek.com/api_keys) · 完整 flag 看 `reasonix code --help`。
+
+<br/>
+
+## Reasonix 的不同之处
+
+整个循环围绕四根支柱组织。每一根解决的都是通用 agent 框架根本看不见的问题 —— 因为它们是为另一种缓存机制设计的。
+
 <p align="center">
-  <img src="docs/assets/hero-terminal.zh-CN.svg" alt="Reasonix code 模式预览 — 助手提出 SEARCH/REPLACE 编辑，未 /apply 不落盘" width="860"/>
+  <a href="./docs/ARCHITECTURE.md"><img src="docs/assets/pillars.zh-CN.svg" alt="Reasonix 四大支柱 — 缓存优先循环、R1 思维提取、工具调用修复、成本控制" width="880"/></a>
 </p>
 
-要求 Node ≥ 22。已在 macOS、Linux、Windows（PowerShell · Git Bash · Windows Terminal）测过。[去拿 DeepSeek API Key →](https://platform.deepseek.com/api_keys) · 完整 flag 看 `reasonix code --help`。
+<sub align="center">
 
----
+各支柱完整说明 → [Pillar 1](./docs/ARCHITECTURE.md#pillar-1--cache-first-loop) · [Pillar 2](./docs/ARCHITECTURE.md#pillar-2--r1-thought-harvesting-opt-in) · [Pillar 3](./docs/ARCHITECTURE.md#pillar-3--tool-call-repair) · [Pillar 4](./docs/ARCHITECTURE.md#pillar-4--cost-control-v06)
+
+</sub>
+
+<br/>
+
+## 能力一览
+
+<p align="center">
+  <img src="docs/assets/feature-grid.zh-CN.svg" alt="Reasonix 能力一览 — cell-diff 渲染器、MCP、计划模式、权限、仪表盘、持久化会话、Hooks/Skills/Memory、语义检索、自动 checkpoint、/effort 旋钮、transcript 重放、事件日志" width="880"/>
+</p>
+
+<br/>
 
 ## 横向对比
 
-|                            | Reasonix          | Claude Code     | Cursor             | Aider             |
-|----------------------------|-------------------|-----------------|--------------------|-------------------|
-| 后端                       | DeepSeek V4       | Anthropic       | OpenAI / Anthropic | 任意（OpenRouter）|
-| **单任务成本**             | **~¥0.01–0.04**   | ~¥0.40–4        | ¥150/月 + 用量     | 不一              |
-| 协议                       | **MIT**           | 闭源            | 闭源               | Apache 2          |
-| **DeepSeek 前缀缓存命中**  | **94%**（实测）   | 不适用          | 不适用             | ~33%（基线）      |
-| 内嵌 web 仪表盘            | 支持              | —               | 不适用 (IDE)       | —                 |
-| 持久化的工作区会话         | 支持              | 部分            | 不适用             | —                 |
+|                            | Reasonix          | Claude Code       | Cursor              | Aider              |
+|----------------------------|-------------------|-------------------|---------------------|--------------------|
+| 后端                       | DeepSeek          | Anthropic         | OpenAI / Anthropic  | 任意（OpenRouter） |
+| 协议                       | **MIT**           | 闭源              | 闭源                | Apache 2           |
+| 单任务成本                 | **低**            | 高                | 订阅 + 用量         | 不一               |
+| DeepSeek 前缀缓存          | **专门工程化**    | 不适用            | 不适用              | 偶发命中           |
+| 内嵌 web 仪表盘            | 支持              | —                 | 不适用 (IDE)        | —                  |
+| 持久化的工作区会话         | 支持              | 部分              | 不适用              | —                  |
+| 计划模式 · MCP · Hooks     | 支持              | 支持              | 支持                | 部分               |
+| 开放社区共建               | 支持              | —                 | —                   | 支持               |
 
-计划模式、编辑审查、MCP、skill、Hooks、沙箱在 Reasonix 和大多数同类里都是"支持"——具体怎么做的看下面的功能一览。
+实测缓存命中率、成本、方法论看 [`benchmarks/`](./benchmarks/) —— 这些数会随模型定价变化，所以归在 harness 里，不进 README。
 
-数据来自 `benchmarks/tau-bench-lite`（8 个多轮任务 × 3 次重放，真实 `deepseek-chat`）。[完整 transcript →](./benchmarks/)
+<br/>
 
-<details>
-<summary><strong>为什么只支持 DeepSeek？— 缓存经济学</strong></summary>
+## 文档
 
-便宜的 token 只是故事的一半。DeepSeek 的前缀缓存是**字节稳定**的：缓存指纹从 prompt 第 0 字节开始算。Reasonix 整个循环都围绕这一点设计——只追加、不重排、不做基于标记的 compaction，所以缓存前缀能跨过每一次工具调用存活下来。
+- [**架构**](./docs/ARCHITECTURE.md) —— 四大支柱、缓存优先循环、思维提取、脚手架
+- [**基准测试**](./benchmarks/) —— τ-bench-lite harness、transcript、成本方法论
+- [**官方网站**](https://esengine.github.io/reasonix/) —— 入门、Dashboard 设计稿、TUI 设计稿
+- [**贡献指南**](./CONTRIBUTING.md) —— 注释规则、错误处理、用现成库不手写
+- [**行为准则**](./CODE_OF_CONDUCT.md) · [**安全策略**](./SECURITY.md)
 
-对比一下：Claude Code 是围绕 Anthropic 的 `cache_control` 标记构建的（完全不同的机制）。把 Claude Code 指向 DeepSeek 的 Anthropic 兼容端点，能拿到便宜的 token，但缓存命中没了——标记被忽略，底下的前缀本来就不字节稳定。通用后端工具（Aider / Cline / Continue）从另一个方向撞上同一堵墙：它们的 compaction 模式会破坏字节稳定。
+<br/>
 
-按 DeepSeek 的定价 —— $0.07/Mtok 未命中、$0.014/Mtok 命中 —— **50% 命中和 94% 命中之间的差距，光是输入成本就大约 2.5 倍。** 同模型、同 API；变的只是循环本身的不变量。
+## 社区
 
-通用循环漏掉的几个 DeepSeek 专属修复：
+> [!NOTE]
+> Reasonix 是开源、社区共建的项目。下面贡献者墙不是装饰 —— 每一个头像都对应一次真实合并的 PR。
 
-| 通用循环假设的 | DeepSeek 实际表现 | Reasonix 的处理 |
-|---|---|---|
-| reasoning 在结构化的 `thinking` 块里 | R1 偶尔把 tool-call JSON 漏在 `<think>` 标签里 | 一个 `scavenge` pass 把逃逸的 tool call 拉回来 |
-| 工具 schema 严格校验 | DeepSeek 会静默丢掉深层嵌套的 object/array 参数 | 自动 flatten——嵌套参数被改写成单层带前缀的名字 |
-| tool-call 参数是合法 JSON | DeepSeek 偶尔吐 `string="false"` 之类的破碎片段 | 专门的 `ToolCallRepair` 在 dispatch 前把常见形状修好 |
-| reasoning 深度靠系统级开关调 | V4 暴露了 `reasoning_effort` 旋钮（`max` / `high`） | `/effort` 斜杠 + `--effort` flag，便宜回合可以降档 |
-
-缓存稳定不是个开关，是循环要围绕设计的不变量。这就是 Reasonix 只支持 DeepSeek 的根本原因。
-
-</details>
-
----
-
-## 功能一览
-
-<p align="center">
-  <img src="docs/assets/feature-grid.zh-CN.svg" alt="功能一览 — 缓存优先循环、计划模式、MCP 一等公民、会话与仪表盘、Hooks、Memory 与 Skills" width="860"/>
-</p>
-
-权限系统（`allow` / `ask` / `deny`）、tool-call repair（flatten · scavenge · truncation · storm）、`/effort` 给便宜回合降档——一起把整个 loop 兜起来。[架构文档 →](./docs/ARCHITECTURE.md) · [Dashboard 设计稿 →](https://esengine.github.io/reasonix/design/agent-dashboard.html) · [TUI 设计稿 →](https://esengine.github.io/reasonix/design/agent-tui-terminal.html) · [官网 →](https://esengine.github.io/reasonix/)
-
----
-
-## 参与贡献
-
-Reasonix 现在主要是单人维护，但是为协作设计的。给新手准备的入门 issue —— 每个都带背景说明、代码定位、验收标准、提示 —— 全部挂在 [`good first issue`](https://github.com/esengine/reasonix/labels/good%20first%20issue) 标签下。挑任意一个还没人认领的就行。
+给新手准备的入门 issue —— 每个都带背景说明、代码定位、验收标准、提示 —— 全部挂在 [`good first issue`](https://github.com/esengine/reasonix/labels/good%20first%20issue) 标签下。挑任意一个还没人认领的就行。
 
 **正在征集意见的 Discussions：**
-- [#20 · CLI / TUI 设计](https://github.com/esengine/reasonix/discussions/20) — 哪里坏了、哪里少东西、哪里你会怎么改？
-- [#21 · Dashboard 设计](https://github.com/esengine/reasonix/discussions/21) — 对着[设计稿](https://esengine.github.io/reasonix/design/agent-dashboard.html)拍砖
-- [#22 · 未来功能愿望单](https://github.com/esengine/reasonix/discussions/22) — 你希望 Reasonix 长出什么功能？
+
+- [#20 · CLI / TUI 设计](https://github.com/esengine/reasonix/discussions/20) —— 哪里坏了、哪里少东西、哪里你会怎么改？
+- [#21 · Dashboard 设计](https://github.com/esengine/reasonix/discussions/21) —— 对着[设计稿](https://esengine.github.io/reasonix/design/agent-dashboard.html)拍砖
+- [#22 · 未来功能愿望单](https://github.com/esengine/reasonix/discussions/22) —— 你希望 Reasonix 长出什么功能？
+
+**正在使用 Reasonix，愿意让更多人了解它？** 欢迎将相关博客、文章、截图、演讲或视频发布到 [**Show and tell**](https://github.com/esengine/reasonix/discussions/categories/show-and-tell)。项目没有营销预算，新用户主要通过社区口碑找到这里。持续参与传播的用户将获得下方这枚徽章，颁发后会展示在贡献者墙旁：
+
+<p align="center">
+  <a href="https://github.com/esengine/reasonix/discussions/categories/show-and-tell">
+    <img src="https://img.shields.io/badge/REASONIX-📣%20ADVOCATE-c4b5fd?style=for-the-badge&labelColor=0d1117" alt="Reasonix Advocate 徽章 —— 授予持续参与传播的用户"/>
+  </a>
+</p>
 
 **第一次提 PR 之前**：先读 [`CONTRIBUTING.md`](./CONTRIBUTING.md) —— 短小、严格的项目规则（注释、错误处理、用现成库不手写）。`tests/comment-policy.test.ts` 静态强制执行注释那部分，`npm run verify` 是 push 前的闸。参与本项目即同意 [行为准则](./CODE_OF_CONDUCT.md)。安全相关问题请走 [SECURITY.md](./SECURITY.md)。
 
-### 贡献者
+<p align="center">
+  <a href="https://github.com/esengine/reasonix/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=esengine/reasonix&max=100&columns=12" alt="esengine/reasonix 贡献者" width="860"/>
+  </a>
+</p>
 
-<a href="https://github.com/esengine/reasonix/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=esengine/reasonix" alt="esengine/reasonix 贡献者"/>
-</a>
-
----
+<br/>
 
 ## 不做的事
 
-- **多供应商灵活性。** 故意只做 DeepSeek —— 每一层都为 DeepSeek 特定的缓存机制和定价调过。绑死一个后端是 feature，不是要克服的限制。
-- **IDE 集成。** 终端优先；diff 在 `git diff`，文件树在 `ls`。仪表盘是 TUI 的伴生，不是 Cursor 的替代。
-- **追最难的 reasoning 榜单。** Claude Opus 在某些榜单上还是赢家。DeepSeek V4 在编程任务上有竞争力；如果你的工作是"解一个 PhD 级证明"而不是"修个 auth bug"，先用 Claude。
+> [!IMPORTANT]
+> Reasonix 是有立场的。有些事它故意 *不做* —— 列在这里方便你为自己的工作挑对工具。
+
+- **多供应商灵活性。** 故意只做 DeepSeek。绑死一个后端是 feature，不是限制。
+- **IDE 集成。** 终端优先。diff 在 `git diff`，文件树在 `ls`。仪表盘是 TUI 的伴生，不是 Cursor 的替代。
+- **追最难的 reasoning 榜单。** Claude Opus 在某些榜单上还是赢家。DeepSeek 在编程任务上有竞争力；如果你的工作是"解一个 PhD 级证明"而不是"修个 auth bug"，先用 Claude。
 - **完全离线 / 永远免费。** Reasonix 需要付费的 DeepSeek API Key。要离线 / 零成本，看 Aider + Ollama 或 [Continue](https://continue.dev)。
 
+<br/>
+
+## Star 趋势
+
+<a href="https://www.star-history.com/?repos=esengine%2Freasonix&type=timeline&logscale=&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=esengine/reasonix&type=timeline&logscale&legend=top-left" />
+ </picture>
+</a>
+
+<br/>
+
 ---
 
-## 协议
-
-MIT —— 见 [LICENSE](./LICENSE)。
+<p align="center">
+  <sub>MIT —— 见 <a href="./LICENSE">LICENSE</a></sub>
+  <br/>
+  <sub>由 <a href="https://github.com/esengine/reasonix/graphs/contributors">esengine/reasonix</a> 社区共建</sub>
+</p>

benchmarks/spike-tdd-kernel/tdd-eval.mjs

@@ -45,7 +45,7 @@ const PROMPTS = [
   { id: "m3", level: "medium", task: "A function \`debounceAsync<T extends any[], R>(fn: (...args: T) => Promise<R>, ms: number): (...args: T) => Promise<R>\` in src/util/debounce.ts. Resolves only the latest call's promise; earlier callers reject with an AbortError-like." },
 
   // hard (2) — these touch domain types from the repo
-  { id: "h1", level: "hard", task: "A function \`extractTestId(file: string, fullName: string, source: string): { id: string, source: 'native' | 'annotation' }\` in src/repair/test-id.ts. If \`source\` contains a '// @reasonix-test-id: <slug>' comment within 3 lines above an it()/test() whose name matches \`fullName\`, return that slug with source='annotation'. Otherwise return \`\${file}::\${fullName}\` with source='native'." },
+  { id: "h1", level: "hard", task: "A function \`extractTestId(file: string, fullName: string, source: string): { id: string, source: 'native' | 'annotation' }\` in src/repair/test-id.ts. If \`source\` contains a '// @reasonix-test-id: <slug>' comment within 3 lines above an it()/test() whose name matches \`fullName\`, return that slug with source='annotation'. Otherwise return \`${file}::${fullName}\` with source='native'." },
   { id: "h2", level: "hard", task: "A function \`pairRedGreen(events: Array<{type:string, test_id?:string, status?:string, ts:number}>): Array<{ test_id: string, red_ts: number, green_ts: number }>\` in src/events/pair.ts. For each test_id, find the most recent fail→pass transition and return one entry per test_id. Ignore test_ids that never went green." },
 ];
 

dashboard/app.css

@@ -690,8 +690,19 @@ main { padding: 32px 40px 60px 32px; min-width: 0; }
 .crumbs .sep { color: var(--fg-4); }
 
 /* ── Sessions panel ──────────────────────────────────────────────────── */
-.sessions-grid { display: grid; grid-template-columns: 320px minmax(0, 1fr); gap: 14px; min-height: 540px; }
-.sessions-list { background: var(--bg-elev); border: 1px solid var(--bd); border-radius: var(--r); display: flex; flex-direction: column; overflow: hidden; }
+.sessions-grid {
+  display: grid;
+  grid-template-columns: 320px minmax(0, 1fr);
+  /* `minmax(0, 1fr)` on the row + `min-height: 0` on the children is the
+     standard recipe for "let the inner overflow:auto take effect" — without
+     it the grid items default to min-height: auto (= content size) and
+     grow past the parent's max-height, dragging .app-body along. */
+  grid-template-rows: minmax(0, 1fr);
+  gap: 14px;
+  min-height: 540px;
+  max-height: calc(100vh - 140px);
+}
+.sessions-list { background: var(--bg-elev); border: 1px solid var(--bd); border-radius: var(--r); display: flex; flex-direction: column; overflow: hidden; min-height: 0; min-width: 0; }
 .sessions-list .ssl-h { padding: 10px 12px; border-bottom: 1px solid var(--bd); display: flex; align-items: center; gap: 8px; }
 .sessions-list .ssl-h input {
   flex: 1; background: var(--bg-input); border: 1px solid var(--bd); border-radius: var(--r);
@@ -710,7 +721,7 @@ main { padding: 32px 40px 60px 32px; min-width: 0; }
 .ssl-row .meta { display: flex; gap: 10px; font-family: var(--font-mono); font-size: 10.5px; color: var(--fg-4); margin-top: 2px; }
 .ssl-row .meta .v { color: var(--fg-2); }
 
-.sessions-detail { background: var(--bg-elev); border: 1px solid var(--bd); border-radius: var(--r); padding: 14px 16px; overflow: auto; }
+.sessions-detail { background: var(--bg-elev); border: 1px solid var(--bd); border-radius: var(--r); padding: 14px 16px; overflow: auto; min-height: 0; min-width: 0; }
 .sessions-detail-h { display: flex; align-items: baseline; gap: 12px; margin-bottom: 12px; padding-bottom: 12px; border-bottom: 1px solid var(--bd); }
 .sessions-detail-h .name { font-family: var(--font-mono); font-size: 14px; color: var(--fg-0); font-weight: 600; }
 .sessions-detail-h .ws   { font-family: var(--font-mono); font-size: 11px; color: var(--fg-3); }
@@ -801,6 +812,9 @@ main { padding: 32px 40px 60px 32px; min-width: 0; }
 }
 .chip-f:hover { background: var(--bg-hover); color: var(--fg-1); }
 .chip-f.active { color: var(--c-brand); border-color: var(--c-brand); background: rgba(121,192,255,.08); }
+.chip-f.static { cursor: default; }
+.chip-f.static:hover { background: var(--bg-elev); color: var(--fg-2); }
+.chip-f.static.active:hover { color: var(--c-brand); background: rgba(121,192,255,.08); }
 .chip-f .ct { color: var(--fg-4); font-size: 10px; }
 .chip-f.active .ct { color: var(--c-brand); }
 .chip-f .x { color: var(--fg-4); padding: 0 2px; }

dashboard/src/i18n/en.ts

@@ -264,6 +264,32 @@ export const en = {
     colName: "name",
     colDesc: "description",
     colUri: "uri",
+    marketplace: "marketplace",
+    marketplaceSearch: "search the registry…",
+    marketplaceLoading: "loading registry…",
+    marketplaceMore: "load 5 more pages",
+    marketplaceMoreLabel: "load 50 more  ·  showing {shown} / {total}",
+    marketplaceMoreHint: "fetches more pages from the registry",
+    marketplaceMoreCachedHint: "more entries already cached locally",
+    marketplaceExhausted: "all pages loaded",
+    marketplaceExhaustedFull: "showing all {total} entries — registry exhausted",
+    marketplaceCount: "{loaded} loaded · {matched} match · source: {source}{cached}",
+    marketplaceCachedSuffix: " · cached",
+    marketplaceNoMatches: "No matches. Try different terms or load more pages.",
+    marketplaceInstall: "Install",
+    marketplacePickHint: "Pick a server on the left, then Install.",
+    marketplaceInstalled: "installed → {spec}",
+    marketplaceInstalledBridged: "installed + bridged → {spec}",
+    marketplaceAlready: "already installed",
+    marketplaceNeedsEnv: "needs env: {names}",
+    marketplaceSourceTag: "[{source}]",
+    marketplaceNoInstall: "smithery listing — install metadata not exposed; use `npx -y @smithery/cli install {name}` directly",
+    marketplaceFetchOnInstall: "Smithery listing — install detail fetched on Install. http servers map to streamable-http remotes; stdio servers run via @smithery/cli.",
+    marketplaceInstalledBadge: "installed",
+    marketplaceUninstall: "Uninstall",
+    marketplaceEnvTitle: "Required environment variables",
+    marketplaceEnvHint: "Set these in your shell before next `reasonix code` so the bridged server can authenticate.",
+    marketplaceRestartHint: "Spec written to ~/.reasonix/config.json. Restart `reasonix code` to bridge the server (live hot-reload is on the roadmap).",
   },
   memory: {
     loading: "loading memory…",

dashboard/src/i18n/zh-CN.ts

@@ -264,6 +264,32 @@ export const zhCN = {
     colName: "名称",
     colDesc: "描述",
     colUri: "URI",
+    marketplace: "市场",
+    marketplaceSearch: "搜索注册表…",
+    marketplaceLoading: "加载注册表…",
+    marketplaceMore: "再加载 5 页",
+    marketplaceMoreLabel: "再加载 50 条  ·  当前 {shown} / {total}",
+    marketplaceMoreHint: "需要从远端注册表再拉几页",
+    marketplaceMoreCachedHint: "本地缓存已有更多条目",
+    marketplaceExhausted: "已加载全部页",
+    marketplaceExhaustedFull: "已展示全部 {total} 条 — 注册表耗尽",
+    marketplaceCount: "已载入 {loaded} · 匹配 {matched} · 来源：{source}{cached}",
+    marketplaceCachedSuffix: " · 缓存中",
+    marketplaceNoMatches: "无匹配结果。换关键词或加载更多页。",
+    marketplaceInstall: "安装",
+    marketplacePickHint: "在左侧选择服务器，然后点安装。",
+    marketplaceInstalled: "已安装 → {spec}",
+    marketplaceInstalledBridged: "已安装并桥接 → {spec}",
+    marketplaceAlready: "已安装过",
+    marketplaceNeedsEnv: "需设置环境变量：{names}",
+    marketplaceSourceTag: "[{source}]",
+    marketplaceNoInstall: "Smithery 列表项 — 不暴露安装元数据；请直接 `npx -y @smithery/cli install {name}`",
+    marketplaceFetchOnInstall: "Smithery 列表 — 安装时再拉详情。HTTP 服务映射为 streamable-http 远端；stdio 服务通过 @smithery/cli 运行。",
+    marketplaceInstalledBadge: "已安装",
+    marketplaceUninstall: "卸载",
+    marketplaceEnvTitle: "必需的环境变量",
+    marketplaceEnvHint: "下次启动 `reasonix code` 之前在 shell 里设好，桥接的服务器才能正常鉴权。",
+    marketplaceRestartHint: "已写入 ~/.reasonix/config.json。重启 `reasonix code` 后服务器才会真正桥接（热重载在路线图上）。",
   },
   memory: {
     loading: "加载记忆…",

dashboard/src/panels/chat.ts

@@ -559,7 +559,7 @@ export function ChatPanel() {
     <div class="chat-shell">
       <div style="display:flex;align-items:center;gap:12px;margin-bottom:10px">
         <div class="chips" style="padding:0">
-          <span class="chip-f active">${MODE === "attached" ? t("chat.modeMirror") : t("chat.modeView")}</span>
+          <span class="chip-f static active">${MODE === "attached" ? t("chat.modeMirror") : t("chat.modeView")}</span>
         </div>
         <div class="header-pickers" style="margin-left:auto">
           ${

dashboard/src/panels/hooks.ts

@@ -68,6 +68,7 @@ export function HooksPanel() {
   const [drafts, setDrafts] = useState<Record<string, string>>({});
   const [busy, setBusy] = useState(false);
   const [info, setInfo] = useState<string | null>(null);
+  const [eventFilter, setEventFilter] = useState<string>("all");
 
   const load = useCallback(async () => {
     try {
@@ -129,19 +130,31 @@ export function HooksPanel() {
     data.events.length > 0
       ? data.events
       : Array.from(new Set(matrixRows.flatMap((r) => Object.keys(r.cells))));
+  const visibleRows =
+    eventFilter === "all"
+      ? matrixRows
+      : matrixRows.filter((r) => r.cells[eventFilter]?.on);
   const gridCols = `220px repeat(${Math.max(events.length, 1)}, minmax(0, 1fr))`;
 
   return html`
     <div style="display:flex;flex-direction:column;gap:6px">
       <div class="chips">
-        <span class="chip-f active">${t("hooks.resolved")} <span class="ct">${data.resolved.length}</span></span>
-        ${data.events.map((ev) => html`<span class="chip-f">${ev}</span>`)}
+        <span
+          class=${`chip-f ${eventFilter === "all" ? "active" : ""}`}
+          onClick=${() => setEventFilter("all")}
+        >${t("hooks.resolved")} <span class="ct">${data.resolved.length}</span></span>
+        ${data.events.map(
+          (ev) => html`<span
+            class=${`chip-f ${eventFilter === ev ? "active" : ""}`}
+            onClick=${() => setEventFilter(ev)}
+          >${ev}</span>`,
+        )}
       </div>
       ${info ? html`<div><span class="pill ok">${info}</span></div>` : null}
       ${error ? html`<div class="card accent-err">${error}</div>` : null}
 
       ${sectionH3(t("hooks.eventMatrix"), t("hooks.matrixSub", { scripts: matrixRows.length, s: matrixRows.length === 1 ? "" : "s", events: events.length }))}${
-        matrixRows.length === 0
+        visibleRows.length === 0
           ? html`<div class="card" style="color:var(--fg-3)">
               ${t("hooks.noHooks")}
             </div>`
@@ -152,7 +165,7 @@ export function HooksPanel() {
                   <div>${t("hooks.colScript")}</div>
                   ${events.map((ev) => html`<div>${ev}</div>`)}
                 </div>
-                ${matrixRows.map(
+                ${visibleRows.map(
                   (r) => html`
                     <div class="row" style=${`grid-template-columns:${gridCols}`}>
                       <div class="cell" title=${r.command}>

dashboard/src/panels/mcp.ts

@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useState } from "preact/hooks";
+import { t, useLang } from "../i18n/index.js";
 import { api } from "../lib/api.js";
 import { fmtNum } from "../lib/format.js";
 import { html } from "../lib/html.js";
-import { t, useLang } from "../i18n/index.js";
 
 interface McpServer {
   label: string;
@@ -20,6 +20,60 @@ interface McpData {
   servers: McpServer[];
 }
 
+interface RegistryInstall {
+  runtime: string;
+  packageId?: string;
+  version?: string;
+  transport: string;
+  url?: string;
+  requiredEnv?: string[];
+  extraArgs?: string[];
+}
+
+interface RegistryEntryDto {
+  name: string;
+  title: string;
+  description: string;
+  source: "official" | "smithery" | "local";
+  install?: RegistryInstall;
+  popularity?: number;
+  homepage?: string;
+  iconUrl?: string;
+}
+
+/** Mirror of src/mcp/registry-fetch.ts:specStringFor — kept in sync to detect already-installed state without an extra round-trip. */
+function specForEntry(e: RegistryEntryDto): string | null {
+  if (!e.install) return null;
+  const localName = e.name.split("/").pop() ?? e.name;
+  const safe = localName.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^-+|-+$/g, "") || "mcp";
+  const trail = e.install.extraArgs?.length ? ` ${e.install.extraArgs.join(" ")}` : "";
+  if (e.install.runtime === "remote" && e.install.url) {
+    if (e.install.transport === "streamable-http") return `${safe}=streamable+${e.install.url}`;
+    return `${safe}=${e.install.url}`;
+  }
+  if (e.install.runtime === "npm" && e.install.packageId) {
+    const pinned = e.install.version
+      ? `${e.install.packageId}@${e.install.version}`
+      : e.install.packageId;
+    return `${safe}=npx -y ${pinned}${trail}`;
+  }
+  if (e.install.runtime === "pypi" && e.install.packageId) {
+    return `${safe}=uvx ${e.install.packageId}${trail}`;
+  }
+  return null;
+}
+
+interface RegistryListResponse {
+  source: "official" | "smithery" | "local";
+  fromCache: boolean;
+  fetchedAt: number;
+  loaded: number;
+  hasMore: boolean;
+  matched: number;
+  entries: RegistryEntryDto[];
+  errors: string[];
+}
+
 function specLabel(spec: string): string {
   const eq = spec.indexOf("=");
   return eq > 0 ? spec.slice(0, eq) : spec;
@@ -30,7 +84,7 @@ function specCommand(spec: string): string {
   return eq > 0 ? spec.slice(eq + 1) : spec;
 }
 
-type McpFilter = "all" | "live" | "unbridged";
+type McpFilter = "all" | "live" | "unbridged" | "marketplace";
 
 export function McpPanel() {
   useLang();
@@ -43,6 +97,70 @@ export function McpPanel() {
   const [open, setOpen] = useState<McpServer | null>(null);
   const [openUnbridged, setOpenUnbridged] = useState<string | null>(null);
   const [filter, setFilter] = useState<McpFilter>("all");
+  const [registry, setRegistry] = useState<RegistryListResponse | null>(null);
+  const [registryQuery, setRegistryQuery] = useState("");
+  const [registryLoading, setRegistryLoading] = useState(false);
+  const [openRegistry, setOpenRegistry] = useState<RegistryEntryDto | null>(null);
+  /** Display cap — grows by 50 each "load more" click. Server caps response size at this. */
+  const [displayLimit, setDisplayLimit] = useState(50);
+
+  const loadRegistry = useCallback(async (q: string, pages: number, limit: number) => {
+    setRegistryLoading(true);
+    try {
+      const params = new URLSearchParams();
+      if (q.trim()) params.set("q", q.trim());
+      params.set("pages", String(pages));
+      params.set("maxPages", String(Math.max(20, pages)));
+      params.set("limit", String(limit));
+      const r = await api<RegistryListResponse>(`/mcp/registry?${params.toString()}`);
+      setRegistry(r);
+    } catch (err) {
+      setError((err as Error).message);
+    } finally {
+      setRegistryLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (filter !== "marketplace") return;
+    if (registry) return;
+    void loadRegistry("", 1, displayLimit);
+  }, [filter, registry, loadRegistry, displayLimit]);
+
+  useEffect(() => {
+    if (filter !== "marketplace") return;
+    // Reset the display cap whenever the user retypes; new query = fresh top-50.
+    setDisplayLimit(50);
+    const handle = setTimeout(() => void loadRegistry(registryQuery, 1, 50), 300);
+    return () => clearTimeout(handle);
+  }, [registryQuery, filter, loadRegistry]);
+
+  const installFromRegistry = useCallback(async (entry: RegistryEntryDto) => {
+    setBusy(true);
+    try {
+      const r = await api<{
+        added: boolean;
+        alreadyPresent?: boolean;
+        bridged?: boolean;
+        spec: string;
+      }>("/mcp/registry/install", { method: "POST", body: { name: entry.name } });
+      if (r.alreadyPresent) {
+        setInfo(t("mcp.marketplaceAlready"));
+      } else if (r.bridged) {
+        setInfo(t("mcp.marketplaceInstalledBridged", { spec: r.spec }));
+      } else {
+        setInfo(t("mcp.marketplaceInstalled", { spec: r.spec }));
+      }
+      setTimeout(() => setInfo(null), 5000);
+      // Reload BOTH live + spec lists since hot-reload should have
+      // attached the new bridge.
+      await load();
+    } catch (err) {
+      setError((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }, []);
 
   const load = useCallback(async () => {
     try {
@@ -64,9 +182,7 @@ export function McpPanel() {
         method: "POST",
         body: { spec: newSpec.trim() },
       });
-      setInfo(
-        r.requiresRestart ? t("mcp.savedRestart") : t("mcp.saved"),
-      );
+      setInfo(r.requiresRestart ? t("mcp.savedRestart") : t("mcp.saved"));
       setTimeout(() => setInfo(null), 4000);
       setNewSpec("");
       await load();
@@ -95,15 +211,17 @@ export function McpPanel() {
     [load],
   );
 
-  if (!data && !error) return html`<div class="card" style="color:var(--fg-3)">${t("mcp.loading")}</div>`;
+  if (!data && !error)
+    return html`<div class="card" style="color:var(--fg-3)">${t("mcp.loading")}</div>`;
   if (error && !data) return html`<div class="card accent-err">${error}</div>`;
   if (!data) return null;
 
   const liveCount = data.servers.length;
   const unbridgedSpecs = (specs ?? []).filter((spec) => !data.servers.some((s) => s.spec === spec));
   const unbridgedCount = unbridgedSpecs.length;
-  const showLive = filter !== "unbridged";
-  const showUnbridged = filter !== "live";
+  const showLive = filter === "all" || filter === "live";
+  const showUnbridged = filter === "all" || filter === "unbridged";
+  const showMarketplace = filter === "marketplace";
 
   return html`
     <div class="sessions-grid">
@@ -116,29 +234,82 @@ export function McpPanel() {
             <span class=${`chip-f ${filter === "all" ? "active" : ""}`} onClick=${() => setFilter("all")}>${t("mcp.all")} <span class="ct">${liveCount + unbridgedCount}</span></span>
             <span class=${`chip-f ${filter === "live" ? "active" : ""}`} onClick=${() => setFilter("live")}>${t("mcp.live")} <span class="ct">${liveCount}</span></span>
             <span class=${`chip-f ${filter === "unbridged" ? "active" : ""}`} onClick=${() => setFilter("unbridged")}>${t("mcp.unbridged")} <span class="ct">${unbridgedCount}</span></span>
+            <span class=${`chip-f ${filter === "marketplace" ? "active" : ""}`} onClick=${() => setFilter("marketplace")}>${t("mcp.marketplace")}</span>
           </div>
         </div>
-        <div style="padding:8px 12px;display:flex;gap:6px">
-          <input
-            type="text"
-            placeholder=${t("mcp.specPlaceholder")}
-            value=${newSpec}
-            onInput=${(e: Event) => setNewSpec((e.target as HTMLInputElement).value)}
-            style="flex:1;font-size:11px"
-          />
-          <button class="btn primary" disabled=${busy || !newSpec.trim()} onClick=${addSpec}>+</button>
-        </div>
+        ${
+          showMarketplace
+            ? html`
+              <div style="padding:8px 12px;display:flex;gap:6px">
+                <input
+                  type="text"
+                  placeholder=${t("mcp.marketplaceSearch")}
+                  value=${registryQuery}
+                  onInput=${(e: Event) => setRegistryQuery((e.target as HTMLInputElement).value)}
+                  style="flex:1;font-size:11px"
+                />
+              </div>
+              ${
+                registry
+                  ? html`<div style="padding:0 12px 6px;font-size:11px;color:var(--fg-3)">
+                      ${t("mcp.marketplaceCount", {
+                        loaded: registry.loaded,
+                        matched: registry.matched,
+                        source: registry.source,
+                        cached: registry.fromCache ? t("mcp.marketplaceCachedSuffix") : "",
+                      })}
+                    </div>`
+                  : null
+              }
+            `
+            : html`
+              <div style="padding:8px 12px;display:flex;gap:6px">
+                <input
+                  type="text"
+                  placeholder=${t("mcp.specPlaceholder")}
+                  value=${newSpec}
+                  onInput=${(e: Event) => setNewSpec((e.target as HTMLInputElement).value)}
+                  style="flex:1;font-size:11px"
+                />
+                <button class="btn primary" disabled=${busy || !newSpec.trim()} onClick=${addSpec}>+</button>
+              </div>
+            `
+        }
         ${info ? html`<div style="padding:0 12px 8px"><span class="pill ok">${info}</span></div>` : null}
         ${error ? html`<div class="card accent-err" style="margin:0 12px 8px">${error}</div>` : null}
 
         <div class="ssl-rows">
           ${
-            liveCount === 0 && unbridgedCount === 0
+            !showMarketplace && liveCount === 0 && unbridgedCount === 0
               ? html`<div style="color:var(--fg-3);padding:14px;font-size:12px">
                 ${t("mcp.noServers")}
               </div>`
               : null
           }
+          ${
+            showMarketplace
+              ? renderMarketplaceRows({
+                  registry,
+                  registryLoading,
+                  openRegistry,
+                  setOpenRegistry: (e) => {
+                    setOpenRegistry(e);
+                    setOpen(null);
+                    setOpenUnbridged(null);
+                  },
+                  loadMore: () => {
+                    const nextLimit = displayLimit + 50;
+                    setDisplayLimit(nextLimit);
+                    // Pages: walk far enough to fill the new cap (each page ≈ 30
+                    // entries) plus a few-page lookahead so the next click also
+                    // has fresh data.
+                    const pagesNeeded = Math.ceil(nextLimit / 30) + 3;
+                    void loadRegistry(registryQuery, pagesNeeded, nextLimit);
+                  },
+                  installedSpecs: new Set(specs ?? []),
+                })
+              : null
+          }
           ${
             showLive
               ? data.servers.map(
@@ -182,8 +353,20 @@ export function McpPanel() {
 
       <div class="sessions-detail">
         ${
-          openUnbridged != null
-            ? html`
+          openRegistry != null
+            ? renderRegistryDetail({
+                entry: openRegistry,
+                busy,
+                installedSpec: (() => {
+                  const spec = specForEntry(openRegistry);
+                  return spec && (specs ?? []).includes(spec) ? spec : null;
+                })(),
+                onInstall: () => installFromRegistry(openRegistry),
+                onUninstall: (spec: string) => removeSpec(spec),
+                onClose: () => setOpenRegistry(null),
+              })
+            : openUnbridged != null
+              ? html`
               <div class="sessions-detail-h">
                 <span class="name">${specLabel(openUnbridged)}</span>
                 <span class="ws"><span class="pill">${t("mcp.unbridgedTitle")}</span></span>
@@ -207,11 +390,11 @@ export function McpPanel() {
                 </div>
               </div>
             `
-            : open == null
-              ? html`<div style="color:var(--fg-3);font-size:13px;text-align:center;padding:60px 20px">
-                ${t("mcp.pickHint")}
+              : open == null
+                ? html`<div style="color:var(--fg-3);font-size:13px;text-align:center;padding:60px 20px">
+                ${showMarketplace ? t("mcp.marketplacePickHint") : t("mcp.pickHint")}
               </div>`
-              : html`
+                : html`
                 <div class="sessions-detail-h">
                   <span class="name">${open.label}</span>
                   <span class="ws">${open.serverInfo?.name ?? "—"} ${open.serverInfo?.version ? `v${open.serverInfo.version}` : ""} · ${open.protocolVersion ?? "—"}</span>
@@ -295,3 +478,198 @@ export function McpPanel() {
     </div>
   `;
 }
+
+interface MarketplaceRowsArgs {
+  registry: RegistryListResponse | null;
+  registryLoading: boolean;
+  openRegistry: RegistryEntryDto | null;
+  setOpenRegistry: (entry: RegistryEntryDto) => void;
+  loadMore: () => void;
+  installedSpecs: Set<string>;
+}
+
+function renderLoadMoreFooter({
+  registry,
+  registryLoading,
+  loadMore,
+}: Pick<MarketplaceRowsArgs, "registry" | "registryLoading" | "loadMore">) {
+  if (!registry) return null;
+  const shown = registry.entries.length;
+  const total = registry.matched;
+  const moreCached = total > shown;
+  const moreOnNetwork = registry.hasMore;
+  const canDoSomething = moreCached || moreOnNetwork;
+
+  // Three states:
+  //   1. Loading           — disabled button + spinner-ish label
+  //   2. More available    — primary button + count of what's loaded
+  //   3. Exhausted         — distinct success-tinted card so the user
+  //      doesn't think the button stopped responding
+  if (canDoSomething) {
+    const label = registryLoading
+      ? t("mcp.marketplaceLoading")
+      : t("mcp.marketplaceMoreLabel", {
+          shown,
+          total: moreOnNetwork ? `${total}+` : `${total}`,
+        });
+    return html`<div style="padding:10px 12px;display:flex;align-items:center;gap:10px">
+      <button class="btn primary" disabled=${registryLoading} onClick=${loadMore}>${label}</button>
+      <span style="font-size:11px;color:var(--fg-3)">
+        ${moreOnNetwork ? t("mcp.marketplaceMoreHint") : t("mcp.marketplaceMoreCachedHint")}
+      </span>
+    </div>`;
+  }
+
+  return html`<div style="padding:12px;background:var(--bg-elev-2,rgba(36,143,242,0.07));border-top:1px solid var(--bd);display:flex;align-items:center;gap:8px;font-size:12px;color:var(--fg-2)">
+    <span style="color:var(--c-ok)">✓</span>
+    <span>${t("mcp.marketplaceExhaustedFull", { total })}</span>
+  </div>`;
+}
+
+function renderMarketplaceRows({
+  registry,
+  registryLoading,
+  openRegistry,
+  setOpenRegistry,
+  loadMore,
+  installedSpecs,
+}: MarketplaceRowsArgs) {
+  if (!registry && registryLoading) {
+    return html`<div style="color:var(--fg-3);padding:14px;font-size:12px">${t("mcp.marketplaceLoading")}</div>`;
+  }
+  if (!registry || registry.entries.length === 0) {
+    return html`<div style="color:var(--fg-3);padding:14px;font-size:12px">${t("mcp.marketplaceNoMatches")}</div>`;
+  }
+  return html`
+    ${registry.entries.map((e) => {
+      const sel = openRegistry?.name === e.name;
+      const tag = t("mcp.marketplaceSourceTag", { source: e.source });
+      const spec = specForEntry(e);
+      const installed = spec !== null && installedSpecs.has(spec);
+      const pop =
+        e.popularity !== undefined
+          ? html` <span class="dim">· ${fmtNum(e.popularity)}</span>`
+          : null;
+      const icon = e.iconUrl
+        ? html`<img src=${e.iconUrl} alt="" style="width:16px;height:16px;border-radius:3px;margin-right:6px;vertical-align:middle;object-fit:cover" loading="lazy" referrerpolicy="no-referrer" onError=${(ev: Event) => ((ev.target as HTMLImageElement).style.display = "none")} />`
+        : null;
+      return html`
+        <div class=${`ssl-row ${sel ? "sel" : ""}`} onClick=${() => setOpenRegistry(e)}>
+          <span class="name">${icon}${e.name} <span class="pill">${tag}</span>${installed ? html` <span class="pill ok">${t("mcp.marketplaceInstalledBadge")}</span>` : null}</span>
+          <span class="preview">${e.description}</span>
+          <span class="meta">${pop}</span>
+        </div>
+      `;
+    })}
+    ${renderLoadMoreFooter({ registry, registryLoading, loadMore })}
+  `;
+}
+
+interface RegistryDetailArgs {
+  entry: RegistryEntryDto;
+  busy: boolean;
+  installedSpec: string | null;
+  onInstall: () => void;
+  onUninstall: (spec: string) => void;
+  onClose: () => void;
+}
+
+function renderRegistryDetail({
+  entry,
+  busy,
+  installedSpec,
+  onInstall,
+  onUninstall,
+  onClose,
+}: RegistryDetailArgs) {
+  const installable = !!entry.install || entry.source === "smithery";
+  const installed = installedSpec !== null;
+  const specPreview = entry.install
+    ? `${entry.install.runtime} · ${entry.install.transport}${
+        entry.install.packageId
+          ? ` · ${entry.install.packageId}`
+          : entry.install.url
+            ? ` · ${entry.install.url}`
+            : ""
+      }${entry.install.version ? `@${entry.install.version}` : ""}`
+    : "";
+  const icon = entry.iconUrl
+    ? html`<img src=${entry.iconUrl} alt="" style="width:24px;height:24px;border-radius:4px;margin-right:8px;vertical-align:middle;object-fit:cover" loading="lazy" referrerpolicy="no-referrer" onError=${(ev: Event) => ((ev.target as HTMLImageElement).style.display = "none")} />`
+    : null;
+  return html`
+    <div class="sessions-detail-h">
+      <span class="name">${icon}${entry.name}${installed ? html` <span class="pill ok">${t("mcp.marketplaceInstalledBadge")}</span>` : null}</span>
+      <span class="ws">${t("mcp.marketplaceSourceTag", { source: entry.source })}${
+        entry.popularity !== undefined ? ` · ${fmtNum(entry.popularity)} uses` : ""
+      }${entry.homepage ? html` · <a href=${entry.homepage} target="_blank" rel="noopener noreferrer">homepage</a>` : ""}</span>
+      <span class="actions">
+        ${
+          installed
+            ? html`<button
+                class="btn"
+                disabled=${busy}
+                onClick=${() => onUninstall(installedSpec)}
+                style="border-color:var(--c-err);color:var(--c-err)"
+              >${t("mcp.marketplaceUninstall")}</button>`
+            : html`<button class="btn primary" disabled=${busy || !installable} onClick=${onInstall}>${t("mcp.marketplaceInstall")}</button>`
+        }
+        <button class="btn ghost" onClick=${onClose}>${t("common.back")}</button>
+      </span>
+    </div>
+
+    <div class="card" style="margin-bottom:12px">
+      <div class="card-b" style="font-size:13px;line-height:1.6">${entry.description || "—"}</div>
+    </div>
+
+    ${
+      entry.install
+        ? html`<div class="card" style="margin-bottom:12px">
+            <div class="card-h"><span class="title">${t("mcp.spec")}</span></div>
+            <div class="card-b">
+              <code class="mono" style="font-size:11.5px;color:var(--fg-2);word-break:break-all;display:block">${specPreview}</code>
+              ${
+                installedSpec
+                  ? html`<div style="margin-top:8px;font-size:11px;color:var(--fg-3)">
+                      <span class="dim">on disk:</span> <code class="mono">${installedSpec}</code>
+                    </div>`
+                  : null
+              }
+            </div>
+          </div>`
+        : entry.source === "smithery"
+          ? html`<div class="card" style="margin-bottom:12px">
+              <div class="card-b" style="font-size:13px;line-height:1.6;color:var(--fg-3)">
+                ${t("mcp.marketplaceFetchOnInstall")}
+              </div>
+            </div>`
+          : null
+    }
+
+    ${
+      entry.install?.requiredEnv?.length
+        ? html`<div class="card accent-brand" style="margin-bottom:12px">
+            <div class="card-h"><span class="title">${t("mcp.marketplaceEnvTitle")}</span></div>
+            <div class="card-b" style="font-size:13px">
+              ${entry.install.requiredEnv.map(
+                (name) =>
+                  html`<div><code class="mono" style="color:var(--c-warn)">${name}</code></div>`,
+              )}
+              <div style="margin-top:6px;color:var(--fg-3);font-size:12px">
+                ${t("mcp.marketplaceEnvHint")}
+              </div>
+            </div>
+          </div>`
+        : null
+    }
+
+    ${
+      installed
+        ? html`<div class="card accent-warn">
+            <div class="card-b" style="font-size:12.5px;line-height:1.6">
+              ${t("mcp.marketplaceRestartHint")}
+            </div>
+          </div>`
+        : null
+    }
+  `;
+}

dashboard/src/panels/permissions.ts

@@ -122,8 +122,8 @@ export function PermissionsPanel() {
       }
 
       <div class="chips">
-        <span class="chip-f active">${t("permissions.project")} <span class="ct">${p.project.length}</span></span>
-        <span class="chip-f">${t("permissions.builtin")} <span class="ct">${p.builtin.length}</span></span>
+        <span class="chip-f static active">${t("permissions.project")} <span class="ct">${p.project.length}</span></span>
+        <span class="chip-f static">${t("permissions.builtin")} <span class="ct">${p.builtin.length}</span></span>
       </div>
 
       ${

dashboard/src/panels/plans.ts

@@ -37,6 +37,7 @@ export function PlansPanel() {
   const { data, error, loading } = usePoll<PlansData>("/plans", 8000);
   const [openIdx, setOpenIdx] = useState<number | null>(null);
   const [filter, setFilter] = useState("");
+  const [statusFilter, setStatusFilter] = useState<"all" | "active" | "done">("all");
 
   if (loading && !data)
     return html`<div class="card" style="color:var(--fg-3)">${t("plans.loading")}</div>`;
@@ -48,13 +49,19 @@ export function PlansPanel() {
       ${t("plans.noPlans")}
     </div>`;
 
+  const statusFiltered =
+    statusFilter === "all"
+      ? plans
+      : statusFilter === "active"
+        ? plans.filter((p) => p.completionRatio > 0 && p.completionRatio < 1)
+        : plans.filter((p) => p.completionRatio >= 1);
   const filtered = filter.trim()
-    ? plans.filter(
+    ? statusFiltered.filter(
         (p) =>
           p.session.toLowerCase().includes(filter.toLowerCase()) ||
           (p.summary ?? "").toLowerCase().includes(filter.toLowerCase()),
       )
-    : plans;
+    : statusFiltered;
 
   const open = openIdx !== null ? plans[openIdx] : null;
 
@@ -71,12 +78,21 @@ export function PlansPanel() {
           />
         </div>
         <div class="chips" style="padding:0 12px 8px">
-          <span class="chip-f active">${t("common.all")} <span class="ct">${plans.length}</span></span>
-          <span class="chip-f">
+          <span
+            class=${`chip-f ${statusFilter === "all" ? "active" : ""}`}
+            onClick=${() => setStatusFilter("all")}
+          >${t("common.all")} <span class="ct">${plans.length}</span></span>
+          <span
+            class=${`chip-f ${statusFilter === "active" ? "active" : ""}`}
+            onClick=${() => setStatusFilter("active")}
+          >
             ${t("plans.active")}
             <span class="ct">${plans.filter((p) => p.completionRatio > 0 && p.completionRatio < 1).length}</span>
           </span>
-          <span class="chip-f">
+          <span
+            class=${`chip-f ${statusFilter === "done" ? "active" : ""}`}
+            onClick=${() => setStatusFilter("done")}
+          >
             ${t("plans.done")} <span class="ct">${plans.filter((p) => p.completionRatio >= 1).length}</span>
           </span>
         </div>

dashboard/src/panels/semantic.ts

@@ -179,13 +179,13 @@ export function SemanticPanel() {
     <div style="display:grid;grid-template-columns:minmax(0,1fr) 280px;gap:14px;align-items:start">
       <div style="display:flex;flex-direction:column;gap:10px;min-width:0">
         <div class="chips">
-          <span class=${`chip-f ${idx?.exists ? "active" : ""}`}>
+          <span class=${`chip-f static ${idx?.exists ? "active" : ""}`}>
             ${idx?.exists ? t("semantic.indexBuilt") : t("semantic.noIndex")}
           </span>
           ${
             ready
-              ? html`<span class="chip-f" style="border-color:var(--c-ok);color:var(--c-ok)">${t("semantic.ready")}</span>`
-              : html`<span class="chip-f" style="border-color:var(--c-warn);color:var(--c-warn)">${t("semantic.setupNeeded")}</span>`
+              ? html`<span class="chip-f static" style="border-color:var(--c-ok);color:var(--c-ok)">${t("semantic.ready")}</span>`
+              : html`<span class="chip-f static" style="border-color:var(--c-warn);color:var(--c-warn)">${t("semantic.setupNeeded")}</span>`
           }
         </div>
         ${info ? html`<div><span class="pill info">${info}</span></div>` : null}
@@ -730,7 +730,7 @@ function ChipFormRow({
       <div style="display:flex;flex-wrap:wrap;gap:4px">
         ${value.map(
           (e) => html`
-            <span class="chip-f">
+            <span class="chip-f static">
               <span>${e}</span>
               <span class="x" style="cursor:pointer" onClick=${() => remove(e)} title="remove">×</span>
             </span>

dashboard/src/panels/sessions.ts

@@ -68,7 +68,7 @@ export function SessionsPanel() {
           />
         </div>
         <div class="chips" style="padding:0 12px 8px">
-          <span class="chip-f active">${t("common.all")} <span class="ct">${sessions.length}</span></span>
+          <span class="chip-f static active">${t("common.all")} <span class="ct">${sessions.length}</span></span>
         </div>
         <div class="ssl-rows">
           ${filtered.map(

dashboard/src/panels/skills.ts

@@ -29,6 +29,7 @@ export function SkillsPanel() {
   const [newName, setNewName] = useState("");
   const [newScope, setNewScope] = useState<"global" | "project">("global");
   const [filter, setFilter] = useState("");
+  const [scopeFilter, setScopeFilter] = useState<"all" | Scope>("all");
 
   const load = useCallback(async () => {
     try {
@@ -120,13 +121,15 @@ export function SkillsPanel() {
     ...data.global.map((s) => ({ scope: "global" as Scope, ...s })),
     ...data.builtin.map((s) => ({ scope: "builtin" as Scope, ...s })),
   ];
+  const scopeFiltered =
+    scopeFilter === "all" ? allWith : allWith.filter((s) => s.scope === scopeFilter);
   const filtered = filter.trim()
-    ? allWith.filter(
+    ? scopeFiltered.filter(
         (s) =>
           s.name.toLowerCase().includes(filter.toLowerCase()) ||
           (s.description ?? "").toLowerCase().includes(filter.toLowerCase()),
       )
-    : allWith;
+    : scopeFiltered;
 
   return html`
     <div class="sessions-grid">
@@ -141,10 +144,22 @@ export function SkillsPanel() {
           />
         </div>
         <div class="chips" style="padding:0 12px 8px">
-          <span class="chip-f active">${t("common.all")} <span class="ct">${allWith.length}</span></span>
-          <span class="chip-f">${t("skills.project")} <span class="ct">${data.project.length}</span></span>
-          <span class="chip-f">${t("skills.global")} <span class="ct">${data.global.length}</span></span>
-          <span class="chip-f">${t("skills.builtin")} <span class="ct">${data.builtin.length}</span></span>
+          <span
+            class=${`chip-f ${scopeFilter === "all" ? "active" : ""}`}
+            onClick=${() => setScopeFilter("all")}
+          >${t("common.all")} <span class="ct">${allWith.length}</span></span>
+          <span
+            class=${`chip-f ${scopeFilter === "project" ? "active" : ""}`}
+            onClick=${() => setScopeFilter("project")}
+          >${t("skills.project")} <span class="ct">${data.project.length}</span></span>
+          <span
+            class=${`chip-f ${scopeFilter === "global" ? "active" : ""}`}
+            onClick=${() => setScopeFilter("global")}
+          >${t("skills.global")} <span class="ct">${data.global.length}</span></span>
+          <span
+            class=${`chip-f ${scopeFilter === "builtin" ? "active" : ""}`}
+            onClick=${() => setScopeFilter("builtin")}
+          >${t("skills.builtin")} <span class="ct">${data.builtin.length}</span></span>
         </div>
 
         <div style="padding:0 12px 8px;display:flex;gap:6px;flex-wrap:wrap">

dashboard/src/panels/tools.ts

@@ -37,8 +37,8 @@ export function ToolsPanel() {
   return html`
     <div style="display:flex;flex-direction:column;gap:14px">
       <div class="chips">
-        <span class="chip-f active">${t("common.all")} <span class="ct">${d.total}</span></span>
-        ${d.planMode ? html`<span class="chip-f" style="border-color:var(--c-warn);color:var(--c-warn)">${t("tools.planMode")}</span>` : null}
+        <span class="chip-f static active">${t("common.all")} <span class="ct">${d.total}</span></span>
+        ${d.planMode ? html`<span class="chip-f static" style="border-color:var(--c-warn);color:var(--c-warn)">${t("tools.planMode")}</span>` : null}
       </div>
 
       ${

dashboard/src/panels/usage.ts

@@ -174,8 +174,8 @@ export function UsagePanel() {
   return html`
     <div style="display:flex;flex-direction:column;gap:6px">
       <div class="chips">
-        <span class="chip-f active">${t("usage.records", { count: u.recordCount.toLocaleString() })}</span>
-        <span class="chip-f">${u.logSize}</span>
+        <span class="chip-f static active">${t("usage.records", { count: u.recordCount.toLocaleString() })}</span>
+        <span class="chip-f static">${u.logSize}</span>
       </div>
 
       ${

docs/ARCHITECTURE.md

@@ -43,6 +43,29 @@ timestamps each turn — cache hit rate in practice: <20%.
 **Metric.** `prompt_cache_hit_tokens / (hit + miss)` exposed per-turn and
 aggregated per-session. Visible in the TUI's top-bar cache cell.
 
+#### Parallel tool dispatch
+
+Each tool declares `parallelSafe?: boolean` (default `false`). The loop
+dispatcher groups consecutive parallel-safe calls into chunks and races
+them via `Promise.allSettled`; the first non-parallel-safe call ends the
+chunk and runs alone (serial barrier — read-after-write order
+preserved). Tool-result yields and history append still land in declared
+order regardless of which call settles first, so the model sees the
+same shape it would under a fully serial dispatch.
+
+| Env var | Default | Effect |
+|---|---|---|
+| `REASONIX_PARALLEL_MAX` | `3` (hard cap `16`) | Max chunk size. |
+| `REASONIX_TOOL_DISPATCH=serial` | unset | Forces serial dispatch — escape hatch. |
+
+Built-in opt-ins: read-only filesystem (`read_file`, `list_directory`,
+`directory_tree`, `search_files`, `search_content`, `get_file_info`),
+web (`web_search`, `web_fetch`), `recall_memory`, `semantic_search`,
+isolated child loops (`run_skill`, `spawn_subagent`), in-memory job
+queries (`job_output`, `list_jobs`). Mutating / side-effecting tools
+stay default. MCP-bridged tools default `false` — third-party tools
+opt in only when the server explicitly declares parallel safety.
+
 ### Pillar 2 — R1 Thought Harvesting *(opt-in)*
 
 **Problem.** R1 / V4-thinking emits extensive `reasoning_content`. DeepSeek's

docs/assets/feature-grid.svg

@@ -1,10 +1,10 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 320" role="img" aria-label="Reasonix feature grid — six cards covering cache-first loop, plan mode, MCP, sessions, hooks, memory and skills">
-  <title>Reasonix feature grid</title>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 570" role="img" aria-label="Reasonix capability grid — twelve features covering renderer, MCP, plan mode, permissions, dashboard, sessions, hooks, semantic search, checkpoints, effort knob, replay, event log">
+  <title>Reasonix capabilities</title>
   <defs>
     <style>
-      .sans  { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
-      .ic    { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
-      .ttl   { font-weight: 700; }
+      .sans { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
+      .mono { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
+      .ttl  { font-weight: 700; }
     </style>
     <linearGradient id="ig" x1="0%" y1="0%" x2="100%" y2="100%">
       <stop offset="0%"  stop-color="#5eead4"/>
@@ -14,50 +14,90 @@
   </defs>
 
   <g transform="translate(10, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">◈</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Cache-first loop</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">Byte-stable prompt prefix.</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">94% live cache hit on tau-bench.</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◈</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Cell-diff renderer</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Custom TUI on Yoga, no Ink.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Wide-char · emoji · paste · resize-clean.</text>
   </g>
-
   <g transform="translate(300, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">✎</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Plan mode · edit review</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">Read-only audit gate before</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">writes. Nothing on disk until /apply.</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⊕</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">MCP first-class</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">stdio · Streamable HTTP transports.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Tools, resources, prompts.</text>
   </g>
-
   <g transform="translate(590, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⊕</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">MCP first-class</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">stdio · SSE · Streamable HTTP.</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">Same cache-safety as native tools.</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">✎</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Plan mode</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Review proposed edits before writes.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Plan checkpoints persist across runs.</text>
   </g>
 
-  <g transform="translate(10, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⌨</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Sessions · dashboard</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">Per-workspace persistent log.</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">/dashboard opens a TUI mirror.</text>
+  <g transform="translate(10, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⊞</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Permissions</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">allow · ask · deny per tool.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Granular shell rules. Teachable.</text>
+  </g>
+  <g transform="translate(300, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">▣</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Embedded dashboard</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Live cache hit · cost · session timeline</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">· MCP health. localhost companion.</text>
+  </g>
+  <g transform="translate(590, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⌨</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Persistent sessions</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Per-workspace, named, resumable.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">--resume restores state fully.</text>
   </g>
 
-  <g transform="translate(300, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⚙</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Hooks</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">Shell scripts on Pre/Post tool.</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">6 lifecycle events, harness-run.</text>
+  <g transform="translate(10, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⚙</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Hooks · skills · memory</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Shell on lifecycle events.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Skill packs + project memory.</text>
+  </g>
+  <g transform="translate(300, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◎</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Semantic search</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">reasonix index builds embeddings.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Local Ollama or DeepSeek-hosted.</text>
+  </g>
+  <g transform="translate(590, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">↺</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Auto-checkpoints</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Cursor-style session-scoped rollback.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Never pollutes git history.</text>
   </g>
 
-  <g transform="translate(590, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">¶</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Memory · skills</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">REASONIX.md + private user mem.</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">Skill packs spawn sub-agents.</text>
+  <g transform="translate(10, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◐</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">/effort knob</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Switch reasoning depth per turn.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Slash command and CLI flag.</text>
+  </g>
+  <g transform="translate(300, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">▶</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Transcript replay</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">reasonix replay re-renders sessions.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Bug reports, demos, audits.</text>
+  </g>
+  <g transform="translate(590, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">¶</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Event log</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">events.jsonl sidecar + reducers.</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Build dashboards or analytics.</text>
   </g>
 </svg>

docs/assets/feature-grid.zh-CN.svg

@@ -1,10 +1,10 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 320" role="img" aria-label="Reasonix 功能一览 — 缓存优先循环、计划模式、MCP、会话、Hooks、Memory 与 Skills">
-  <title>Reasonix 功能一览</title>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 570" role="img" aria-label="Reasonix 能力一览 — 12 张卡片：渲染器、MCP、计划模式、权限、仪表盘、会话、Hooks、语义检索、checkpoint、effort 旋钮、重放、事件日志">
+  <title>Reasonix 能力一览</title>
   <defs>
     <style>
-      .sans  { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
-      .ic    { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
-      .ttl   { font-weight: 700; }
+      .sans { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
+      .mono { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
+      .ttl  { font-weight: 700; }
     </style>
     <linearGradient id="ig" x1="0%" y1="0%" x2="100%" y2="100%">
       <stop offset="0%"  stop-color="#5eead4"/>
@@ -14,50 +14,90 @@
   </defs>
 
   <g transform="translate(10, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">◈</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">缓存优先的循环</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">prompt 前缀字节稳定。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">tau-bench 上 94% 实测命中。</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◈</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">自研 cell-diff 渲染器</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">基于 Yoga，不依赖 Ink。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">宽字符 · emoji · 粘贴 · resize 全干净。</text>
   </g>
-
   <g transform="translate(300, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">✎</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">计划模式 · 编辑审查</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">写盘前先过只读审计闸。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">不 /apply 一行都不改。</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⊕</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">MCP 一等公民</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">stdio · Streamable HTTP 双传输。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">工具 / 资源 / 提示词全套。</text>
   </g>
-
   <g transform="translate(590, 10)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⊕</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">MCP 一等公民</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">stdio · SSE · Streamable HTTP。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">和原生工具一样保缓存。</text>
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">✎</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">计划模式</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">修改在落盘前先 review。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Plan checkpoint 跨运行持久化。</text>
   </g>
 
-  <g transform="translate(10, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⌨</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">会话 · 仪表盘</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">按工作区持久化日志。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">/dashboard 开浏览器镜像 TUI。</text>
+  <g transform="translate(10, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⊞</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">权限系统</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">每个工具 allow / ask / deny。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">shell 命令粒度规则，可教。</text>
+  </g>
+  <g transform="translate(300, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">▣</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">内嵌仪表盘</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">实时缓存命中、成本、会话时间线、</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">MCP 健康。localhost 伴生面板。</text>
+  </g>
+  <g transform="translate(590, 150)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⌨</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">持久化会话</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">按工作区组织、命名、可恢复。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">--resume 完全还原状态。</text>
   </g>
 
-  <g transform="translate(300, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">⚙</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Hooks</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">Pre/Post tool 时跑 shell 脚本。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">6 个生命周期事件，由 harness 触发。</text>
+  <g transform="translate(10, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">⚙</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Hooks · Skills · Memory</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">生命周期事件触发 shell。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">Skill 包 + 项目级 memory。</text>
+  </g>
+  <g transform="translate(300, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◎</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">语义检索</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">reasonix index 构建 embedding 索引。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">本地 Ollama 或 DeepSeek 托管。</text>
+  </g>
+  <g transform="translate(590, 290)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">↺</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">自动 checkpoint</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">Cursor 风格会话级 AI 编辑回滚。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">不污染 git 历史。</text>
   </g>
 
-  <g transform="translate(590, 170)">
-    <rect width="280" height="140" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
-    <text x="22" y="44" class="ic" font-size="24" fill="url(#ig)">¶</text>
-    <text x="56" y="42" class="sans ttl" font-size="15" fill="#e6edf3">Memory · Skills</text>
-    <text x="22" y="78" class="sans" font-size="13" fill="#8b949e">REASONIX.md 加用户私有 memory。</text>
-    <text x="22" y="98" class="sans" font-size="13" fill="#8b949e">Skill 包可起 sub-agent 执行。</text>
+  <g transform="translate(10, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">◐</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">/effort 旋钮</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">每回合切换 reasoning 深度。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">斜杠命令 + CLI flag 双入口。</text>
+  </g>
+  <g transform="translate(300, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">▶</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">Transcript 重放</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">reasonix replay 重渲染会话。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">bug 复现、演示、审计。</text>
+  </g>
+  <g transform="translate(590, 430)">
+    <rect width="280" height="130" rx="10" ry="10" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="22" y="42" class="mono" font-size="22" fill="url(#ig)">¶</text>
+    <text x="54" y="40" class="sans ttl" font-size="14" fill="#e6edf3">事件日志</text>
+    <text x="22" y="72" class="sans" font-size="12" fill="#8b949e">events.jsonl 旁路日志 + reducer。</text>
+    <text x="22" y="92" class="sans" font-size="12" fill="#8b949e">自建仪表盘或分析。</text>
   </g>
 </svg>

docs/assets/og-card.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" role="img" aria-label="Reasonix — DeepSeek-native AI coding agent for your terminal">
+  <title>Reasonix social card</title>
+  <defs>
+    <style>
+      .mono { font-family: Consolas, "Courier New", monospace; font-weight: 500; }
+      .sans { font-family: "Segoe UI", Arial, sans-serif; }
+    </style>
+    <linearGradient id="brand" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#5eead4"/>
+      <stop offset="50%" stop-color="#93c5fd"/>
+      <stop offset="100%" stop-color="#c4b5fd"/>
+    </linearGradient>
+    <linearGradient id="bgfade" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#0a0c10"/>
+      <stop offset="100%" stop-color="#11141a"/>
+    </linearGradient>
+    <pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="#1e2436" stroke-width="0.5"/>
+    </pattern>
+  </defs>
+
+  <rect width="1280" height="640" fill="url(#bgfade)"/>
+  <rect width="1280" height="640" fill="url(#grid)" opacity="0.4"/>
+
+  <g transform="translate(80, 96)">
+    <text class="sans" font-size="22" font-weight="600" letter-spacing="6" fill="#5eead4" opacity="0.85">REASONIX</text>
+    <text y="100" class="sans" font-size="84" font-weight="800" fill="#e6edf3" letter-spacing="-2">DeepSeek-native</text>
+    <text y="184" class="sans" font-size="84" font-weight="800" fill="url(#brand)" letter-spacing="-2">AI coding agent.</text>
+    <text y="244" class="sans" font-size="26" fill="#8b949e">Engineered around prefix-cache stability — leave it running.</text>
+  </g>
+
+  <g transform="translate(80, 432)">
+    <rect x="0" y="0" width="1120" height="128" rx="10" fill="#0d1117" stroke="#1e2436"/>
+    <circle cx="22" cy="20" r="6" fill="#ff8b81"/>
+    <circle cx="42" cy="20" r="6" fill="#f0b07d"/>
+    <circle cx="62" cy="20" r="6" fill="#7ee787"/>
+    <text x="560" y="25" text-anchor="middle" class="mono" font-size="12" fill="url(#brand)">reasonix code</text>
+    <line x1="0" y1="40" x2="1120" y2="40" stroke="#1e2436"/>
+    <g class="mono" font-size="18">
+      <text x="20" y="74"><tspan fill="#79c0ff">›</tspan><tspan fill="#c9d1d9" xml:space="preserve"> fix the case-sensitivity bug in findByEmail</tspan></text>
+      <text x="20" y="106"><tspan fill="#7ee787">+</tspan><tspan fill="#8b949e" xml:space="preserve"> queued: src/users.ts (1 edit)  ·  </tspan><tspan fill="#d2a8ff">/apply</tspan><tspan fill="#8b949e" xml:space="preserve"> to commit</tspan></text>
+    </g>
+  </g>
+
+  <g transform="translate(80, 360)" class="sans" font-size="16" fill="#8b949e">
+    <text>
+      <tspan fill="#5eead4">●</tspan> Cache-First Loop
+      <tspan dx="24" fill="#93c5fd">●</tspan> R1 Thought Harvesting
+      <tspan dx="24" fill="#c4b5fd">●</tspan> Tool-Call Repair
+    </text>
+  </g>
+
+  <text x="1200" y="600" text-anchor="end" class="mono" font-size="14" fill="#484f58">github.com/esengine/reasonix</text>
+</svg>

docs/assets/pillars.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 360" role="img" aria-label="Reasonix four pillars — cache-first loop, R1 thought harvesting, tool-call repair, cost control">
+  <title>Reasonix four pillars</title>
+  <defs>
+    <style>
+      .sans { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
+      .mono { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
+      .ttl  { font-weight: 700; }
+      .num  { font-weight: 800; letter-spacing: 0.08em; }
+    </style>
+    <linearGradient id="ig" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%"  stop-color="#5eead4"/>
+      <stop offset="50%" stop-color="#93c5fd"/>
+      <stop offset="100%" stop-color="#c4b5fd"/>
+    </linearGradient>
+  </defs>
+
+  <g transform="translate(10, 10)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">01 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">Cache-first loop</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">Append-only history with no in-place</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">mutation. Byte prefix survives every tool</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">call — the cache keeps hitting.</text>
+  </g>
+
+  <g transform="translate(450, 10)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">02 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">R1 thought harvesting</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">Distills reasoning_content into typed plan</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">state — subgoals, hypotheses, rejected paths.</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">Signal kept, noise dropped.</text>
+  </g>
+
+  <g transform="translate(10, 190)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">03 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">Tool-call repair</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">Schema flatten · JSON repair · scavenge from</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">&lt;think&gt; · truncation. Four strategies for</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">DeepSeek-specific quirks.</text>
+  </g>
+
+  <g transform="translate(450, 190)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">04 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">Cost control</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">Cache-safe folding · aggressive-fold tier ·</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">model-aware budgets. Context size managed</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">without breaking prefix.</text>
+  </g>
+</svg>

docs/assets/pillars.zh-CN.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 360" role="img" aria-label="Reasonix 四大支柱 — 缓存优先循环、R1 思维提取、工具调用修复、成本控制">
+  <title>Reasonix 四大支柱</title>
+  <defs>
+    <style>
+      .sans { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", sans-serif; }
+      .mono { font-family: "JetBrains Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace; }
+      .ttl  { font-weight: 700; }
+      .num  { font-weight: 800; letter-spacing: 0.08em; }
+    </style>
+    <linearGradient id="ig" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%"  stop-color="#5eead4"/>
+      <stop offset="50%" stop-color="#93c5fd"/>
+      <stop offset="100%" stop-color="#c4b5fd"/>
+    </linearGradient>
+  </defs>
+
+  <g transform="translate(10, 10)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">01 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">缓存优先循环</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">只追加历史，不就地修改。字节前缀</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">跨过每一次工具调用都活着 ——</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">命中率持续。</text>
+  </g>
+
+  <g transform="translate(450, 10)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">02 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">R1 思维提取</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">把 reasoning_content 蒸馏成结构化</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">plan state —— 子目标、假设、被否决</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">的路径。留信号，去噪声。</text>
+  </g>
+
+  <g transform="translate(10, 190)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">03 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">工具调用修复</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">Schema 扁平化 · JSON 修复 · &lt;think&gt;</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">内 scavenge · 截断处理。四种策略</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">对付 DeepSeek 专属怪癖。</text>
+  </g>
+
+  <g transform="translate(450, 190)">
+    <rect width="420" height="160" rx="12" ry="12" fill="#0a0c10" stroke="#1e2436"/>
+    <text x="24" y="42" class="mono num" font-size="13" fill="url(#ig)">04 /</text>
+    <text x="24" y="74" class="sans ttl" font-size="20" fill="#e6edf3">成本控制</text>
+    <text x="24" y="106" class="sans" font-size="13" fill="#8b949e">缓存安全 fold · 激进 fold 层 ·</text>
+    <text x="24" y="124" class="sans" font-size="13" fill="#8b949e">模型感知预算。管上下文规模</text>
+    <text x="24" y="142" class="sans" font-size="13" fill="#8b949e">不破坏前缀。</text>
+  </g>
+</svg>

docs/i18n.js

@@ -11,23 +11,27 @@
 
   const translations = {
     en: {
+      "nav.why": "Why",
       "nav.features": "Features",
       "nav.quickstart": "Quick start",
-      "nav.benchmarks": "Benchmarks",
+      "nav.community": "Community",
       "nav.github": "GitHub",
 
-      "hero.badge": "v{version} · DeepSeek V4 · cache-first",
+      "hero.badge": "v{version} · DeepSeek · cache-first · MIT",
       "hero.title.line1": "DeepSeek-native",
       "hero.title.line2": "AI coding agent in your terminal",
       "hero.sub":
-        "Cache-first agent loop for DeepSeek V4 (flash + pro). Edits files as reviewable SEARCH/REPLACE blocks. Ink TUI. MCP first-class. No LangChain.",
+        "Engineered around DeepSeek's prefix-cache so token costs stay low across long sessions. Custom cell-diff renderer. MCP first-class. Open source.",
       "hero.copy": "Copy",
       "hero.copy.done": "Copied",
       "hero.cta.start": "Get started →",
       "hero.cta.star": "Star on GitHub",
-      "hero.stat.cache": "prefix cache hit rate",
-      "hero.stat.cost": "cheaper vs Claude Sonnet 4.6",
-      "hero.stat.pass": "τ-bench-lite pass rate",
+      "hero.stat.cache.num": "Cache-engineered",
+      "hero.stat.cache": "Byte-stable prefix loop",
+      "hero.stat.lic.num": "Open source",
+      "hero.stat.lic": "MIT, community-developed",
+      "hero.stat.tui.num": "Terminal-native",
+      "hero.stat.tui": "Plus embedded dashboard",
 
       "term.user":
         "users.ts findByEmail is case-sensitive — login fails for users with uppercase emails",
@@ -37,25 +41,25 @@
 
       "why.title": "Why Reasonix",
       "why.sub":
-        "Every abstraction earns its weight against a DeepSeek-specific property — dirt-cheap tokens, R1 traces, automatic prefix caching, JSON mode. Generic wrappers leave these on the table.",
+        "The loop is organized around four architectural pillars. Each one solves a problem generic agent frameworks don't even see — because they were designed for a different cache mechanic.",
       "why.cache.title": "Cache-first loop",
       "why.cache.body":
-        "Append-only conversation log keeps the prompt prefix byte-stable across turns, so DeepSeek's automatic cache hits 85–95% — not 40%.",
-      "why.cost.title": "Cost is a pillar",
+        "Append-only history. No in-place mutation, no marker-based compaction. The byte prefix survives every tool call — DeepSeek's prefix-cache keeps hitting turn after turn.",
+      "why.r1.title": "R1 thought harvesting",
+      "why.r1.body":
+        "Distills <code>reasoning_content</code> into a typed plan state — subgoals, hypotheses, uncertainties, rejected paths. Signal kept, noise dropped.",
+      "why.repair.title": "Tool-call repair",
+      "why.repair.body":
+        "Schema flatten · JSON repair · scavenge from <code>&lt;think&gt;</code> · truncation. Four strategies that handle DeepSeek-specific quirks generic loops mistake for model errors.",
+      "why.cost.title": "Cost control",
       "why.cost.body":
-        "Flash-first defaults, turn-end auto-compaction, model self-escalation when (and only when) needed. Per-turn cost badge in the TUI.",
-      "why.tui.title": "Ink TUI, no web",
-      "why.tui.body":
-        "Lives in your terminal. Streaming preview, slash commands, plan picker, edit-confirm modal. Plain mode for stubborn Windows shells.",
-      "why.mcp.title": "MCP first-class",
-      "why.mcp.body":
-        "Stdio + HTTP+SSE transports. Live progress notifications. Same cache-safety + repair plumbing as native tools.",
-      "why.safe.title": "Reviewable edits",
-      "why.safe.body":
-        "Edits arrive as SEARCH/REPLACE blocks; nothing hits disk until /apply. Per-file diff confirm modal, undo history, sandboxed paths.",
-      "why.ctx.title": "1M-token aware",
-      "why.ctx.body":
-        "Context gauge with proactive compaction, oversized tool-result repair, forced-summary fallback near the window edge.",
+        "Cache-safe folding · aggressive-fold tier · summary-on-exit · model-aware budgets. The loop manages context size without breaking prefix stability.",
+      "why.deepseek.title": "DeepSeek-only by design",
+      "why.deepseek.body":
+        "Every layer is tuned around DeepSeek's specific cache mechanic and pricing. Coupling to one backend is the feature, not a limitation.",
+      "why.oss.title": "Open community",
+      "why.oss.body":
+        "MIT licensed and community-developed. Scoped <code>good first issue</code> tickets with code pointers and acceptance criteria. Real PRs from real contributors.",
 
       "qs.title": "Quick start (60 seconds)",
       "qs.step1.title": "Get a DeepSeek API key",
@@ -64,63 +68,91 @@
       "qs.step2.title": "Point it at a project",
       "qs.step2.body": "No install needed.",
       "qs.step2.note":
-        "First run walks you through a 30-second wizard (paste API key → pick preset → pick MCP servers).",
-      "qs.step3.title": "Ask it to edit",
+        "First run walks you through a short wizard — paste API key, pick a preset, optionally attach MCP servers.",
+      "qs.step3.title": "Review and apply",
       "qs.step3.body":
-        "The model proposes edits as SEARCH/REPLACE blocks — nothing hits disk until you <code>/apply</code>.",
+        "The agent proposes edits as reviewable blocks — nothing hits disk until you <code>/apply</code>. Plan mode lets you stage multi-file changes before committing any.",
       "qs.req":
-        "Requires Node ≥ 22. macOS, Linux, Windows (PowerShell · Git Bash · Windows Terminal). Press <kbd>Esc</kbd> anytime to abort; <code>/help</code> for the full command list.",
+        "Requires Node ≥ 22. macOS, Linux, Windows (PowerShell · Git Bash · Windows Terminal). Press <kbd>Esc</kbd> anytime to abort; <code>/help</code> for the full slash-command list.",
 
       "feat.title": "In the box",
-      "feat.code.title": "Pair programmer mode",
-      "feat.code.body":
-        "<code>read_file</code> · <code>write_file</code> · <code>edit_file</code> · <code>search_files</code> · <code>directory_tree</code> · <code>run_command</code> with read-only allowlist. Sandboxed to the launch root — no path escapes. Plan mode and per-edit review modal.",
-      "feat.memory.title": "Two-layer memory",
-      "feat.memory.body":
-        "Committable <code>REASONIX.md</code> for team conventions plus a private per-user <code>~/.reasonix/memory/</code> with global and per-project scopes. The model can write to it via the <code>remember</code> tool.",
-      "feat.skills.title": "User-authored prompt packs",
-      "feat.skills.body":
-        "Drop <code>SKILL.md</code> files anywhere. Names + descriptions are pinned in the prefix; the model picks them autonomously, or you trigger with <code>/skill name</code>.",
-      "feat.hooks.title": "Lifecycle hooks",
-      "feat.hooks.body":
-        "Shell commands fire at <code>PreToolUse</code> · <code>PostToolUse</code> · <code>UserPromptSubmit</code> · <code>Stop</code>. Exit code drives pass / block / warn.",
-      "feat.mcp.title": "Bring your own tools",
+      "feat.sub":
+        "Twelve concrete capabilities. The loop is the foundation; everything below is what you get on top of it.",
+      "feat.renderer.title": "Cell-diff renderer",
+      "feat.renderer.body":
+        "Custom TUI runtime built on Yoga. No Ink dependency. Wide-char, emoji, bracketed paste, and resize handled cleanly across platforms.",
+      "feat.mcp.title": "MCP first-class",
       "feat.mcp.body":
-        'Wizard catalog, or <code>--mcp "name=cmd"</code> to attach stdio / HTTP+SSE servers on the fly. Live progress bars on long calls.',
-      "feat.web.title": "Web search built-in",
-      "feat.web.body":
-        "<code>web_search</code> + <code>web_fetch</code> via Mojeek — no key, no signup, off-by-flag for offline / CI. Bring-your-own provider via the <code>WebSearchProvider</code> interface.",
+        'Stdio and Streamable HTTP transports. Tools, resources, and prompts. In-app browser to inspect any server\'s surface, plus <code>--mcp "name=cmd"</code> on the fly.',
+      "feat.plan.title": "Plan mode",
+      "feat.plan.body":
+        "Review proposed edits before they touch disk. Approve, refine, or reject. Plan checkpoints persist across runs so you can resume mid-review.",
+      "feat.perm.title": "Permissions",
+      "feat.perm.body":
+        "<code>allow</code> · <code>ask</code> · <code>deny</code> per-tool. Granular shell command rules. Interactive prompts you can teach.",
+      "feat.dash.title": "Embedded dashboard",
+      "feat.dash.body":
+        "Companion web view at <code>localhost</code>. Live cache hit rate, cost ticker, session timeline, MCP health — all in one place.",
+      "feat.sess.title": "Persistent sessions",
+      "feat.sess.body":
+        "Per-workspace, named, resumable. <code>--resume</code> picks up exactly where you left off — system prompt, history, plan state.",
+      "feat.hooks.title": "Hooks · skills · memory",
+      "feat.hooks.body":
+        "Shell commands fire on lifecycle events. Drop-in skill packs spawn sub-agents. Project memory the agent reads on every turn.",
+      "feat.search.title": "Semantic search",
+      "feat.search.body":
+        "<code>reasonix index</code> builds an embedding index your agent can query. Local Ollama or DeepSeek-hosted embeddings.",
+      "feat.ckpt.title": "Auto-checkpoints",
+      "feat.ckpt.body":
+        "Cursor-style session-scoped rollback for AI edits. Never pollutes git history; the checkpoint stack is yours alone.",
+      "feat.effort.title": "<code>/effort</code> knob",
+      "feat.effort.body":
+        "Switch reasoning depth per turn. <code>max</code> for the gnarly, <code>low</code> for routine. Slash command and CLI flag.",
+      "feat.replay.title": "Transcript replay",
+      "feat.replay.body":
+        "<code>reasonix replay</code> plays a recorded session back through the renderer — useful for bug reports, demos, and audits.",
+      "feat.events.title": "Event log",
+      "feat.events.body":
+        "<code>events.jsonl</code> sidecar with reducers and a <code>reasonix events</code> CLI. Build dashboards, audits, or your own analytics.",
 
       "bench.title": "Verify the cache claim yourself",
       "bench.sub":
-        "On the same τ-bench-lite workload (8 multi-turn tool-use tasks × 3 repeats = 48 runs per side), live DeepSeek <code>deepseek-chat</code>, sole variable prefix stability:",
-      "bench.col.metric": "metric",
-      "bench.col.baseline": "baseline (cache-hostile)",
-      "bench.col.reasonix": "Reasonix",
-      "bench.col.delta": "delta",
-      "bench.row.cache": "cache hit",
-      "bench.row.cost": "cost / task",
-      "bench.row.pass": "pass rate",
-      "bench.repro.intro": "Reproduce without spending an API credit:",
+        "We don't ship benchmark numbers in marketing copy — they move with model pricing and harness changes, so they live with the harness instead of the README. Reproduce on your own machine:",
       "bench.repro.note":
-        "The committed JSONL transcripts carry per-turn <code>usage</code>, <code>cost</code>, and <code>prefixHash</code>. Reasonix's prefix hash stays byte-stable across every model call.",
+        "Each committed JSONL transcript carries per-turn <code>usage</code>, <code>cost</code>, and <code>prefixHash</code>. Reasonix's prefix hash stays byte-stable across every model call — that's the whole game.",
+      "bench.link": "Read the τ-bench-lite harness →",
 
       "cli.title": "CLI at a glance",
       "cli.code": "coding mode scoped to path",
-      "cli.chat": "chat (uses saved config)",
-      "cli.setup": "reconfigure the wizard",
+      "cli.chat": "interactive chat (saved config)",
       "cli.run": "one-shot, streams to stdout",
-      "cli.stats": "cross-session cost dashboard",
-      "cli.mcp": "probe a single MCP server",
+      "cli.doctor": "environment health check",
+      "cli.replay": "re-render a recorded session",
+      "cli.diff": "compare two transcripts",
+      "cli.events": "query the event log",
+      "cli.stats": "cross-session usage",
+      "cli.index": "build semantic embedding index",
+      "cli.mcp": "probe one MCP server",
+      "cli.mcplist": "list configured MCP servers",
+      "cli.prune": "clean up old sessions",
       "cli.flags.intro": "Common flags:",
-      "cli.f.preset": "model + harvest + branch bundle",
+      "cli.f.effort": "reasoning depth for the run",
       "cli.f.model": "explicit DeepSeek model id",
       "cli.f.mcp": "attach an MCP server (repeatable)",
       "cli.f.session": "named session",
+      "cli.f.resume": "pick up the latest session for this workspace",
+      "cli.f.new": "force a fresh session, preserve old",
       "cli.f.noconf": "ignore ~/.reasonix/config.json (CI)",
 
+      "comm.title": "Built by the community",
+      "comm.sub":
+        "Reasonix is open source and community-developed. Every avatar on the wall below is a real PR that shipped — not a sponsorship slot.",
+      "comm.gfi": "good first issue →",
+      "comm.disc": "Discussions",
+      "comm.contrib": "Contributing guide",
+
       "ctab.title": "Ready to try?",
-      "ctab.sub": "One <code>npx</code> away. Sandboxed. Reviewable. 98% cheaper.",
+      "ctab.sub": "One <code>npx</code> away. Sandboxed. Reviewable. Open source.",
       "ctab.gh": "GitHub repository →",
       "ctab.npm": "npm package",
 
@@ -128,33 +160,39 @@
       "foot.col.project": "Project",
       "foot.col.docs": "Docs",
       "foot.col.community": "Community",
-      "foot.changelog": "Changelog",
+      "foot.releases": "Releases",
       "foot.readme": "README",
       "foot.readme.zh": "中文 README",
       "foot.arch": "Architecture",
+      "foot.bench": "Benchmarks",
       "foot.issues": "Issues",
       "foot.discuss": "Discussions",
+      "foot.contributors": "Contributors",
       "foot.copyright": "© 2026 Reasonix · MIT License",
     },
 
     zh: {
+      "nav.why": "为什么",
       "nav.features": "特性",
       "nav.quickstart": "快速上手",
-      "nav.benchmarks": "性能对比",
+      "nav.community": "社区",
       "nav.github": "GitHub",
 
-      "hero.badge": "v{version} · DeepSeek V4 · 缓存优先",
+      "hero.badge": "v{version} · DeepSeek · 缓存优先 · MIT",
       "hero.title.line1": "DeepSeek 原生",
       "hero.title.line2": "终端里的 AI 编程代理",
       "hero.sub":
-        "为 DeepSeek V4（flash + pro）打造的缓存优先 agent 循环。编辑以可审查的 SEARCH/REPLACE 块呈现，落盘前必须确认。Ink TUI、原生支持 MCP，不依赖 LangChain。",
+        "围绕 DeepSeek 前缀缓存设计，长会话下 token 成本始终维持在低位。自研 cell-diff 渲染器，MCP 一等公民，完全开源。",
       "hero.copy": "复制",
       "hero.copy.done": "已复制",
       "hero.cta.start": "开始使用 →",
       "hero.cta.star": "在 GitHub 加星",
-      "hero.stat.cache": "前缀缓存命中率",
-      "hero.stat.cost": "相比 Claude Sonnet 4.6 节省",
-      "hero.stat.pass": "τ-bench-lite 通过率",
+      "hero.stat.cache.num": "缓存工程化",
+      "hero.stat.cache": "字节稳定的前缀循环",
+      "hero.stat.lic.num": "开源",
+      "hero.stat.lic": "MIT 协议，社区共建",
+      "hero.stat.tui.num": "终端原生",
+      "hero.stat.tui": "外加内嵌仪表盘",
 
       "term.user":
         "users.ts 里 findByEmail 对大小写敏感导致登录失败，帮我改",
@@ -164,25 +202,25 @@
 
       "why.title": "为什么选 Reasonix",
       "why.sub":
-        "每个抽象都对应 DeepSeek 的一个具体特性——极低 token 价、R1 推理轨迹、自动前缀缓存、JSON 模式。通用框架把这些机会全留在桌上。",
-      "why.cache.title": "缓存优先的循环",
+        "整个循环围绕四根架构支柱组织。每一根解决的都是通用 agent 框架根本看不见的问题——因为它们是为另一种缓存机制设计的。",
+      "why.cache.title": "缓存优先循环",
       "why.cache.body":
-        "对话日志只追加不重写，前缀字节级稳定，DeepSeek 的自动前缀缓存命中能稳定打到 85–95%，而不是 40%。",
-      "why.cost.title": "成本是头等公民",
+        "只追加历史。不就地修改，不依赖标记的 compaction。字节前缀跨过每一次工具调用都活着——DeepSeek 的前缀缓存一轮一轮持续命中。",
+      "why.r1.title": "R1 思维提取",
+      "why.r1.body":
+        "把 <code>reasoning_content</code> 蒸馏成结构化 plan state——子目标、假设、不确定性、被否决的路径。留信号，去噪声。",
+      "why.repair.title": "工具调用修复",
+      "why.repair.body":
+        "Schema 扁平化 · JSON 修复 · <code>&lt;think&gt;</code> 内 scavenge · 截断处理。四种策略对付 DeepSeek 专属怪癖——通用循环会把这些当模型错误。",
+      "why.cost.title": "成本控制",
       "why.cost.body":
-        "默认 flash 优先、turn 末尾自动压缩、必要时模型自我升级到 pro。TUI 有实时单轮成本徽章。",
-      "why.tui.title": "Ink TUI，不靠浏览器",
-      "why.tui.body":
-        "完全在终端里。流式预览、斜杠命令、计划审阅、编辑确认弹窗。Windows 顽固终端可启用 plain 模式。",
-      "why.mcp.title": "原生 MCP",
-      "why.mcp.body":
-        "stdio + HTTP+SSE 双传输。长任务有实时进度条。和原生工具一样走缓存安全 + 自动修复管线。",
-      "why.safe.title": "编辑可审阅",
-      "why.safe.body":
-        "编辑以 SEARCH/REPLACE 块呈现，/apply 之前不动磁盘。逐文件 diff 确认、撤销历史、路径沙箱。",
-      "why.ctx.title": "百万 token 感知",
-      "why.ctx.body":
-        "上下文仪表 + 主动压缩、超大工具结果自动修复、贴近上限自动总结兜底。",
+        "缓存安全 fold · 激进 fold 层 · 退出时摘要 · 模型感知预算。循环管理上下文规模时不破坏前缀稳定。",
+      "why.deepseek.title": "故意只做 DeepSeek",
+      "why.deepseek.body":
+        "每一层都为 DeepSeek 特定的缓存机制和定价调过。绑死一个后端是 feature，不是限制。",
+      "why.oss.title": "开放社区",
+      "why.oss.body":
+        "MIT 协议，社区共建。<code>good first issue</code> 入门 issue 都带代码定位和验收标准。真实贡献者的真实 PR。",
 
       "qs.title": "60 秒快速上手",
       "qs.step1.title": "获取 DeepSeek API Key",
@@ -191,63 +229,91 @@
       "qs.step2.title": "切到项目目录运行",
       "qs.step2.body": "无需安装。",
       "qs.step2.note":
-        "首次运行会走 30 秒向导：粘贴 API key → 选预设 → 勾选 MCP 服务器。",
-      "qs.step3.title": "让它改代码",
+        "首次运行会走一个短向导：粘贴 API key、选预设、可选挂载 MCP 服务器。",
+      "qs.step3.title": "审阅再应用",
       "qs.step3.body":
-        "模型会以 SEARCH/REPLACE 块的形式提出编辑——你不 <code>/apply</code>，磁盘不会被改。",
+        "代理会把改动以可审阅的块呈现——你不 <code>/apply</code>，磁盘不会被改。Plan 模式可以让你先把多文件改动整理好，再统一落盘。",
       "qs.req":
-        "需要 Node ≥ 22。支持 macOS、Linux、Windows（PowerShell · Git Bash · Windows Terminal）。任何时候按 <kbd>Esc</kbd> 中断；<code>/help</code> 查看完整命令。",
+        "需要 Node ≥ 22。支持 macOS、Linux、Windows（PowerShell · Git Bash · Windows Terminal）。任何时候按 <kbd>Esc</kbd> 中断；<code>/help</code> 查看完整斜杠命令。",
 
       "feat.title": "开箱即用",
-      "feat.code.title": "结对编程模式",
-      "feat.code.body":
-        "<code>read_file</code> · <code>write_file</code> · <code>edit_file</code> · <code>search_files</code> · <code>directory_tree</code> · 带只读白名单的 <code>run_command</code>。沙箱限定在启动目录——路径逃逸一律拒绝。支持 plan 模式与逐次编辑确认弹窗。",
-      "feat.memory.title": "两层记忆系统",
-      "feat.memory.body":
-        "可提交的 <code>REASONIX.md</code> 承载团队约定，私人 <code>~/.reasonix/memory/</code> 分全局与按项目两个作用域。模型可通过 <code>remember</code> 工具自行写入。",
-      "feat.skills.title": "用户定义的 prompt 包",
-      "feat.skills.body":
-        "把 <code>SKILL.md</code> 丢进任意位置。名字 + 描述会被钉在前缀里，模型可自动调用，或你用 <code>/skill name</code> 手动触发。",
-      "feat.hooks.title": "生命周期钩子",
-      "feat.hooks.body":
-        "在 <code>PreToolUse</code> · <code>PostToolUse</code> · <code>UserPromptSubmit</code> · <code>Stop</code> 四个点触发 shell 命令，退出码决定放行 / 阻断 / 警告。",
-      "feat.mcp.title": "自带工具进来",
+      "feat.sub":
+        "12 个具体能力。循环是地基，下面是地基之上你能直接拿来用的东西。",
+      "feat.renderer.title": "自研 cell-diff 渲染器",
+      "feat.renderer.body":
+        "基于 Yoga 的 TUI 运行时，不依赖 Ink。宽字符、emoji、bracketed paste、resize 跨平台都干净。",
+      "feat.mcp.title": "MCP 一等公民",
       "feat.mcp.body":
-        '向导内置目录，或用 <code>--mcp "name=cmd"</code> 直接挂 stdio / HTTP+SSE 服务器。长任务渲染实时进度条。',
-      "feat.web.title": "内置联网搜索",
-      "feat.web.body":
-        "<code>web_search</code> + <code>web_fetch</code>，背靠 Mojeek——无需 key、无需注册，离线 / CI 可关闭。可通过 <code>WebSearchProvider</code> 接口接入自家搜索。",
+        'stdio 与 Streamable HTTP 双传输。工具、资源、提示词全套。内置浏览器查看任意服务器的接口，也能用 <code>--mcp "name=cmd"</code> 现挂。',
+      "feat.plan.title": "计划模式",
+      "feat.plan.body":
+        "改动落盘前先 review。批准、调整、拒绝。Plan checkpoint 跨运行持久化，中途中断也能续。",
+      "feat.perm.title": "权限系统",
+      "feat.perm.body":
+        "每个工具 <code>allow</code> · <code>ask</code> · <code>deny</code>。shell 命令粒度规则。交互式提示，可以教它。",
+      "feat.dash.title": "内嵌仪表盘",
+      "feat.dash.body":
+        "<code>localhost</code> 的伴生 web 面板。实时缓存命中、成本计数、会话时间线、MCP 健康，一处看全。",
+      "feat.sess.title": "持久化会话",
+      "feat.sess.body":
+        "按工作区组织，命名、可恢复。<code>--resume</code> 完全还原——系统提示、历史、plan state。",
+      "feat.hooks.title": "Hooks · Skills · Memory",
+      "feat.hooks.body":
+        "生命周期事件触发 shell 命令。drop-in 的 skill 包能拉子代理。每回合自动读入的项目级 memory。",
+      "feat.search.title": "语义检索",
+      "feat.search.body":
+        "<code>reasonix index</code> 构建 embedding 索引供 agent 查询。本地 Ollama 或 DeepSeek 托管 embedding 任选。",
+      "feat.ckpt.title": "自动 checkpoint",
+      "feat.ckpt.body":
+        "Cursor 风格的会话级 AI 编辑回滚。不污染 git 历史；checkpoint 栈完全是你自己的。",
+      "feat.effort.title": "<code>/effort</code> 旋钮",
+      "feat.effort.body":
+        "每回合切换 reasoning 深度。难活 <code>max</code>、日常 <code>low</code>。斜杠命令 + CLI flag 双入口。",
+      "feat.replay.title": "Transcript 重放",
+      "feat.replay.body":
+        "<code>reasonix replay</code> 把录制好的会话用渲染器重放一遍——bug 复现、演示、审计都好用。",
+      "feat.events.title": "事件日志",
+      "feat.events.body":
+        "<code>events.jsonl</code> 旁路日志，附带 reducer 和 <code>reasonix events</code> CLI。自己搭仪表盘、审计、分析都行。",
 
-      "bench.title": "缓存命中率自己也能验证",
+      "bench.title": "缓存命中自己也能验证",
       "bench.sub":
-        "同一 τ-bench-lite 负载（8 个多轮工具调用任务 × 3 次重复 = 每边 48 次运行），实测 DeepSeek <code>deepseek-chat</code>，唯一变量是前缀稳定性：",
-      "bench.col.metric": "指标",
-      "bench.col.baseline": "基线（缓存敌对）",
-      "bench.col.reasonix": "Reasonix",
-      "bench.col.delta": "差值",
-      "bench.row.cache": "缓存命中",
-      "bench.row.cost": "单任务成本",
-      "bench.row.pass": "通过率",
-      "bench.repro.intro": "无需消耗 API 额度即可复现：",
+        "营销文案里我们不放具体 benchmark 数字——这些数会随模型定价和测试集变化，所以归在 harness 里，不进 README。在自己机器上复现：",
       "bench.repro.note":
-        "提交进仓库的 JSONL 文件每轮带 <code>usage</code>、<code>cost</code>、<code>prefixHash</code>。Reasonix 的前缀哈希在每次模型调用时都字节稳定。",
+        "提交进仓库的每个 JSONL transcript 都带逐轮 <code>usage</code>、<code>cost</code> 和 <code>prefixHash</code>。Reasonix 的前缀哈希在每次模型调用中都字节稳定——这就是全部把戏。",
+      "bench.link": "查看 τ-bench-lite harness →",
 
       "cli.title": "CLI 速览",
       "cli.code": "针对指定路径的编程模式",
-      "cli.chat": "聊天模式（读取已保存配置）",
-      "cli.setup": "重新跑配置向导",
+      "cli.chat": "交互式聊天（读取已保存配置）",
       "cli.run": "一次性运行，结果流到 stdout",
-      "cli.stats": "跨会话的成本仪表盘",
+      "cli.doctor": "环境健康检查",
+      "cli.replay": "重渲染一段录制的会话",
+      "cli.diff": "比较两段 transcript",
+      "cli.events": "查询事件日志",
+      "cli.stats": "跨会话用量统计",
+      "cli.index": "构建语义 embedding 索引",
       "cli.mcp": "探测单个 MCP 服务器",
+      "cli.mcplist": "列出已配置的 MCP 服务器",
+      "cli.prune": "清理旧会话",
       "cli.flags.intro": "常用 flag：",
-      "cli.f.preset": "模型 + harvest + 分支并行 一键组合",
+      "cli.f.effort": "本次运行的 reasoning 深度",
       "cli.f.model": "显式指定 DeepSeek 模型 ID",
       "cli.f.mcp": "挂载 MCP 服务器（可重复）",
       "cli.f.session": "命名会话",
+      "cli.f.resume": "恢复本工作区的最近一个会话",
+      "cli.f.new": "强制开新会话，旧会话保留",
       "cli.f.noconf": "忽略 ~/.reasonix/config.json（CI 友好）",
 
+      "comm.title": "由社区共建",
+      "comm.sub":
+        "Reasonix 是开源、社区共建的项目。下面墙上每一个头像都对应一次真实合并的 PR——不是赞助位。",
+      "comm.gfi": "good first issue →",
+      "comm.disc": "Discussions",
+      "comm.contrib": "贡献指南",
+
       "ctab.title": "准备好了吗？",
-      "ctab.sub": "一条 <code>npx</code> 即可开始。沙箱、可审阅、便宜 98%。",
+      "ctab.sub": "一条 <code>npx</code> 即可开始。沙箱、可审阅、完全开源。",
       "ctab.gh": "GitHub 仓库 →",
       "ctab.npm": "npm 包",
 
@@ -255,12 +321,14 @@
       "foot.col.project": "项目",
       "foot.col.docs": "文档",
       "foot.col.community": "社区",
-      "foot.changelog": "更新日志",
+      "foot.releases": "Releases",
       "foot.readme": "英文 README",
       "foot.readme.zh": "中文 README",
       "foot.arch": "架构文档",
+      "foot.bench": "Benchmarks",
       "foot.issues": "问题反馈",
       "foot.discuss": "讨论区",
+      "foot.contributors": "贡献者",
       "foot.copyright": "© 2026 Reasonix · MIT 协议",
     },
   };
@@ -312,7 +380,7 @@
   // visits the site for the first time. Bumping it occasionally on
   // major version cuts is fine; the npm fetch handles everything else.
   const VERSION_STORAGE_KEY = "reasonix.version";
-  const VERSION_FALLBACK = "0.16";
+  const VERSION_FALLBACK = "0.26";
   const versionListeners = [];
   let currentVersion = VERSION_FALLBACK;
 

docs/index.html

@@ -6,14 +6,14 @@
     <title>Reasonix — DeepSeek-native AI coding agent</title>
     <meta
       name="description"
-      content="Cache-first agent loop for DeepSeek V4. Ink TUI. MCP first-class. 90%+ prefix cache hit, ~98% cheaper than Claude on the same workload. No LangChain."
+      content="Open-source AI coding agent for your terminal, engineered around DeepSeek's prefix-cache so token costs stay low across long sessions. MCP first-class · plan mode · custom cell-diff renderer."
     />
     <meta name="theme-color" content="#0b0f17" />
 
     <meta property="og:title" content="Reasonix — DeepSeek-native AI coding agent" />
     <meta
       property="og:description"
-      content="Cache-first agent loop for DeepSeek V4 (flash + pro). Ink TUI. MCP first-class. No LangChain."
+      content="Open-source AI coding agent for your terminal. Engineered around DeepSeek's prefix-cache. MCP first-class · plan mode · embedded dashboard · MIT."
     />
     <meta property="og:type" content="website" />
     <meta property="og:url" content="https://esengine.github.io/reasonix/" />
@@ -44,9 +44,10 @@
       </a>
 
       <nav class="nav-links">
+        <a href="#why" data-i18n="nav.why">Why</a>
         <a href="#features" data-i18n="nav.features">Features</a>
         <a href="#quickstart" data-i18n="nav.quickstart">Quick start</a>
-        <a href="#benchmarks" data-i18n="nav.benchmarks">Benchmarks</a>
+        <a href="#community" data-i18n="nav.community">Community</a>
         <a
           href="https://github.com/esengine/reasonix"
           target="_blank"
@@ -67,15 +68,15 @@
     <main id="top">
       <section class="hero">
         <div class="hero-inner">
-          <div class="badge" data-i18n="hero.badge">v0.16 · DeepSeek V4 · cache-first</div>
+          <div class="badge" data-i18n="hero.badge">v{version} · DeepSeek · cache-first · MIT</div>
           <h1 class="hero-title">
             <span class="grad-text" data-i18n="hero.title.line1">DeepSeek-native</span>
             <br />
             <span data-i18n="hero.title.line2">AI coding agent in your terminal</span>
           </h1>
           <p class="hero-sub" data-i18n="hero.sub">
-            Cache-first agent loop for DeepSeek V4 (flash + pro). Edits files as
-            reviewable SEARCH/REPLACE blocks. Ink TUI. MCP first-class. No LangChain.
+            Engineered around DeepSeek's prefix-cache so token costs stay low across long
+            sessions. Custom cell-diff renderer. MCP first-class. Open source.
           </p>
 
           <div class="hero-install">
@@ -103,16 +104,16 @@
 
           <div class="hero-stats">
             <div class="stat">
-              <div class="stat-num grad-text">90.2%</div>
-              <div class="stat-label" data-i18n="hero.stat.cache">prefix cache hit rate</div>
+              <div class="stat-num grad-text" data-i18n="hero.stat.cache.num">Cache-engineered</div>
+              <div class="stat-label" data-i18n="hero.stat.cache">Byte-stable prefix loop</div>
             </div>
             <div class="stat">
-              <div class="stat-num grad-text">~98%</div>
-              <div class="stat-label" data-i18n="hero.stat.cost">cheaper vs Claude Sonnet 4.6</div>
+              <div class="stat-num grad-text" data-i18n="hero.stat.lic.num">Open source</div>
+              <div class="stat-label" data-i18n="hero.stat.lic">MIT, community-developed</div>
             </div>
             <div class="stat">
-              <div class="stat-num grad-text">100%</div>
-              <div class="stat-label" data-i18n="hero.stat.pass">τ-bench-lite pass rate</div>
+              <div class="stat-num grad-text" data-i18n="hero.stat.tui.num">Terminal-native</div>
+              <div class="stat-label" data-i18n="hero.stat.tui">Plus embedded dashboard</div>
             </div>
           </div>
         </div>
@@ -127,13 +128,13 @@
         </div>
       </section>
 
-      <section class="why">
+      <section id="why" class="why">
         <div class="container">
           <h2 class="section-title" data-i18n="why.title">Why Reasonix</h2>
           <p class="section-sub" data-i18n="why.sub">
-            Every abstraction earns its weight against a DeepSeek-specific property —
-            dirt-cheap tokens, R1 traces, automatic prefix caching, JSON mode. Generic
-            wrappers leave these on the table.
+            The loop is organized around four architectural pillars. Each one solves a
+            problem generic agent frameworks don't even see — because they were designed
+            for a different cache mechanic.
           </p>
 
           <div class="why-grid">
@@ -141,48 +142,51 @@
               <div class="why-icon">◈</div>
               <h3 data-i18n="why.cache.title">Cache-first loop</h3>
               <p data-i18n="why.cache.body">
-                Append-only conversation log keeps the prompt prefix byte-stable across
-                turns, so DeepSeek's automatic cache hits 85–95% — not 40%.
+                Append-only history. No in-place mutation, no marker-based compaction.
+                The byte prefix survives every tool call — DeepSeek's prefix-cache keeps
+                hitting turn after turn.
+              </p>
+            </article>
+            <article class="why-card">
+              <div class="why-icon">⌥</div>
+              <h3 data-i18n="why.r1.title">R1 thought harvesting</h3>
+              <p data-i18n="why.r1.body">
+                Distills <code>reasoning_content</code> into a typed plan state — subgoals,
+                hypotheses, uncertainties, rejected paths. Signal kept, noise dropped.
+              </p>
+            </article>
+            <article class="why-card">
+              <div class="why-icon">⚒</div>
+              <h3 data-i18n="why.repair.title">Tool-call repair</h3>
+              <p data-i18n="why.repair.body">
+                Schema flatten · JSON repair · scavenge from <code>&lt;think&gt;</code> ·
+                truncation. Four strategies that handle DeepSeek-specific quirks generic
+                loops mistake for model errors.
               </p>
             </article>
             <article class="why-card">
               <div class="why-icon">¥</div>
-              <h3 data-i18n="why.cost.title">Cost is a pillar</h3>
+              <h3 data-i18n="why.cost.title">Cost control</h3>
               <p data-i18n="why.cost.body">
-                Flash-first defaults, turn-end auto-compaction, model self-escalation
-                when (and only when) needed. Per-turn cost badge in the TUI.
+                Cache-safe folding · aggressive-fold tier · summary-on-exit · model-aware
+                budgets. The loop manages context size without breaking prefix stability.
               </p>
             </article>
             <article class="why-card">
-              <div class="why-icon">⌨</div>
-              <h3 data-i18n="why.tui.title">Ink TUI, no web</h3>
-              <p data-i18n="why.tui.body">
-                Lives in your terminal. Streaming preview, slash commands, plan picker,
-                edit-confirm modal. Plain mode for stubborn Windows shells.
+              <div class="why-icon">∂</div>
+              <h3 data-i18n="why.deepseek.title">DeepSeek-only by design</h3>
+              <p data-i18n="why.deepseek.body">
+                Every layer is tuned around DeepSeek's specific cache mechanic and pricing.
+                Coupling to one backend is the feature, not a limitation.
               </p>
             </article>
             <article class="why-card">
-              <div class="why-icon">⊕</div>
-              <h3 data-i18n="why.mcp.title">MCP first-class</h3>
-              <p data-i18n="why.mcp.body">
-                Stdio + HTTP+SSE transports. Live progress notifications. Same
-                cache-safety + repair plumbing as native tools.
-              </p>
-            </article>
-            <article class="why-card">
-              <div class="why-icon">↶</div>
-              <h3 data-i18n="why.safe.title">Reviewable edits</h3>
-              <p data-i18n="why.safe.body">
-                Edits arrive as SEARCH/REPLACE blocks; nothing hits disk until /apply.
-                Per-file diff confirm modal, undo history, sandboxed paths.
-              </p>
-            </article>
-            <article class="why-card">
-              <div class="why-icon">∞</div>
-              <h3 data-i18n="why.ctx.title">1M-token aware</h3>
-              <p data-i18n="why.ctx.body">
-                Context gauge with proactive compaction, oversized tool-result repair,
-                forced-summary fallback near the window edge.
+              <div class="why-icon">⊜</div>
+              <h3 data-i18n="why.oss.title">Open community</h3>
+              <p data-i18n="why.oss.body">
+                MIT licensed and community-developed. Scoped <code>good first issue</code>
+                tickets with code pointers and acceptance criteria. Real PRs from real
+                contributors.
               </p>
             </article>
           </div>
@@ -209,15 +213,16 @@
               <pre class="code"><code>cd my-project
 npx reasonix code</code></pre>
               <p data-i18n="qs.step2.note">
-                First run walks you through a 30-second wizard (paste API key → pick
-                preset → pick MCP servers).
+                First run walks you through a short wizard — paste API key, pick a
+                preset, optionally attach MCP servers.
               </p>
             </li>
             <li>
-              <h3 data-i18n="qs.step3.title">Ask it to edit</h3>
+              <h3 data-i18n="qs.step3.title">Review and apply</h3>
               <p data-i18n="qs.step3.body">
-                The model proposes edits as SEARCH/REPLACE blocks — nothing hits disk
-                until you <code>/apply</code>.
+                The agent proposes edits as reviewable blocks — nothing hits disk until
+                you <code>/apply</code>. Plan mode lets you stage multi-file changes
+                before committing any.
               </p>
             </li>
           </ol>
@@ -225,7 +230,7 @@ npx reasonix code</code></pre>
           <p class="req" data-i18n="qs.req">
             Requires Node ≥ 22. macOS, Linux, Windows (PowerShell · Git Bash · Windows
             Terminal). Press <kbd>Esc</kbd> anytime to abort; <code>/help</code> for the
-            full command list.
+            full slash-command list.
           </p>
         </div>
       </section>
@@ -233,121 +238,147 @@ npx reasonix code</code></pre>
       <section id="features" class="features">
         <div class="container">
           <h2 class="section-title" data-i18n="feat.title">In the box</h2>
+          <p class="section-sub" data-i18n="feat.sub">
+            Twelve concrete capabilities. The loop is the foundation; everything below
+            is what you get on top of it.
+          </p>
 
           <div class="feat-grid">
             <article class="feat">
               <h3>
-                <span class="feat-tag">code</span>
-                <span data-i18n="feat.code.title">Pair programmer mode</span>
+                <span class="feat-tag">renderer</span>
+                <span data-i18n="feat.renderer.title">Cell-diff renderer</span>
               </h3>
-              <p data-i18n="feat.code.body">
-                <code>read_file</code> · <code>write_file</code> · <code>edit_file</code> ·
-                <code>search_files</code> · <code>directory_tree</code> ·
-                <code>run_command</code> with read-only allowlist. Sandboxed to the
-                launch root — no path escapes. Plan mode and per-edit review modal.
-              </p>
-            </article>
-            <article class="feat">
-              <h3>
-                <span class="feat-tag">memory</span>
-                <span data-i18n="feat.memory.title">Two-layer memory</span>
-              </h3>
-              <p data-i18n="feat.memory.body">
-                Committable <code>REASONIX.md</code> for team conventions plus a private
-                per-user <code>~/.reasonix/memory/</code> with global and per-project
-                scopes. The model can write to it via the <code>remember</code> tool.
-              </p>
-            </article>
-            <article class="feat">
-              <h3>
-                <span class="feat-tag">skills</span>
-                <span data-i18n="feat.skills.title">User-authored prompt packs</span>
-              </h3>
-              <p data-i18n="feat.skills.body">
-                Drop <code>SKILL.md</code> files anywhere. Names + descriptions are
-                pinned in the prefix; the model picks them autonomously, or you trigger
-                with <code>/skill name</code>.
-              </p>
-            </article>
-            <article class="feat">
-              <h3>
-                <span class="feat-tag">hooks</span>
-                <span data-i18n="feat.hooks.title">Lifecycle hooks</span>
-              </h3>
-              <p data-i18n="feat.hooks.body">
-                Shell commands fire at <code>PreToolUse</code> · <code>PostToolUse</code>
-                · <code>UserPromptSubmit</code> · <code>Stop</code>. Exit code drives
-                pass / block / warn.
+              <p data-i18n="feat.renderer.body">
+                Custom TUI runtime built on Yoga. No Ink dependency. Wide-char, emoji,
+                bracketed paste, and resize handled cleanly across platforms.
               </p>
             </article>
             <article class="feat">
               <h3>
                 <span class="feat-tag">mcp</span>
-                <span data-i18n="feat.mcp.title">Bring your own tools</span>
+                <span data-i18n="feat.mcp.title">MCP first-class</span>
               </h3>
               <p data-i18n="feat.mcp.body">
-                Wizard catalog, or <code>--mcp "name=cmd"</code> to attach stdio /
-                HTTP+SSE servers on the fly. Live progress bars on long calls.
+                Stdio and Streamable HTTP transports. Tools, resources, and prompts.
+                In-app browser to inspect any server's surface, plus
+                <code>--mcp "name=cmd"</code> on the fly.
               </p>
             </article>
             <article class="feat">
               <h3>
-                <span class="feat-tag">web</span>
-                <span data-i18n="feat.web.title">Web search built-in</span>
+                <span class="feat-tag">plan</span>
+                <span data-i18n="feat.plan.title">Plan mode</span>
               </h3>
-              <p data-i18n="feat.web.body">
-                <code>web_search</code> + <code>web_fetch</code> via Mojeek — no key, no
-                signup, off-by-flag for offline / CI. Bring-your-own provider via the
-                <code>WebSearchProvider</code> interface.
+              <p data-i18n="feat.plan.body">
+                Review proposed edits before they touch disk. Approve, refine, or reject.
+                Plan checkpoints persist across runs so you can resume mid-review.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">perms</span>
+                <span data-i18n="feat.perm.title">Permissions</span>
+              </h3>
+              <p data-i18n="feat.perm.body">
+                <code>allow</code> · <code>ask</code> · <code>deny</code> per-tool.
+                Granular shell command rules. Interactive prompts you can teach.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">dashboard</span>
+                <span data-i18n="feat.dash.title">Embedded dashboard</span>
+              </h3>
+              <p data-i18n="feat.dash.body">
+                Companion web view at <code>localhost</code>. Live cache hit rate, cost
+                ticker, session timeline, MCP health — all in one place.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">sessions</span>
+                <span data-i18n="feat.sess.title">Persistent sessions</span>
+              </h3>
+              <p data-i18n="feat.sess.body">
+                Per-workspace, named, resumable. <code>--resume</code> picks up exactly
+                where you left off — system prompt, history, plan state.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">hooks</span>
+                <span data-i18n="feat.hooks.title">Hooks · skills · memory</span>
+              </h3>
+              <p data-i18n="feat.hooks.body">
+                Shell commands fire on lifecycle events. Drop-in skill packs spawn
+                sub-agents. Project memory the agent reads on every turn.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">search</span>
+                <span data-i18n="feat.search.title">Semantic search</span>
+              </h3>
+              <p data-i18n="feat.search.body">
+                <code>reasonix index</code> builds an embedding index your agent can
+                query. Local Ollama or DeepSeek-hosted embeddings.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">checkpoint</span>
+                <span data-i18n="feat.ckpt.title">Auto-checkpoints</span>
+              </h3>
+              <p data-i18n="feat.ckpt.body">
+                Cursor-style session-scoped rollback for AI edits. Never pollutes git
+                history; the checkpoint stack is yours alone.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">effort</span>
+                <span data-i18n="feat.effort.title"><code>/effort</code> knob</span>
+              </h3>
+              <p data-i18n="feat.effort.body">
+                Switch reasoning depth per turn. <code>max</code> for the gnarly,
+                <code>low</code> for routine. Slash command and CLI flag.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">replay</span>
+                <span data-i18n="feat.replay.title">Transcript replay</span>
+              </h3>
+              <p data-i18n="feat.replay.body">
+                <code>reasonix replay</code> plays a recorded session back through the
+                renderer — useful for bug reports, demos, and audits.
+              </p>
+            </article>
+            <article class="feat">
+              <h3>
+                <span class="feat-tag">events</span>
+                <span data-i18n="feat.events.title">Event log</span>
+              </h3>
+              <p data-i18n="feat.events.body">
+                <code>events.jsonl</code> sidecar with reducers and a
+                <code>reasonix events</code> CLI. Build dashboards, audits, or your own
+                analytics.
               </p>
             </article>
           </div>
         </div>
       </section>
 
-      <section id="benchmarks" class="bench">
+      <section class="bench">
         <div class="container">
           <h2 class="section-title" data-i18n="bench.title">Verify the cache claim yourself</h2>
           <p class="section-sub" data-i18n="bench.sub">
-            On the same τ-bench-lite workload (8 multi-turn tool-use tasks × 3 repeats =
-            48 runs per side), live DeepSeek <code>deepseek-chat</code>, sole variable
-            prefix stability:
+            We don't ship benchmark numbers in marketing copy — they move with model
+            pricing and harness changes, so they live with the harness instead of the
+            README. Reproduce on your own machine:
           </p>
 
-          <div class="bench-table-wrap">
-            <table class="bench-table">
-              <thead>
-                <tr>
-                  <th data-i18n="bench.col.metric">metric</th>
-                  <th data-i18n="bench.col.baseline">baseline (cache-hostile)</th>
-                  <th data-i18n="bench.col.reasonix">Reasonix</th>
-                  <th data-i18n="bench.col.delta">delta</th>
-                </tr>
-              </thead>
-              <tbody>
-                <tr>
-                  <td data-i18n="bench.row.cache">cache hit</td>
-                  <td>32.8%</td>
-                  <td class="hi">90.2%</td>
-                  <td>+57.4 pp</td>
-                </tr>
-                <tr>
-                  <td data-i18n="bench.row.cost">cost / task</td>
-                  <td>$0.000992</td>
-                  <td class="hi">$0.000593</td>
-                  <td><strong>−40%</strong></td>
-                </tr>
-                <tr>
-                  <td data-i18n="bench.row.pass">pass rate</td>
-                  <td>100% (24/24)</td>
-                  <td class="hi">100% (24/24)</td>
-                  <td>—</td>
-                </tr>
-              </tbody>
-            </table>
-          </div>
-
-          <p data-i18n="bench.repro.intro">Reproduce without spending an API credit:</p>
           <pre class="code"><code>git clone https://github.com/esengine/reasonix.git &amp;&amp; cd reasonix &amp;&amp; npm install
 npx reasonix replay benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl
 npx reasonix diff \
@@ -355,9 +386,19 @@ npx reasonix diff \
   benchmarks/tau-bench/transcripts/t01_address_happy.reasonix.r1.jsonl</code></pre>
 
           <p data-i18n="bench.repro.note">
-            The committed JSONL transcripts carry per-turn <code>usage</code>,
+            Each committed JSONL transcript carries per-turn <code>usage</code>,
             <code>cost</code>, and <code>prefixHash</code>. Reasonix's prefix hash stays
-            byte-stable across every model call.
+            byte-stable across every model call — that's the whole game.
+          </p>
+          <p>
+            <a
+              class="cta ghost"
+              href="https://github.com/esengine/reasonix/tree/main/benchmarks"
+              target="_blank"
+              rel="noopener"
+              data-i18n="bench.link"
+              >Read the τ-bench-lite harness →</a
+            >
           </p>
         </div>
       </section>
@@ -366,18 +407,77 @@ npx reasonix diff \
         <div class="container">
           <h2 class="section-title" data-i18n="cli.title">CLI at a glance</h2>
           <pre class="code"><code>npx reasonix code [path]                 <span class="hash"># <span data-i18n="cli.code">coding mode scoped to path</span></span>
-npx reasonix                             <span class="hash"># <span data-i18n="cli.chat">chat (uses saved config)</span></span>
-npx reasonix setup                       <span class="hash"># <span data-i18n="cli.setup">reconfigure the wizard</span></span>
+npx reasonix chat                        <span class="hash"># <span data-i18n="cli.chat">interactive chat (saved config)</span></span>
 npx reasonix run "ask anything"          <span class="hash"># <span data-i18n="cli.run">one-shot, streams to stdout</span></span>
-npx reasonix stats                       <span class="hash"># <span data-i18n="cli.stats">cross-session cost dashboard</span></span>
-npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i18n="cli.mcp">probe a single MCP server</span></span></code></pre>
+npx reasonix doctor                      <span class="hash"># <span data-i18n="cli.doctor">environment health check</span></span>
+npx reasonix replay &lt;file.jsonl&gt;         <span class="hash"># <span data-i18n="cli.replay">re-render a recorded session</span></span>
+npx reasonix diff a.jsonl b.jsonl        <span class="hash"># <span data-i18n="cli.diff">compare two transcripts</span></span>
+npx reasonix events &lt;name&gt;               <span class="hash"># <span data-i18n="cli.events">query the event log</span></span>
+npx reasonix stats                       <span class="hash"># <span data-i18n="cli.stats">cross-session usage</span></span>
+npx reasonix index                       <span class="hash"># <span data-i18n="cli.index">build semantic embedding index</span></span>
+npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i18n="cli.mcp">probe one MCP server</span></span>
+npx reasonix mcp list                    <span class="hash"># <span data-i18n="cli.mcplist">list configured MCP servers</span></span>
+npx reasonix prune-sessions              <span class="hash"># <span data-i18n="cli.prune">clean up old sessions</span></span></code></pre>
 
           <p class="cli-flags" data-i18n="cli.flags.intro">Common flags:</p>
-          <pre class="code"><code>--preset &lt;fast|smart|max&gt;   <span class="hash"># <span data-i18n="cli.f.preset">model + harvest + branch bundle</span></span>
---model &lt;id&gt;                <span class="hash"># <span data-i18n="cli.f.model">explicit DeepSeek model id</span></span>
---mcp "name=cmd args…"      <span class="hash"># <span data-i18n="cli.f.mcp">attach an MCP server (repeatable)</span></span>
---session &lt;name&gt;            <span class="hash"># <span data-i18n="cli.f.session">named session</span></span>
---no-config                 <span class="hash"># <span data-i18n="cli.f.noconf">ignore ~/.reasonix/config.json (CI)</span></span></code></pre>
+          <pre class="code"><code>--effort &lt;max|high|medium|low&gt;   <span class="hash"># <span data-i18n="cli.f.effort">reasoning depth for the run</span></span>
+--model &lt;id&gt;                     <span class="hash"># <span data-i18n="cli.f.model">explicit DeepSeek model id</span></span>
+--mcp "name=cmd args…"           <span class="hash"># <span data-i18n="cli.f.mcp">attach an MCP server (repeatable)</span></span>
+--session &lt;name&gt;                 <span class="hash"># <span data-i18n="cli.f.session">named session</span></span>
+--resume                         <span class="hash"># <span data-i18n="cli.f.resume">pick up the latest session for this workspace</span></span>
+--new                            <span class="hash"># <span data-i18n="cli.f.new">force a fresh session, preserve old</span></span>
+--no-config                      <span class="hash"># <span data-i18n="cli.f.noconf">ignore ~/.reasonix/config.json (CI)</span></span></code></pre>
+        </div>
+      </section>
+
+      <section id="community" class="community">
+        <div class="container">
+          <h2 class="section-title" data-i18n="comm.title">Built by the community</h2>
+          <p class="section-sub" data-i18n="comm.sub">
+            Reasonix is open source and community-developed. Every avatar on the wall
+            below is a real PR that shipped — not a sponsorship slot.
+          </p>
+
+          <p align="center">
+            <a
+              href="https://github.com/esengine/reasonix/graphs/contributors"
+              target="_blank"
+              rel="noopener"
+            >
+              <img
+                src="https://contrib.rocks/image?repo=esengine/reasonix&max=100&columns=12"
+                alt="Contributors to esengine/reasonix"
+                style="max-width: 100%; border-radius: 8px;"
+              />
+            </a>
+          </p>
+
+          <div class="comm-links">
+            <a
+              class="cta ghost"
+              href="https://github.com/esengine/reasonix/labels/good%20first%20issue"
+              target="_blank"
+              rel="noopener"
+              data-i18n="comm.gfi"
+              >good first issue →</a
+            >
+            <a
+              class="cta ghost"
+              href="https://github.com/esengine/reasonix/discussions"
+              target="_blank"
+              rel="noopener"
+              data-i18n="comm.disc"
+              >Discussions</a
+            >
+            <a
+              class="cta ghost"
+              href="https://github.com/esengine/reasonix/blob/main/CONTRIBUTING.md"
+              target="_blank"
+              rel="noopener"
+              data-i18n="comm.contrib"
+              >Contributing guide</a
+            >
+          </div>
         </div>
       </section>
 
@@ -385,7 +485,7 @@ npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i
         <div class="container">
           <h2 data-i18n="ctab.title">Ready to try?</h2>
           <p data-i18n="ctab.sub">
-            One <code>npx</code> away. Sandboxed. Reviewable. 98% cheaper.
+            One <code>npx</code> away. Sandboxed. Reviewable. Open source.
           </p>
           <div class="hero-ctas center">
             <a
@@ -427,11 +527,11 @@ npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i
             <a href="https://github.com/esengine/reasonix" target="_blank" rel="noopener">GitHub</a>
             <a href="https://www.npmjs.com/package/reasonix" target="_blank" rel="noopener">npm</a>
             <a
-              href="https://github.com/esengine/reasonix/blob/main/CHANGELOG.md"
+              href="https://github.com/esengine/reasonix/releases"
               target="_blank"
               rel="noopener"
-              data-i18n="foot.changelog"
-              >Changelog</a
+              data-i18n="foot.releases"
+              >Releases</a
             >
             <a
               href="https://github.com/esengine/reasonix/blob/main/LICENSE"
@@ -463,6 +563,13 @@ npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i
               data-i18n="foot.arch"
               >Architecture</a
             >
+            <a
+              href="https://github.com/esengine/reasonix/tree/main/benchmarks"
+              target="_blank"
+              rel="noopener"
+              data-i18n="foot.bench"
+              >Benchmarks</a
+            >
           </div>
           <div>
             <h4 data-i18n="foot.col.community">Community</h4>
@@ -480,6 +587,13 @@ npx reasonix mcp inspect &lt;spec&gt;          <span class="hash"># <span data-i
               data-i18n="foot.discuss"
               >Discussions</a
             >
+            <a
+              href="https://github.com/esengine/reasonix/graphs/contributors"
+              target="_blank"
+              rel="noopener"
+              data-i18n="foot.contributors"
+              >Contributors</a
+            >
           </div>
         </div>
       </div>

docs/styles.css

@@ -417,9 +417,9 @@ main,
 }
 .stat-num {
   font-family: var(--font-mono);
-  font-size: 28px;
+  font-size: 18px;
   font-weight: 700;
-  letter-spacing: -0.02em;
+  letter-spacing: -0.01em;
   margin-bottom: 4px;
 }
 .stat-label {
@@ -941,9 +941,9 @@ main,
 
 .feat-grid {
   display: grid;
-  grid-template-columns: repeat(2, 1fr);
+  grid-template-columns: repeat(3, 1fr);
   gap: 18px;
-  max-width: 980px;
+  max-width: 1100px;
   margin: 0 auto;
 }
 
@@ -1057,6 +1057,27 @@ main,
   margin: 24px 0 0;
 }
 
+/* Community */
+.community {
+  padding: 80px 0;
+}
+.community .container > p[align="center"] {
+  margin: 24px auto 32px;
+  max-width: 880px;
+  text-align: center;
+}
+.community .container > p[align="center"] img {
+  max-width: 100%;
+  border-radius: 8px;
+}
+.comm-links {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 12px;
+  margin-top: 8px;
+}
+
 /* CTA band */
 .cta-band {
   padding: 80px 0;
@@ -1128,10 +1149,10 @@ main,
     grid-template-columns: 1fr;
     gap: 40px;
   }
-  .why-grid {
+  .why-grid,
+  .feat-grid {
     grid-template-columns: repeat(2, 1fr);
   }
-  .feat-grid,
   .foot-inner {
     grid-template-columns: 1fr;
   }
@@ -1148,7 +1169,8 @@ main,
     margin: 24px auto 60px;
     padding: 0 20px;
   }
-  .why-grid {
+  .why-grid,
+  .feat-grid {
     grid-template-columns: 1fr;
   }
   .hero-stats {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "reasonix",
-  "version": "0.25.0",
+  "version": "0.30.0",
   "description": "DeepSeek-native coding agent: cache-first loop, flash-first cost control, tool-call repair.",
   "type": "module",
   "bin": {
@@ -30,6 +30,8 @@
     "chat": "tsx src/cli/index.ts chat",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
     "lint": "biome check src tests",
     "lint:fix": "biome check --write src tests",
     "format": "biome format --write src tests",
@@ -70,6 +72,7 @@
     "commander": "^12.1.0",
     "eventsource-parser": "^3.0.0",
     "ignore": "^7.0.5",
+    "node-html-parser": "^7.1.0",
     "picomatch": "^4.0.4",
     "react": "^18.3.1",
     "react-reconciler": "^0.29.2",
@@ -79,10 +82,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^22.9.0",
     "@types/picomatch": "^4.0.3",
     "@types/react": "^18.3.12",
     "@types/react-reconciler": "^0.28.9",
+    "@vitest/coverage-v8": "^2.1.5",
     "esbuild": "^0.21.5",
     "highlight.js": "^11.10.0",
     "htm": "^3.1.1",

scripts/coverage-summary.mjs

@@ -0,0 +1,44 @@
+import { readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = new URL("..", import.meta.url).pathname;
+const SUMMARY_PATH = join(ROOT, "coverage", "coverage-summary.json");
+
+const GITHUB_STEP_SUMMARY = process.env.GITHUB_STEP_SUMMARY;
+if (!GITHUB_STEP_SUMMARY) {
+  console.log("Not running in GitHub Actions (no GITHUB_STEP_SUMMARY). Skipping.");
+  process.exit(0);
+}
+
+let data;
+try {
+  data = JSON.parse(readFileSync(SUMMARY_PATH, "utf-8"));
+} catch (err) {
+  console.error("Failed to read coverage summary:", err.message);
+  process.exit(0); // don't fail the build if coverage report is missing
+}
+
+const { total } = data;
+if (!total) {
+  console.error("No 'total' key in coverage summary. Skipping.");
+  process.exit(0);
+}
+
+const pct = (metric) => {
+  const m = total[metric];
+  if (!m) return "-";
+  return `${m.pct.toFixed(1)}%`;
+};
+
+const rows = [
+  "| Metric | Coverage |",
+  "| ------ | -------- |",
+  `| Statements | ${pct("statements")} |`,
+  `| Branches   | ${pct("branches")}   |`,
+  `| Functions  | ${pct("functions")}  |`,
+  `| Lines      | ${pct("lines")}      |`,
+];
+
+const md = `## Coverage\n\n${rows.join("\n")}\n`;
+appendFileSync(GITHUB_STEP_SUMMARY, md + "\n");
+console.log("Coverage summary written to job summary.");

scripts/probe-cache.mjs

@@ -0,0 +1,156 @@
+/**
+ * Probes whether mutating a mid-history message destroys DeepSeek's prompt
+ * cache for everything after the mutation point.
+ *
+ * Hypothesis: our compactInPlace() rewrites old tool results, which shifts
+ * the byte offsets of every subsequent message. DeepSeek caches by exact
+ * prefix, so the next request would cache-hit only up to the mutation
+ * point, even though most of the conversation is unchanged.
+ *
+ * Run: node scripts/probe-cache.mjs
+ * Reads DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL from .env.testbak.
+ */
+
+import { readFileSync } from "node:fs";
+
+function loadDotenv(path) {
+  const txt = readFileSync(path, "utf8");
+  for (const line of txt.split(/\r?\n/)) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) process.env[m[1]] ??= m[2];
+  }
+}
+loadDotenv("./.env.testbak");
+
+const KEY = process.env.DEEPSEEK_API_KEY;
+const BASE = process.env.DEEPSEEK_BASE_URL ?? "https://api.deepseek.com";
+if (!KEY) throw new Error("DEEPSEEK_API_KEY missing");
+
+const filler = (label, n) =>
+  Array.from({ length: n }, (_, i) => `${label} line ${i}: lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`).join("\n");
+
+const SYS = "You are a terse echo bot. Reply with a single short sentence.";
+const MSG_A_FULL = `Long context block A. Detail follows:\n${filler("A", 80)}`;
+const MSG_A_TRUNCATED = `Long context block A. Detail follows:\n${filler("A", 8)}\n[truncated]`;
+const MSG_B = `Block B reference: ${filler("B", 30)}`;
+const MSG_C = `Block C reference: ${filler("C", 30)}`;
+
+async function call(label, messages) {
+  const t0 = Date.now();
+  const res = await fetch(`${BASE}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${KEY}`,
+    },
+    body: JSON.stringify({
+      model: "deepseek-chat",
+      messages,
+      temperature: 0,
+      max_tokens: 16,
+      stream: false,
+    }),
+  });
+  const ms = Date.now() - t0;
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${label} http ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const j = await res.json();
+  const u = j.usage ?? {};
+  const hit = u.prompt_cache_hit_tokens ?? 0;
+  const miss = u.prompt_cache_miss_tokens ?? 0;
+  const prompt = u.prompt_tokens ?? 0;
+  const ratio = hit + miss > 0 ? (hit / (hit + miss)) * 100 : 0;
+  console.log(
+    `[${label}] prompt=${prompt} hit=${hit} miss=${miss} hit%=${ratio.toFixed(1)} ${ms}ms`,
+  );
+  return { hit, miss, prompt };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+  console.log("=== Phase 1: warm cache with full conversation ===");
+  const warm = [
+    { role: "system", content: SYS },
+    { role: "user", content: MSG_A_FULL },
+    { role: "assistant", content: "ack A" },
+    { role: "user", content: MSG_B },
+    { role: "assistant", content: "ack B" },
+    { role: "user", content: MSG_C },
+    { role: "assistant", content: "ack C" },
+    { role: "user", content: "say hi" },
+  ];
+  await call("warm-1", warm);
+  await sleep(1500);
+  await call("warm-2", warm);
+
+  console.log("\n=== Phase 2: append a new turn (cache should hit on prefix) ===");
+  const appended = [
+    ...warm,
+    { role: "assistant", content: "hi" },
+    { role: "user", content: "say bye" },
+  ];
+  await sleep(1500);
+  const appendResult = await call("append", appended);
+
+  console.log("\n=== Phase 3: mutate MSG_A in place + append same new turn ===");
+  const mutated = [
+    { role: "system", content: SYS },
+    { role: "user", content: MSG_A_TRUNCATED },
+    { role: "assistant", content: "ack A" },
+    { role: "user", content: MSG_B },
+    { role: "assistant", content: "ack B" },
+    { role: "user", content: MSG_C },
+    { role: "assistant", content: "ack C" },
+    { role: "user", content: "say hi" },
+    { role: "assistant", content: "hi" },
+    { role: "user", content: "say bye" },
+  ];
+  await sleep(1500);
+  const mutateResult = await call("mutate", mutated);
+
+  console.log("\n=== Result (Phases 1-3) ===");
+  const lostHit = appendResult.hit - mutateResult.hit;
+  console.log(
+    `append: hit=${appendResult.hit}/${appendResult.prompt}  mutate: hit=${mutateResult.hit}/${mutateResult.prompt}`,
+  );
+  console.log(`cache tokens lost to in-place mutation: ${lostHit}`);
+  if (lostHit > 100) {
+    console.log("VERDICT: in-place mutation destroys cache. Hypothesis confirmed.");
+  } else {
+    console.log("VERDICT: cache survived mutation. Hypothesis rejected.");
+  }
+
+  console.log("\n=== Phase 4: append-only across many turns (the new code's behavior) ===");
+  const session = [
+    { role: "system", content: SYS },
+    { role: "user", content: MSG_A_FULL },
+    { role: "assistant", content: "ack A" },
+    { role: "user", content: MSG_B },
+    { role: "assistant", content: "ack B" },
+  ];
+  const ratios = [];
+  for (let i = 0; i < 5; i++) {
+    session.push({ role: "user", content: `turn ${i}: ${filler(`Q${i}`, 10)}` });
+    await sleep(1200);
+    const r = await call(`turn-${i}`, session);
+    session.push({ role: "assistant", content: `reply ${i}` });
+    const total = r.hit + r.miss;
+    ratios.push(total > 0 ? (r.hit / total) * 100 : 0);
+  }
+  const avg = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+  console.log(`\nappend-only cache hit % across 5 turns: ${ratios.map((x) => x.toFixed(1)).join(", ")}`);
+  console.log(`average: ${avg.toFixed(1)}%`);
+  if (avg > 80) {
+    console.log("VERDICT: append-only keeps cache warm across turns. New strategy validated.");
+  } else {
+    console.log("VERDICT: cache hit lower than expected — investigate.");
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

scripts/probe-long-session.mts

@@ -0,0 +1,167 @@
+/**
+ * Long-session probe — drives CacheFirstLoop through 20 real turns
+ * with oversized tool results (each ~4k tokens, the size that USED to
+ * trigger the old turn-end auto-compaction every turn).
+ *
+ * Reports per-turn: prompt size, cache hit %, miss tokens, USD cost.
+ * Surfaces: cache trajectory, cost shape, anything degrading over time.
+ *
+ * Run: REASONIX_LOG_LEVEL=ERROR npx tsx scripts/probe-long-session.mts
+ */
+
+import { readFileSync } from "node:fs";
+import { DeepSeekClient } from "../src/client.js";
+import { CacheFirstLoop } from "../src/loop.js";
+import { ImmutablePrefix } from "../src/memory/runtime.js";
+import { DEEPSEEK_CONTEXT_TOKENS } from "../src/telemetry/stats.js";
+import { ToolRegistry } from "../src/tools.js";
+
+// Force a small ctx window so the 50% fold threshold trips in a few
+// turns instead of needing 200+ turns at the real 1M cap. Same model
+// id, real API call, just the local gauge is shrunk.
+DEEPSEEK_CONTEXT_TOKENS["deepseek-chat"] = 50_000;
+
+function loadDotenv(path: string) {
+  const txt = readFileSync(path, "utf8");
+  for (const line of txt.split(/\r?\n/)) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m && !process.env[m[1]]) process.env[m[1]] = m[2];
+  }
+}
+loadDotenv("./.env.testbak");
+
+const PRICE_HIT_PER_M = 0.07;
+const PRICE_MISS_PER_M = 0.27;
+const PRICE_COMPLETION_PER_M = 1.1;
+
+const docLine = (i: number, sec: string) =>
+  `[${sec}#${i}] section ${sec} entry ${i}: requirement traces to constraint ${(i % 7) + 1}, status ${i % 3 === 0 ? "open" : "closed"}, owner team-${(i % 5) + 1}, last touched 2026-04-${(i % 28) + 1}.`;
+
+async function main() {
+  const reg = new ToolRegistry();
+  reg.register({
+    name: "read_doc",
+    description: "Read a section of a project document.",
+    parameters: {
+      type: "object",
+      properties: { section: { type: "string" } },
+      required: ["section"],
+    },
+    fn: async (args: Record<string, unknown>) => {
+      const sec = String(args.section ?? "default");
+      const lines = Array.from({ length: 65 }, (_, i) => docLine(i, sec));
+      return lines.join("\n");
+    },
+  });
+
+  const client = new DeepSeekClient();
+  const model = "deepseek-chat";
+  const loop = new CacheFirstLoop({
+    client,
+    prefix: new ImmutablePrefix({
+      system:
+        "You are a documentation triage agent. For each turn, call read_doc with the section the user asks about, then reply with one short sentence summarizing what you found.",
+      toolSpecs: reg.specs(),
+    }),
+    tools: reg,
+    stream: false,
+    model,
+    maxToolIters: 4,
+  });
+
+  let mutations = 0;
+  let folds = 0;
+  const origCompactInPlace = loop.log.compactInPlace.bind(loop.log);
+  loop.log.compactInPlace = (...args) => {
+    mutations++;
+    return origCompactInPlace(...args);
+  };
+
+  const sections = [
+    "auth",
+    "billing",
+    "telemetry",
+    "rate-limit",
+    "webhooks",
+    "search",
+    "indexing",
+    "permissions",
+    "audit",
+    "exports",
+    "imports",
+    "cdn",
+    "analytics",
+    "rbac",
+    "sso",
+    "scheduler",
+    "workflows",
+    "notifications",
+    "reports",
+    "api-v2",
+  ];
+
+  console.log("turn |  prompt  |   hit   |   miss  | hit% |  $/turn  |  $cum");
+  console.log("-----+----------+---------+---------+------+----------+--------");
+
+  let cumCost = 0;
+  let forceSummaryHit = false;
+
+  for (let i = 0; i < sections.length; i++) {
+    const t0 = Date.now();
+    let usage: {
+      promptTokens: number;
+      completionTokens: number;
+      promptCacheHitTokens: number;
+      promptCacheMissTokens: number;
+    } | null = null;
+    let warning = "";
+    for await (const ev of loop.step(`Read the "${sections[i]}" section.`)) {
+      if (ev.role === "assistant_final" && ev.stats?.usage) {
+        usage = ev.stats.usage as typeof usage;
+      }
+      if (ev.role === "warning" && ev.content) {
+        warning = ev.content;
+        if (/folded \d+ messages/.test(ev.content)) folds++;
+      }
+      if (ev.forcedSummary) forceSummaryHit = true;
+    }
+    const ms = Date.now() - t0;
+    if (!usage) {
+      console.log(
+        `${String(i).padStart(3)}  | (no usage)  -- ${warning ? `warning: ${warning}` : ""}`,
+      );
+      continue;
+    }
+    const total = usage.promptCacheHitTokens + usage.promptCacheMissTokens;
+    const ratio = total > 0 ? (usage.promptCacheHitTokens / total) * 100 : 0;
+    const cost =
+      (usage.promptCacheHitTokens * PRICE_HIT_PER_M +
+        usage.promptCacheMissTokens * PRICE_MISS_PER_M +
+        usage.completionTokens * PRICE_COMPLETION_PER_M) /
+      1_000_000;
+    cumCost += cost;
+    console.log(
+      `${String(i).padStart(3)}  | ${String(usage.promptTokens).padStart(7)} | ${String(usage.promptCacheHitTokens).padStart(7)} | ${String(usage.promptCacheMissTokens).padStart(7)} | ${ratio.toFixed(1).padStart(4)} | $${cost.toFixed(5)} | $${cumCost.toFixed(4)}  ${ms}ms${warning ? ` (${warning.slice(0, 60)}…)` : ""}`,
+    );
+    if (forceSummaryHit) {
+      console.log(
+        `\n>> force-summary triggered at turn ${i} (${ratio.toFixed(1)}% cache hit, ${usage.promptTokens} tokens)`,
+      );
+      break;
+    }
+  }
+
+  console.log(`\ntotal log.compactInPlace() calls: ${mutations} (expected: ${folds} folds)`);
+  console.log(`total cost across session: $${cumCost.toFixed(4)}`);
+
+  if (mutations !== folds) {
+    console.log(`FAIL: ${mutations} mutations but only ${folds} fold events — unexpected mutation`);
+    process.exit(1);
+  }
+  console.log(`\nVERDICT: ${folds} fold(s) fired, no other mutations.`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

scripts/probe-loop-cache.mts

@@ -0,0 +1,118 @@
+/**
+ * End-to-end cache probe — drives CacheFirstLoop through real turns
+ * against the live DeepSeek API and reports cache hit % per turn.
+ *
+ * The point: validate that the post-PR code (no auto-compaction)
+ * actually sustains high cache hit on a long-ish session, not just
+ * that the API-level append-vs-mutate primitive behaves as expected.
+ *
+ * Run: REASONIX_LOG_LEVEL=ERROR npx tsx scripts/probe-loop-cache.mts
+ * Reads DEEPSEEK_API_KEY from .env.testbak.
+ */
+
+import { readFileSync } from "node:fs";
+import { CacheFirstLoop } from "../src/loop.js";
+import { DeepSeekClient } from "../src/client.js";
+import { ImmutablePrefix } from "../src/memory/runtime.js";
+import { ToolRegistry } from "../src/tools.js";
+
+function loadDotenv(path: string) {
+  const txt = readFileSync(path, "utf8");
+  for (const line of txt.split(/\r?\n/)) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m && !process.env[m[1]]) process.env[m[1]] = m[2];
+  }
+}
+loadDotenv("./.env.testbak");
+
+const filler = (label: string, n: number): string =>
+  Array.from(
+    { length: n },
+    (_, i) =>
+      `${label} line ${i}: lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`,
+  ).join("\n");
+
+async function main() {
+  const reg = new ToolRegistry();
+  reg.register({
+    name: "echo",
+    description: "echo the input back",
+    parameters: {
+      type: "object",
+      properties: { msg: { type: "string" } },
+      required: ["msg"],
+    },
+    fn: async (args: Record<string, unknown>) => `echoed: ${String(args.msg ?? "")}`,
+  });
+
+  const client = new DeepSeekClient();
+  const loop = new CacheFirstLoop({
+    client,
+    prefix: new ImmutablePrefix({
+      system:
+        "You are a terse echo bot. Reply with one short sentence. Do not call any tools unless explicitly asked.",
+      toolSpecs: reg.specs(),
+    }),
+    tools: reg,
+    stream: false,
+    maxToolIters: 4,
+  });
+
+  // Pre-seed log with a moderate prior conversation (~6k tokens of
+  // user/assistant turns) so the cache has something substantial to
+  // hit across subsequent turns.
+  loop.log.append({ role: "user", content: `prior context: ${filler("ctx", 60)}` });
+  loop.log.append({ role: "assistant", content: "noted." });
+  loop.log.append({ role: "user", content: `more context: ${filler("more", 40)}` });
+  loop.log.append({ role: "assistant", content: "noted." });
+
+  const ratios: number[] = [];
+  let mutations = 0;
+  const origCompactInPlace = loop.log.compactInPlace.bind(loop.log);
+  loop.log.compactInPlace = (...args: Parameters<typeof origCompactInPlace>) => {
+    mutations++;
+    return origCompactInPlace(...args);
+  };
+
+  for (let i = 0; i < 6; i++) {
+    let usage: { promptTokens: number; promptCacheHitTokens: number; promptCacheMissTokens: number } | null = null;
+    for await (const ev of loop.step(`Turn ${i}: just say "ok ${i}".`)) {
+      if (ev.role === "assistant_final" && ev.stats?.usage) {
+        usage = ev.stats.usage as typeof usage;
+      }
+    }
+    if (!usage) {
+      console.log(`turn-${i}: no usage captured`);
+      ratios.push(0);
+      continue;
+    }
+    const total = usage.promptCacheHitTokens + usage.promptCacheMissTokens;
+    const ratio = total > 0 ? (usage.promptCacheHitTokens / total) * 100 : 0;
+    console.log(
+      `turn-${i}: prompt=${usage.promptTokens} hit=${usage.promptCacheHitTokens} miss=${usage.promptCacheMissTokens} hit%=${ratio.toFixed(1)}`,
+    );
+    ratios.push(ratio);
+  }
+
+  console.log(`\ntotal log.compactInPlace() calls: ${mutations}`);
+  console.log(`cache hit % per turn: ${ratios.map((x) => x.toFixed(1)).join(", ")}`);
+
+  const warmRatios = ratios.slice(1);
+  const avgWarm = warmRatios.reduce((a, b) => a + b, 0) / warmRatios.length;
+  console.log(`warm-turn average (excluding cold start): ${avgWarm.toFixed(1)}%`);
+
+  if (mutations > 0) {
+    console.log(`\nFAIL: log was mutated ${mutations} time(s) — append-only invariant broken`);
+    process.exit(1);
+  }
+  if (avgWarm < 80) {
+    console.log(`\nFAIL: warm-turn average ${avgWarm.toFixed(1)}% below 80% threshold`);
+    process.exit(1);
+  }
+  console.log(`\nPASS: append-only sustained, cache hit avg ${avgWarm.toFixed(1)}%`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

src/at-mentions.ts

@@ -315,8 +315,10 @@ export function expandAtMentions(
   for (const match of text.matchAll(AT_MENTION_PATTERN)) {
     const rawPath = match[1] ?? "";
     // Strip trailing dot (sentence terminator): `@foo.ts.` → `@foo.ts`.
-    // Keep internal dots intact.
-    const cleaned = rawPath.replace(/\.+$/, "");
+    // Keep internal dots intact. Manual loop instead of `/\.+$/` — the
+    // regex is O(n²) on dot-heavy non-matches per CodeQL js/polynomial-redos.
+    let cleaned = rawPath;
+    while (cleaned.endsWith(".")) cleaned = cleaned.slice(0, -1);
     if (!cleaned) continue;
     const token = `@${cleaned}`;
     if (seen.has(token)) continue;

src/cli/commands/chat.tsx

@@ -2,6 +2,7 @@ import { render } from "ink";
 import React, { useState } from "react";
 import { loadApiKey, readConfig, searchEnabled } from "../../config.js";
 import { loadDotenv } from "../../env.js";
+import type { CacheFirstLoop } from "../../loop.js";
 import { McpClient } from "../../mcp/client.js";
 import { type InspectionReport, inspectMcpServer } from "../../mcp/inspect.js";
 import { type McpClientHost, bridgeMcpTools } from "../../mcp/registry.js";
@@ -35,6 +36,220 @@ export interface ProgressInfo {
   message?: string;
 }
 
+interface SpecRecord {
+  spec: string;
+  client: McpClient;
+  summary: McpServerSummary;
+  /** Names of bridged tools — used for hot-unbridge. */
+  registeredNames: string[];
+  /** ToolSpec snapshots captured AFTER bridge — handed to loop.prefix.addTool on hot-add. */
+  registeredSpecs: import("../../types.js").ToolSpec[];
+}
+
+interface RuntimeContext {
+  getTools: () => ToolRegistry | undefined;
+  getMcpPrefix: () => string | undefined;
+  getRequestedCount: () => number;
+  progressSink: { current: ((info: ProgressInfo) => void) | null };
+}
+
+export interface McpRuntime {
+  size(): number;
+  specs(): string[];
+  summaries(): McpServerSummary[];
+  addSpec(
+    raw: string,
+    loop?: CacheFirstLoop,
+  ): Promise<{ ok: true; summary: McpServerSummary } | { ok: false; reason: string }>;
+  removeSpec(raw: string, loop?: CacheFirstLoop): Promise<boolean>;
+  reloadFromConfig(loop?: CacheFirstLoop): Promise<{
+    added: string[];
+    removed: string[];
+    failed: Array<{ spec: string; reason: string }>;
+    summaries: McpServerSummary[];
+  }>;
+  closeAll(): Promise<void>;
+}
+
+function createMcpRuntime(ctx: RuntimeContext): McpRuntime {
+  const records = new Map<string, SpecRecord>();
+  const insertionOrder: string[] = [];
+
+  async function addSpec(
+    raw: string,
+    loop?: CacheFirstLoop,
+  ): Promise<{ ok: true; summary: McpServerSummary } | { ok: false; reason: string }> {
+    if (records.has(raw)) {
+      return { ok: true, summary: records.get(raw)!.summary };
+    }
+    const tools = ctx.getTools();
+    if (!tools) return { ok: false, reason: "no tool registry available" };
+    const disabledNames = new Set(readConfig().mcpDisabled ?? []);
+    let label = "anon";
+    let mcp: McpClient | undefined;
+    try {
+      const spec = parseMcpSpec(raw);
+      label = spec.name ?? "anon";
+      if (spec.name && disabledNames.has(spec.name)) {
+        process.stderr.write(`${formatMcpLifecycleEvent({ state: "disabled", name: label })}\n`);
+        return { ok: false, reason: "disabled by user" };
+      }
+      process.stderr.write(`${formatMcpLifecycleEvent({ state: "handshake", name: label })}\n`);
+      const t0 = Date.now();
+      const namePrefix = spec.name
+        ? `${spec.name}_`
+        : ctx.getRequestedCount() === 1 && ctx.getMcpPrefix()
+          ? (ctx.getMcpPrefix() as string)
+          : "";
+      const transport: McpTransport =
+        spec.transport === "sse"
+          ? new SseTransport({ url: spec.url })
+          : spec.transport === "streamable-http"
+            ? new StreamableHttpTransport({ url: spec.url })
+            : new StdioTransport({ command: spec.command, args: spec.args });
+      mcp = new McpClient({ transport });
+      await mcp.initialize();
+      const host: McpClientHost = { client: mcp };
+      const bridge = await bridgeMcpTools(mcp, {
+        registry: tools,
+        namePrefix,
+        serverName: label,
+        host,
+        onProgress: (info) => ctx.progressSink.current?.(info),
+        onSlow: (info) =>
+          process.stderr.write(
+            `${formatMcpSlowToast({ name: info.serverName, p95Ms: info.p95Ms, sampleSize: info.sampleSize })}\n`,
+          ),
+      });
+      let report: InspectionReport;
+      try {
+        report = await inspectMcpServer(mcp);
+      } catch {
+        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" },
+          elapsedMs: 0,
+        };
+      }
+      const ms = Date.now() - t0;
+      const resourceCount = report.resources.supported ? report.resources.items.length : 0;
+      const promptCount = report.prompts.supported ? report.prompts.items.length : 0;
+      process.stderr.write(
+        `${formatMcpLifecycleEvent({
+          state: "connected",
+          name: label,
+          tools: bridge.registeredNames.length,
+          resources: resourceCount,
+          prompts: promptCount,
+          ms,
+        })}\n`,
+      );
+      const summary = buildMcpServerSummary({
+        label,
+        spec: raw,
+        toolCount: bridge.registeredNames.length,
+        report,
+        host,
+        bridgeEnv: bridge.env,
+      });
+      // Snapshot tool specs AFTER bridge so hot-add can replay them into loop.prefix.
+      const allSpecs = tools.specs();
+      const registeredSpecs = allSpecs.filter((s) =>
+        bridge.registeredNames.includes(s.function.name),
+      );
+      records.set(raw, {
+        spec: raw,
+        client: mcp,
+        summary,
+        registeredNames: bridge.registeredNames,
+        registeredSpecs,
+      });
+      insertionOrder.push(raw);
+      // Hot-add: shift the prefix so the live loop sees the new tools
+      // on the very next turn. Each addTool is one cache-miss turn.
+      if (loop) for (const s of registeredSpecs) loop.prefix.addTool(s);
+      return { ok: true, summary };
+    } catch (err) {
+      await mcp?.close().catch(() => undefined);
+      const reason = (err as Error).message;
+      process.stderr.write(
+        `${formatMcpLifecycleEvent({ state: "failed", name: label, reason })}\n  → run \`reasonix setup\` to remove this entry, or fix the underlying issue (missing npm package, network, etc.).\n`,
+      );
+      return { ok: false, reason };
+    }
+  }
+
+  async function removeSpec(raw: string, loop?: CacheFirstLoop): Promise<boolean> {
+    const record = records.get(raw);
+    if (!record) return false;
+    await record.client.close().catch(() => undefined);
+    const tools = ctx.getTools();
+    for (const name of record.registeredNames) {
+      tools?.unregister(name);
+      loop?.prefix.removeTool(name);
+    }
+    records.delete(raw);
+    const idx = insertionOrder.indexOf(raw);
+    if (idx >= 0) insertionOrder.splice(idx, 1);
+    return true;
+  }
+
+  async function reloadFromConfig(loop?: CacheFirstLoop): Promise<{
+    added: string[];
+    removed: string[];
+    failed: Array<{ spec: string; reason: string }>;
+    summaries: McpServerSummary[];
+  }> {
+    const desired = readConfig().mcp ?? [];
+    const desiredSet = new Set(desired);
+    const currentSet = new Set(records.keys());
+    const added: string[] = [];
+    const removed: string[] = [];
+    const failed: Array<{ spec: string; reason: string }> = [];
+
+    for (const spec of [...currentSet]) {
+      if (!desiredSet.has(spec)) {
+        await removeSpec(spec, loop);
+        removed.push(spec);
+      }
+    }
+    for (const spec of desired) {
+      if (currentSet.has(spec)) continue;
+      const result = await addSpec(spec, loop);
+      if (result.ok) added.push(spec);
+      else failed.push({ spec, reason: result.reason });
+    }
+    return { added, removed, failed, summaries: summaries() };
+  }
+
+  function specs(): string[] {
+    return [...insertionOrder];
+  }
+  function summaries(): McpServerSummary[] {
+    return insertionOrder
+      .map((s) => records.get(s)?.summary)
+      .filter((s): s is McpServerSummary => Boolean(s));
+  }
+  async function closeAll(): Promise<void> {
+    for (const r of records.values()) await r.client.close().catch(() => undefined);
+    records.clear();
+    insertionOrder.length = 0;
+  }
+  return {
+    size: () => records.size,
+    specs,
+    summaries,
+    addSpec,
+    removeSpec,
+    reloadFromConfig,
+    closeAll,
+  };
+}
+
 export interface ChatOptions {
   model: string;
   system: string;
@@ -96,6 +311,8 @@ interface RootProps extends ChatOptions {
   progressSink: { current: ((info: ProgressInfo) => void) | null };
   /** Show the SessionPicker (full list) when no --session was specified and saved sessions exist. */
   showPicker: boolean;
+  /** Hot-reload runtime — passed through to App so /mcp browse + dashboard can bridge after install. */
+  mcpRuntime: McpRuntime;
 }
 
 function Root({
@@ -105,6 +322,7 @@ function Root({
   mcpServers,
   progressSink,
   showPicker,
+  mcpRuntime,
   ...appProps
 }: RootProps) {
   const [key, setKey] = useState<string | undefined>(initialKey);
@@ -176,6 +394,7 @@ function Root({
         tools={tools}
         mcpSpecs={mcpSpecs}
         mcpServers={mcpServers}
+        mcpRuntime={mcpRuntime}
         progressSink={progressSink}
         codeMode={appProps.codeMode}
         noDashboard={appProps.noDashboard}
@@ -190,10 +409,6 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
   const initialKey = loadApiKey();
 
   const requestedSpecs = opts.mcp ?? [];
-  const clients: McpClient[] = [];
-  const successfulSpecs: string[] = [];
-  const failedSpecs: Array<{ spec: string; reason: string }> = [];
-  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
@@ -204,115 +419,25 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
   // 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) tools = new ToolRegistry();
 
-  const disabledNames = new Set(readConfig().mcpDisabled ?? []);
-  if (requestedSpecs.length > 0) {
-    if (!tools) tools = new ToolRegistry();
-    for (const raw of requestedSpecs) {
-      let label = "anon";
-      let mcp: McpClient | undefined;
-      try {
-        const spec = parseMcpSpec(raw);
-        label = spec.name ?? "anon";
-        if (spec.name && disabledNames.has(spec.name)) {
-          process.stderr.write(`${formatMcpLifecycleEvent({ state: "disabled", name: label })}\n`);
-          continue;
-        }
-        process.stderr.write(`${formatMcpLifecycleEvent({ state: "handshake", name: label })}\n`);
-        const t0 = Date.now();
-        const prefix = spec.name
-          ? `${spec.name}_`
-          : requestedSpecs.length === 1 && opts.mcpPrefix
-            ? opts.mcpPrefix
-            : "";
-        const transport: McpTransport =
-          spec.transport === "sse"
-            ? new SseTransport({ url: spec.url })
-            : spec.transport === "streamable-http"
-              ? new StreamableHttpTransport({ url: spec.url })
-              : new StdioTransport({ command: spec.command, args: spec.args });
-        mcp = new McpClient({ transport });
-        await mcp.initialize();
-        // Host indirection lets `/mcp reconnect` swap the underlying client
-        // without re-bridging the registered tools (closures resolve via
-        // host.client at call time).
-        const host: McpClientHost = { client: mcp };
-        const bridge = await bridgeMcpTools(mcp, {
-          registry: tools,
-          namePrefix: prefix,
-          serverName: label,
-          host,
-          onProgress: (info) => progressSink.current?.(info),
-          onSlow: (info) =>
-            process.stderr.write(
-              `${formatMcpSlowToast({ name: info.serverName, p95Ms: info.p95Ms, sampleSize: info.sampleSize })}\n`,
-            ),
-        });
-        // Inspect collects resources + prompts once so `/mcp` can render them
-        // synchronously. Servers that don't support these fall through as
-        // `{supported: false}` instead of throwing.
-        let report: InspectionReport;
-        try {
-          report = await inspectMcpServer(mcp);
-        } catch {
-          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" },
-            elapsedMs: 0,
-          };
-        }
-        const ms = Date.now() - t0;
-        const resourceCount = report.resources.supported ? report.resources.items.length : 0;
-        const promptCount = report.prompts.supported ? report.prompts.items.length : 0;
-        process.stderr.write(
-          `${formatMcpLifecycleEvent({
-            state: "connected",
-            name: label,
-            tools: bridge.registeredNames.length,
-            resources: resourceCount,
-            prompts: promptCount,
-            ms,
-          })}\n`,
-        );
-        clients.push(mcp);
-        successfulSpecs.push(raw);
-        mcpServers.push(
-          buildMcpServerSummary({
-            label,
-            spec: raw,
-            toolCount: bridge.registeredNames.length,
-            report,
-            host,
-            bridgeEnv: bridge.env,
-          }),
-        );
-      } catch (err) {
-        // Per-server failure is non-fatal: one broken server shouldn't
-        // kill a chat that has working servers configured. Recover by
-        // recording the failure and continuing; user fixes via `reasonix
-        // setup` without losing their other servers.
-        await mcp?.close().catch(() => undefined);
-        const reason = (err as Error).message;
-        failedSpecs.push({ spec: raw, reason });
-        process.stderr.write(
-          `${formatMcpLifecycleEvent({ state: "failed", name: label, reason })}\n  → run \`reasonix setup\` to remove this entry, or fix the underlying issue (missing npm package, network, etc.).\n`,
-        );
-      }
-    }
-    // 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 runtime = createMcpRuntime({
+    getTools: () => tools,
+    getMcpPrefix: () => opts.mcpPrefix,
+    getRequestedCount: () => requestedSpecs.length,
+    progressSink,
+  });
+
+  const failedSpecs: Array<{ spec: string; reason: string }> = [];
+  for (const raw of requestedSpecs) {
+    const result = await runtime.addSpec(raw);
+    if (!result.ok) failedSpecs.push({ spec: raw, reason: result.reason });
   }
-  const mcpSpecs = successfulSpecs;
+  if (runtime.size() === 0 && !opts.seedTools) {
+    tools = undefined;
+  }
+  const mcpSpecs = runtime.specs();
+  const mcpServers = runtime.summaries();
 
   // Register web search/fetch tools unless explicitly disabled. DDG
   // backs them with no key required; the model invokes them whenever
@@ -367,6 +492,7 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
       tools={tools}
       mcpSpecs={mcpSpecs}
       mcpServers={mcpServers}
+      mcpRuntime={runtime}
       progressSink={progressSink}
       showPicker={showPicker}
       {...opts}
@@ -378,6 +504,6 @@ export async function chatCommand(opts: ChatOptions): Promise<void> {
   try {
     await waitUntilExit();
   } finally {
-    for (const c of clients) await c.close();
+    await runtime.closeAll();
   }
 }

src/cli/commands/doctor.ts

@@ -226,7 +226,7 @@ async function checkSessions(): Promise<Check> {
       return {
         label: "sessions     ",
         level: "warn",
-        detail: `${detail} · ${stale} idle ≥90d (run /prune-sessions)`,
+        detail: `${detail} · ${stale} idle ≥90d (run \`reasonix prune-sessions\`)`,
       };
     }
     return { label: "sessions     ", level: "ok", detail };

src/cli/commands/events.ts

@@ -80,6 +80,14 @@ function detailsFor(e: Event): string {
       return `${e.callId} reason=${e.reason}`;
     case "tool.result":
       return `${e.callId} ${e.ok ? "ok" : "err"} ${e.output.length}B${e.truncated ? " [trunc]" : ""}`;
+    case "tool.call":
+      return `${e.name} args=${truncate(JSON.stringify(e.args), 60)}`;
+    case "tool.confirm.allow":
+      return `${e.kind} ${quote(e.payload.command, 60)}`;
+    case "tool.confirm.deny":
+      return `${e.kind} ${quote(e.payload.command, 60)}${e.denyContext ? ` — ${truncate(e.denyContext, 40)}` : ""}`;
+    case "tool.confirm.always_allow":
+      return `${e.kind} ${quote(e.payload.command, 60)} prefix=${truncate(e.prefix, 30)}`;
     case "effect.file.touched":
       return `${e.mode} ${e.path} (${e.bytes}B)`;
     case "effect.memory.written":

src/cli/commands/mcp-browse.tsx

@@ -0,0 +1,237 @@
+/** `reasonix mcp browse` — Ink TUI for the MCP marketplace. Lazy-loads pages on scroll. */
+
+import { Box, Text, render, useApp, useInput } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig jsx=react needs React in value scope for JSX compilation
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import { readConfig, writeConfig } from "../../config.js";
+import { loadDotenv } from "../../env.js";
+import {
+  type RegistryHandle,
+  loadMorePages,
+  openRegistry,
+  specStringFor,
+} from "../../mcp/registry-fetch.js";
+import type { RegistryEntry } from "../../mcp/registry-types.js";
+
+const VISIBLE_ROWS = 12;
+
+interface State {
+  handle: RegistryHandle | null;
+  loading: boolean;
+  query: string;
+  selected: number;
+  status: string;
+}
+
+function rankAndFilter(entries: RegistryEntry[], query: string): RegistryEntry[] {
+  const q = query.trim().toLowerCase();
+  const list = q
+    ? entries.filter((e) => `${e.name} ${e.title} ${e.description}`.toLowerCase().includes(q))
+    : entries;
+  return [...list].sort((a, b) => {
+    const ap = a.popularity ?? -1;
+    const bp = b.popularity ?? -1;
+    if (ap !== bp) return bp - ap;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function McpBrowseApp() {
+  const app = useApp();
+  const [state, setState] = useState<State>({
+    handle: null,
+    loading: true,
+    query: "",
+    selected: 0,
+    status: "opening registry…",
+  });
+
+  const setStatus = useCallback((status: string) => {
+    setState((s) => ({ ...s, status }));
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const handle = await openRegistry({});
+        if (cancelled) return;
+        const ageMs = Date.now() - handle.fetchedAt;
+        const ageStr =
+          ageMs < 60_000 ? `${Math.floor(ageMs / 1000)}s` : `${Math.floor(ageMs / 60_000)}m`;
+        setState((s) => ({
+          ...s,
+          handle,
+          loading: false,
+          status: `${handle.source} · ${handle.cache.entries.length} entries${
+            handle.fromCache ? ` · cached ${ageStr} ago` : ""
+          }`,
+        }));
+      } catch (err) {
+        if (cancelled) return;
+        setState((s) => ({ ...s, loading: false, status: `error: ${(err as Error).message}` }));
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const filtered = useMemo(() => {
+    if (!state.handle) return [];
+    return rankAndFilter(state.handle.cache.entries, state.query);
+  }, [state.handle, state.query]);
+
+  const selected = filtered[state.selected];
+
+  const fetchMore = useCallback(async () => {
+    if (!state.handle || state.loading) return;
+    if (state.handle.cache.pagination.nextCursor === null) {
+      setStatus("no more pages — registry exhausted");
+      return;
+    }
+    setState((s) => ({ ...s, loading: true, status: "loading more…" }));
+    try {
+      const r = await loadMorePages(state.handle, { pages: 5 });
+      setState((s) => ({
+        ...s,
+        loading: false,
+        status: `+${r.newEntries} entries (${state.handle?.cache.entries.length ?? 0} total)${
+          r.exhausted ? " · exhausted" : ""
+        }`,
+      }));
+    } catch (err) {
+      setState((s) => ({ ...s, loading: false, status: `error: ${(err as Error).message}` }));
+    }
+  }, [state.handle, state.loading, setStatus]);
+
+  const install = useCallback(
+    (entry: RegistryEntry) => {
+      if (!entry.install) {
+        setStatus(`${entry.name} has no install info (smithery listing)`);
+        return;
+      }
+      try {
+        const spec = specStringFor(entry.name, entry.install);
+        const cfg = readConfig();
+        const existing = cfg.mcp ?? [];
+        if (existing.includes(spec)) {
+          setStatus(`already installed: ${spec}`);
+          return;
+        }
+        writeConfig({ ...cfg, mcp: [...existing, spec] });
+        setStatus(`installed → ${spec}`);
+      } catch (err) {
+        setStatus(`install failed: ${(err as Error).message}`);
+      }
+    },
+    [setStatus],
+  );
+
+  useInput((input, key) => {
+    if (key.escape || (key.ctrl && input === "c")) {
+      app.exit();
+      return;
+    }
+    if (key.upArrow) {
+      setState((s) => ({ ...s, selected: Math.max(0, s.selected - 1) }));
+      return;
+    }
+    if (key.downArrow) {
+      setState((s) => ({ ...s, selected: Math.min(filtered.length - 1, s.selected + 1) }));
+      return;
+    }
+    if (key.return) {
+      if (selected) install(selected);
+      return;
+    }
+    if (key.tab || (key.ctrl && input === "n")) {
+      void fetchMore();
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setState((s) => ({ ...s, query: s.query.slice(0, -1), selected: 0 }));
+      return;
+    }
+    if (input && !key.ctrl && !key.meta) {
+      setState((s) => ({ ...s, query: s.query + input, selected: 0 }));
+    }
+  });
+
+  const start = Math.max(
+    0,
+    Math.min(state.selected - Math.floor(VISIBLE_ROWS / 2), filtered.length - VISIBLE_ROWS),
+  );
+  const window = filtered.slice(Math.max(0, start), Math.max(0, start) + VISIBLE_ROWS);
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Box>
+        <Text bold color="cyan">
+          ◈ MCP marketplace
+        </Text>
+        <Text dimColor>{`  ·  ${state.status}`}</Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text>search: </Text>
+        <Text color="white">{state.query || "(type to filter)"}</Text>
+        <Text dimColor>{`  ${filtered.length} match${filtered.length === 1 ? "" : "es"}`}</Text>
+      </Box>
+      <Box marginTop={1} flexDirection="column">
+        {window.length === 0 ? (
+          <Text dimColor>{state.loading ? "loading…" : "no entries"}</Text>
+        ) : (
+          window.map((e, i) => {
+            const idx = (start || 0) + i;
+            const active = idx === state.selected;
+            const tag =
+              e.source === "official" ? "[off]" : e.source === "smithery" ? "[smt]" : "[loc]";
+            const pop = e.popularity !== undefined ? ` · ${e.popularity.toLocaleString()}` : "";
+            return (
+              <Box key={e.name}>
+                <Text color={active ? "cyan" : undefined}>{active ? "▸ " : "  "}</Text>
+                <Text bold={active}>{e.name.padEnd(40).slice(0, 40)}</Text>
+                <Text dimColor>{` ${tag}${pop}`}</Text>
+              </Box>
+            );
+          })
+        )}
+      </Box>
+      {selected ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold color="white">
+            {selected.title}
+          </Text>
+          {selected.description ? <Text dimColor>{selected.description.slice(0, 160)}</Text> : null}
+          {selected.install ? (
+            <Text dimColor>
+              {`spec: ${selected.install.runtime} ${selected.install.packageId ?? selected.install.url ?? "—"} · ${selected.install.transport}`}
+            </Text>
+          ) : (
+            <Text dimColor>(smithery listing — install info not exposed)</Text>
+          )}
+          {selected.install?.requiredEnv?.length ? (
+            <Text color="yellow">{`needs: ${selected.install.requiredEnv.join(", ")}`}</Text>
+          ) : null}
+        </Box>
+      ) : null}
+      <Box marginTop={1}>
+        <Text dimColor>type to filter · ↑↓ pick · enter install · tab load more · esc quit</Text>
+      </Box>
+    </Box>
+  );
+}
+
+export interface McpBrowseOptions {
+  /** Reserved — currently unused, kept for symmetry with other commands. */
+  _unused?: never;
+}
+
+export async function mcpBrowseCommand(_opts: McpBrowseOptions = {}): Promise<void> {
+  loadDotenv();
+  const { waitUntilExit } = render(<McpBrowseApp />, {
+    exitOnCtrlC: true,
+    patchConsole: false,
+  });
+  await waitUntilExit();
+}

src/cli/commands/mcp-inspect.ts

@@ -35,6 +35,32 @@ export async function mcpInspectCommand(opts: McpInspectOptions): Promise<void>
   }
 }
 
+export function formatMcpInspectFailure(err: unknown): string {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const message = error.message;
+  const code = (error as NodeJS.ErrnoException).code;
+
+  if (code === "ENOENT") {
+    const command = message.match(/^spawn\s+([^\s]+)\s+ENOENT$/)?.[1] ?? "the command";
+    return `${message} — try: install or verify \`${command}\`, then check the MCP spec's command spelling`;
+  }
+
+  if (code === "ECONNREFUSED") {
+    const target = message.match(/\b(https?:\/\/\S+|\d+\.\d+\.\d+\.\d+:\d+|localhost:\d+)\b/i)?.[1];
+    return `${message} — try: confirm ${target ?? "the MCP server"} is running and the host/port match the spec`;
+  }
+
+  if (/^MCP request initialize \(id=\d+\) timed out after \d+ms$/.test(message)) {
+    return `${message} — try: confirm the target speaks MCP and completes the handshake before the request timeout`;
+  }
+
+  if (/^(empty MCP spec|MCP spec ".*" has name but no command)/.test(message)) {
+    return `${message} — try: pass \`name=command args\` or an http(s):// URL`;
+  }
+
+  return message;
+}
+
 function formatReport(nsName: string, r: InspectionReport): string {
   const lines: string[] = [];
   lines.push(`MCP server [${nsName}]`);

src/cli/commands/mcp.ts

@@ -1,33 +1,315 @@
+import { readConfig, writeConfig } from "../../config.js";
 import { MCP_CATALOG, mcpCommandFor } from "../../mcp/catalog.js";
+import {
+  type FetchProgress,
+  fetchSmitheryDetail,
+  handleToFetchResult,
+  loadMorePages,
+  openRegistry,
+  specStringFor,
+} from "../../mcp/registry-fetch.js";
+import type { RegistryEntry } from "../../mcp/registry-types.js";
 
-export interface McpListOptions {
-  /** Emit JSON on stdout instead of the human-readable table. */
-  json?: boolean;
+const DEFAULT_LIST_LIMIT = 30;
+/** Soft cap on how far `search` walks the registry on first run. */
+const SEARCH_PAGE_CAP = 20;
+/** Soft cap on how far `install` walks looking for a name. */
+const INSTALL_PAGE_CAP = 30;
+
+const progressToStderr: FetchProgress = ({ source, page, entries }) => {
+  if (page === 1 || page % 5 === 0) {
+    process.stderr.write(`\r▸ fetching ${source} registry · page ${page} · ${entries} entries`);
+  }
+};
+
+function finishProgressLine(): void {
+  if (process.stderr.isTTY) process.stderr.write("\r\x1b[K");
+  else process.stderr.write("\n");
 }
 
-export function mcpListCommand(opts: McpListOptions): void {
-  if (opts.json) {
-    console.log(JSON.stringify(MCP_CATALOG, null, 2));
-    return;
-  }
+export interface McpListOptions {
+  json?: boolean;
+  /** Skip network — only show the bundled MCP_CATALOG entries. */
+  local?: boolean;
+  /** Bypass cache TTL. */
+  refresh?: boolean;
+  /** How many entries to show. Default 30. */
+  limit?: number;
+  /** Eagerly load this many pages before showing. Default 1. */
+  pages?: number;
+  /** Walk all pages of the registry (slow on first run). */
+  all?: boolean;
+}
 
-  console.log("Popular MCP servers you can bridge into Reasonix:");
-  console.log("");
-  for (const entry of MCP_CATALOG) {
-    console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
-    console.log(`               ${mcpCommandFor(entry)}`);
-    if (entry.note) console.log(`               · ${entry.note}`);
-    console.log("");
-  }
-  console.log("Usage:  reasonix chat <one-of-the---mcp-lines-above>");
-  console.log(
-    "Docs:   https://github.com/modelcontextprotocol/servers  —  Anthropic's official server repo",
-  );
-  console.log(
-    "        https://mcp.so                                   —  community-maintained catalog",
-  );
+export interface McpSearchOptions {
+  json?: boolean;
+  refresh?: boolean;
+  limit?: number;
+  /** Cap how many pages to walk while searching. Default 20. */
+  maxPages?: number;
+}
+
+export interface McpInstallOptions {
+  refresh?: boolean;
+  /** Cap how many pages to walk while looking for the name. Default 30. */
+  maxPages?: number;
+}
+
+function rankEntries(entries: RegistryEntry[]): RegistryEntry[] {
+  return [...entries].sort((a, b) => {
+    const ap = a.popularity ?? -1;
+    const bp = b.popularity ?? -1;
+    if (ap !== bp) return bp - ap;
+    return a.name.localeCompare(b.name);
+  });
 }
 
 function pad(s: string, width: number): string {
   return s.length >= width ? s : s + " ".repeat(width - s.length);
 }
+
+function fmtAge(ms: number): string {
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+  if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`;
+  return `${Math.floor(sec / 86400)}d ago`;
+}
+
+function printEntry(e: RegistryEntry, indent = "  "): void {
+  const tag =
+    e.source === "official" ? "[official]" : e.source === "smithery" ? "[smithery]" : "[local]";
+  const pop = e.popularity !== undefined ? ` · ${e.popularity.toLocaleString()} uses` : "";
+  console.log(`${indent}${pad(e.name, 36)} ${tag}${pop}`);
+  if (e.description) console.log(`${indent}    ${e.description}`);
+  if (e.install?.requiredEnv?.length) {
+    console.log(`${indent}    needs: ${e.install.requiredEnv.join(", ")}`);
+  } else if (!e.install) {
+    console.log(`${indent}    (smithery listing — install detail fetched lazily on install)`);
+  }
+}
+
+export async function mcpListCommand(opts: McpListOptions = {}): Promise<void> {
+  if (opts.local) {
+    if (opts.json) {
+      console.log(JSON.stringify(MCP_CATALOG, null, 2));
+      return;
+    }
+    console.log("Bundled MCP servers (offline catalog):");
+    console.log("");
+    for (const entry of MCP_CATALOG) {
+      console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
+      console.log(`               ${mcpCommandFor(entry)}`);
+      if (entry.note) console.log(`               · ${entry.note}`);
+      console.log("");
+    }
+    return;
+  }
+
+  const handle = await openRegistry({ noCache: opts.refresh, onProgress: progressToStderr });
+  const wantedPages = opts.all ? Number.POSITIVE_INFINITY : (opts.pages ?? 1);
+  const additional = Math.max(0, wantedPages - handle.cache.pagination.pagesLoaded);
+  if (additional > 0) {
+    await loadMorePages(handle, {
+      pages: additional,
+      onProgress: progressToStderr,
+    });
+  }
+  finishProgressLine();
+
+  const result = handleToFetchResult(handle);
+  const ranked = rankEntries(result.entries);
+  const limit = opts.limit ?? DEFAULT_LIST_LIMIT;
+  const shown = ranked.slice(0, limit);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          source: result.source,
+          fromCache: result.fromCache,
+          fetchedAt: result.fetchedAt,
+          loaded: result.entries.length,
+          hasMore: result.hasMore,
+          entries: shown,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  const ageStr = result.fromCache
+    ? `cached, ${fmtAge(Date.now() - result.fetchedAt)}`
+    : "just fetched";
+  const moreStr = result.hasMore ? "more available" : "all loaded";
+  console.log(
+    `MCP servers from ${result.source} registry (${result.entries.length} loaded, ${moreStr}, ${ageStr}):`,
+  );
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.error(`  warn: ${e}`);
+  }
+  console.log("");
+  for (const e of shown) printEntry(e);
+  if (ranked.length > limit) {
+    console.log(
+      `  … ${ranked.length - limit} more loaded — use \`reasonix mcp search <query>\` to filter`,
+    );
+  }
+  if (result.hasMore) {
+    console.log("  ▸ more pages available — `reasonix mcp list --pages <n>` or --all");
+  }
+  console.log("");
+  console.log("Install:  reasonix mcp install <name>");
+}
+
+function matchFilter(query: string): (e: RegistryEntry) => boolean {
+  const q = query.toLowerCase();
+  return (e) => `${e.name} ${e.title} ${e.description}`.toLowerCase().includes(q);
+}
+
+export async function mcpSearchCommand(query: string, opts: McpSearchOptions = {}): Promise<void> {
+  const q = query.trim();
+  if (!q) {
+    console.error("usage: reasonix mcp search <query>");
+    process.exit(1);
+  }
+  const handle = await openRegistry({ noCache: opts.refresh, onProgress: progressToStderr });
+  const filter = matchFilter(q);
+  const limit = opts.limit ?? DEFAULT_LIST_LIMIT;
+  const cap = opts.maxPages ?? SEARCH_PAGE_CAP;
+
+  await loadMorePages(handle, {
+    pages: Math.max(0, cap - handle.cache.pagination.pagesLoaded),
+    matchTarget: limit,
+    filter,
+    onProgress: progressToStderr,
+  });
+  finishProgressLine();
+
+  const result = handleToFetchResult(handle);
+  const matches = rankEntries(result.entries.filter(filter));
+  const shown = matches.slice(0, limit);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          query: q,
+          source: result.source,
+          loaded: result.entries.length,
+          hasMore: result.hasMore,
+          matches: matches.length,
+          entries: shown,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (shown.length === 0) {
+    console.log(
+      `No matches for "${q}" across ${result.entries.length} loaded entries (${result.source}${
+        result.hasMore ? ", more pages exist — try --refresh or `mcp list --all`" : ""
+      }).`,
+    );
+    return;
+  }
+  console.log(
+    `${matches.length} match(es) for "${q}" in ${result.source} registry (${result.entries.length} entries scanned):`,
+  );
+  console.log("");
+  for (const e of shown) printEntry(e);
+  if (matches.length > limit) console.log(`  … ${matches.length - limit} more matches`);
+}
+
+function findEntry(entries: RegistryEntry[], name: string): RegistryEntry | null {
+  const exact = entries.find((e) => e.name === name);
+  if (exact) return exact;
+  const lower = name.toLowerCase();
+  const ci = entries.find((e) => e.name.toLowerCase() === lower);
+  if (ci) return ci;
+  const tail = entries.find((e) => e.name.toLowerCase().endsWith(`/${lower}`));
+  if (tail) return tail;
+  return null;
+}
+
+export async function mcpInstallCommand(name: string, opts: McpInstallOptions = {}): Promise<void> {
+  const target = name.trim();
+  if (!target) {
+    console.error("usage: reasonix mcp install <name>");
+    process.exit(1);
+  }
+
+  const handle = await openRegistry({ noCache: opts.refresh, onProgress: progressToStderr });
+  const lower = target.toLowerCase();
+  const filter = (e: RegistryEntry): boolean => {
+    const n = e.name.toLowerCase();
+    return n === lower || n.endsWith(`/${lower}`) || n.includes(lower);
+  };
+  const cap = opts.maxPages ?? INSTALL_PAGE_CAP;
+
+  await loadMorePages(handle, {
+    pages: Math.max(0, cap - handle.cache.pagination.pagesLoaded),
+    matchTarget: 1,
+    filter,
+    onProgress: progressToStderr,
+  });
+  finishProgressLine();
+
+  const entry = findEntry(handle.cache.entries, target);
+  if (!entry) {
+    console.error(
+      `No MCP server named "${target}" found after walking ${handle.cache.pagination.pagesLoaded} page(s) of the ${handle.source} registry.`,
+    );
+    if (handle.cache.pagination.nextCursor !== null) {
+      console.error(`Try: reasonix mcp install ${target} --max-pages 100`);
+    }
+    process.exit(1);
+  }
+
+  if (!entry.install && entry.source === "smithery") {
+    process.stderr.write(`▸ fetching smithery install detail for ${entry.name}…\n`);
+    const fetched = await fetchSmitheryDetail(entry.name);
+    if (fetched) entry.install = fetched;
+  }
+
+  if (!entry.install) {
+    console.error(
+      `Could not derive install metadata for "${entry.name}" — try \`npx -y @smithery/cli install ${entry.name}\` directly.`,
+    );
+    process.exit(1);
+  }
+
+  let spec: string;
+  try {
+    spec = specStringFor(entry.name, entry.install);
+  } catch (err) {
+    console.error(`Cannot build install spec for ${entry.name}: ${(err as Error).message}`);
+    process.exit(1);
+  }
+
+  const cfg = readConfig();
+  const existing = cfg.mcp ?? [];
+  if (existing.includes(spec)) {
+    console.log(`Already installed: ${spec}`);
+    return;
+  }
+  const next = { ...cfg, mcp: [...existing, spec] };
+  writeConfig(next);
+
+  console.log(`Installed: ${entry.name}`);
+  console.log(`  spec:    ${spec}`);
+  if (entry.install.requiredEnv?.length) {
+    console.log(
+      `  needs:   ${entry.install.requiredEnv.join(", ")}  (set these in your env before next chat)`,
+    );
+  }
+  console.log("");
+  console.log(
+    "Use it:  reasonix chat   (or `reasonix code`) — the server will be bridged automatically.",
+  );
+}

src/cli/commands/prune-sessions.ts

@@ -0,0 +1,38 @@
+import { listSessions, pruneStaleSessions } from "../../memory/session.js";
+
+export interface PruneSessionsOptions {
+  days?: number;
+  dryRun?: boolean;
+}
+
+export function pruneSessionsCommand(opts: PruneSessionsOptions): void {
+  const days = opts.days ?? 90;
+  if (!Number.isFinite(days) || days < 1) {
+    console.error(`--days must be a positive integer (got ${days}).`);
+    process.exit(1);
+  }
+  if (opts.dryRun) {
+    const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+    const stale = listSessions().filter((s) => s.mtime.getTime() < cutoff);
+    if (stale.length === 0) {
+      console.log(`no sessions idle ≥${days} days. Nothing would be pruned.`);
+      return;
+    }
+    console.log(`would prune ${stale.length} session(s) idle ≥${days} days:`);
+    for (const s of stale) {
+      console.log(`  ${s.name}`);
+    }
+    console.log("");
+    console.log("re-run without --dry-run to actually delete.");
+    return;
+  }
+  const removed = pruneStaleSessions(days);
+  if (removed.length === 0) {
+    console.log(`no sessions idle ≥${days} days. Nothing pruned.`);
+    return;
+  }
+  console.log(`pruned ${removed.length} session(s) idle ≥${days} days:`);
+  for (const name of removed) {
+    console.log(`  ${name}`);
+  }
+}

src/cli/index.ts

@@ -34,8 +34,10 @@ import { diffCommand } from "./commands/diff.js";
 import { doctorCommand } from "./commands/doctor.js";
 import { eventsCommand } from "./commands/events.js";
 import { indexCommand } from "./commands/index.js";
-import { mcpInspectCommand } from "./commands/mcp-inspect.js";
-import { mcpListCommand } from "./commands/mcp.js";
+import { mcpBrowseCommand } from "./commands/mcp-browse.js";
+import { formatMcpInspectFailure, mcpInspectCommand } from "./commands/mcp-inspect.js";
+import { mcpInstallCommand, mcpListCommand, mcpSearchCommand } from "./commands/mcp.js";
+import { pruneSessionsCommand } from "./commands/prune-sessions.js";
 import { replayCommand } from "./commands/replay.js";
 import { runCommand } from "./commands/run.js";
 import { sessionsCommand } from "./commands/sessions.js";
@@ -262,6 +264,15 @@ program
     sessionsCommand({ name, verbose: !!opts.verbose });
   });
 
+program
+  .command("prune-sessions")
+  .description(t("cli.pruneSessions"))
+  .option("--days <n>", t("ui.pruneDaysHint"), (v) => Number.parseInt(v, 10))
+  .option("--dry-run", t("ui.pruneDryRunHint"))
+  .action((opts) => {
+    pruneSessionsCommand({ days: opts.days, dryRun: !!opts.dryRun });
+  });
+
 program
   .command("events <name>")
   .description(t("cli.events"))
@@ -322,8 +333,77 @@ mcp
   .command("list")
   .description(t("ui.mcpListDescription"))
   .option("--json", t("ui.jsonHintCatalog"))
-  .action((opts) => {
-    mcpListCommand({ json: !!opts.json });
+  .option("--local", t("ui.mcpLocalHint"))
+  .option("--refresh", t("ui.mcpRefreshHint"))
+  .option("--limit <n>", t("ui.mcpLimitHint"), (v) => Number.parseInt(v, 10))
+  .option("--pages <n>", t("ui.mcpPagesHint"), (v) => Number.parseInt(v, 10))
+  .option("--all", t("ui.mcpAllHint"))
+  .action(async (opts) => {
+    try {
+      await mcpListCommand({
+        json: !!opts.json,
+        local: !!opts.local,
+        refresh: !!opts.refresh,
+        limit: typeof opts.limit === "number" && opts.limit > 0 ? opts.limit : undefined,
+        pages: typeof opts.pages === "number" && opts.pages > 0 ? opts.pages : undefined,
+        all: !!opts.all,
+      });
+    } catch (err) {
+      process.stderr.write(`mcp list failed: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
+  });
+
+mcp
+  .command("search <query>")
+  .description(t("ui.mcpSearchDescription"))
+  .option("--json", t("ui.jsonHintCatalog"))
+  .option("--refresh", t("ui.mcpRefreshHint"))
+  .option("--limit <n>", t("ui.mcpLimitHint"), (v) => Number.parseInt(v, 10))
+  .option("--max-pages <n>", t("ui.mcpMaxPagesHint"), (v) => Number.parseInt(v, 10))
+  .action(async (query: string, opts) => {
+    try {
+      await mcpSearchCommand(query, {
+        json: !!opts.json,
+        refresh: !!opts.refresh,
+        limit: typeof opts.limit === "number" && opts.limit > 0 ? opts.limit : undefined,
+        maxPages:
+          typeof opts.maxPages === "number" && opts.maxPages > 0 ? opts.maxPages : undefined,
+      });
+    } catch (err) {
+      process.stderr.write(`mcp search failed: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
+  });
+
+mcp
+  .command("install <name>")
+  .description(t("ui.mcpInstallDescription"))
+  .option("--refresh", t("ui.mcpRefreshHint"))
+  .option("--max-pages <n>", t("ui.mcpMaxPagesHint"), (v) => Number.parseInt(v, 10))
+  .action(async (name: string, opts) => {
+    try {
+      await mcpInstallCommand(name, {
+        refresh: !!opts.refresh,
+        maxPages:
+          typeof opts.maxPages === "number" && opts.maxPages > 0 ? opts.maxPages : undefined,
+      });
+    } catch (err) {
+      process.stderr.write(`mcp install failed: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
+  });
+
+mcp
+  .command("browse")
+  .description(t("ui.mcpBrowseDescription"))
+  .action(async () => {
+    try {
+      await mcpBrowseCommand();
+    } catch (err) {
+      process.stderr.write(`mcp browse failed: ${(err as Error).message}\n`);
+      process.exit(1);
+    }
   });
 
 mcp
@@ -334,7 +414,7 @@ mcp
     try {
       await mcpInspectCommand({ spec, json: !!opts.json });
     } catch (err) {
-      process.stderr.write(`mcp inspect failed: ${(err as Error).message}\n`);
+      process.stderr.write(`mcp inspect failed: ${formatMcpInspectFailure(err)}\n`);
       process.exit(1);
     }
   });

src/cli/ui/ChromeBar.tsx

@@ -1,259 +0,0 @@
-import { Box, Text, useStdout } from "ink";
-// biome-ignore lint/style/useImportType: tsconfig jsx=react needs React in value scope for JSX compilation
-import React from "react";
-import stringWidth from "string-width";
-import type { SessionSummary } from "../../telemetry/stats.js";
-import { ChromeRule } from "./primitives.js";
-import { COLOR, GRADIENT } from "./theme.js";
-
-const COLD_START_TURNS = 3;
-const CACHE_BAR_CELLS = 10;
-
-export type Preset = "auto" | "flash" | "pro";
-
-export interface ChromeBarProps {
-  summary: SessionSummary;
-  rootDir?: string;
-  sessionName?: string | null;
-  preset?: Preset;
-  planMode?: boolean;
-  proArmed?: boolean;
-  escalated?: boolean;
-  updateAvailable?: string | null;
-  balance?: { currency: string; total: number } | null;
-  budgetUsd?: number | null;
-  /** Scroll progress: 0 = at latest, 1 = at oldest. Hides the pill at 0. */
-  scrollRatio?: number;
-}
-
-export function ChromeBar(props: ChromeBarProps): React.ReactElement {
-  const { stdout } = useStdout();
-  const cols = (stdout?.columns ?? 80) - 2; // subtract paddingX={1} on both sides
-  const cold = props.summary.turns <= COLD_START_TURNS;
-  const projectName = props.rootDir ? basename(props.rootDir) : null;
-  const mode = pickModePill(props.planMode, props.preset);
-  const proPill = props.escalated
-    ? { label: "⇧ pro", color: COLOR.err }
-    : props.proArmed
-      ? { label: "⇧ pro", color: COLOR.warn }
-      : null;
-
-  // Greedy width-aware fit. Layout (each gap is exactly ONE space — single
-  // suffix on update/mode/pro/scroll, single prefix on balance/cache):
-  //   [brand][·project][›session]<spacer>[scroll][update][mode][pro]$cost  w bal cache █▓▓▓
-  // Always-shown carve out the budget first; optional pieces are dropped
-  // by priority — balance > cache > session > update — until the row fits.
-  // (`flexGrow` spacer can shrink to 0, so no minimum reserve.) Cache is
-  // shown unconditionally now: pre-turn-4 it renders dim with a "—" so
-  // it's "default on" instead of materializing only after a few turns.
-  const SEP = 3; // " · " / " › "
-  const GAP = 1;
-  const scrollLabel =
-    props.scrollRatio !== undefined && props.scrollRatio > 0
-      ? `[↑ ${Math.round(props.scrollRatio * 100)}%]`
-      : "";
-  const updateLabel = props.updateAvailable ? `↑ ${props.updateAvailable}` : "";
-  const balanceLabel = props.balance ? formatBalanceLabel(props.balance) : "";
-  const cachePct = Math.round(props.summary.cacheHitRatio * 100);
-  // Use the worst-case rendered cache string (3-digit pct, full bar) so the
-  // shed decision doesn't oscillate as the percentage changes turn-to-turn.
-  const cacheLabel = `cache ${"█".repeat(CACHE_BAR_CELLS)} 100%`;
-  const costLabel = `$${props.summary.totalCostUsd.toFixed(4)}${
-    props.budgetUsd && props.budgetUsd > 0 ? ` / $${props.budgetUsd.toFixed(2)}` : ""
-  }`;
-
-  const brandW = stringWidth("◈ reasonix");
-  const projectW = projectName ? SEP + stringWidth(projectName) : 0;
-  const fixedLeft = brandW + projectW;
-  const scrollW = scrollLabel ? stringWidth(scrollLabel) + GAP : 0;
-  const modeW = mode ? stringWidth(`[${mode.label}]`) + GAP : 0;
-  const proW = proPill ? stringWidth(`[${proPill.label}]`) + GAP : 0;
-  const costW = stringWidth(costLabel);
-  const fixedRight = scrollW + modeW + proW + costW;
-  let budget = cols - fixedLeft - fixedRight;
-
-  const balanceOptW = balanceLabel ? GAP + stringWidth(balanceLabel) : 0;
-  const cacheOptW = GAP + stringWidth(cacheLabel);
-  const sessionOptW = props.sessionName ? SEP + stringWidth(props.sessionName) : 0;
-  const updateOptW = updateLabel ? stringWidth(updateLabel) + GAP : 0;
-
-  const showBalance = balanceOptW > 0 && budget >= balanceOptW;
-  if (showBalance) budget -= balanceOptW;
-  const showCache = budget >= cacheOptW;
-  if (showCache) budget -= cacheOptW;
-  const showSession = sessionOptW > 0 && budget >= sessionOptW;
-  if (showSession) budget -= sessionOptW;
-  const showUpdate = updateOptW > 0 && budget >= updateOptW;
-  if (showUpdate) budget -= updateOptW;
-
-  return (
-    <Box flexDirection="column" paddingX={1}>
-      <Box>
-        <Text bold color={GRADIENT[0]}>
-          {"◈ "}
-        </Text>
-        <Text color={COLOR.brand} bold>
-          reasonix
-        </Text>
-        {projectName ? (
-          <>
-            <Text color={COLOR.info} dimColor>
-              {" · "}
-            </Text>
-            <Text>{projectName}</Text>
-            {showSession && props.sessionName ? (
-              <>
-                <Text color={COLOR.info} dimColor>
-                  {" › "}
-                </Text>
-                <Text color={COLOR.info}>{props.sessionName}</Text>
-              </>
-            ) : null}
-          </>
-        ) : null}
-
-        <Box flexGrow={1} />
-
-        {scrollLabel ? (
-          <>
-            <Text color={COLOR.accent} bold>
-              {scrollLabel}
-            </Text>
-            <Text> </Text>
-          </>
-        ) : null}
-        {showUpdate ? (
-          <>
-            <Text color={COLOR.warn} bold>
-              {updateLabel}
-            </Text>
-            <Text> </Text>
-          </>
-        ) : null}
-        {mode ? (
-          <>
-            <Text color={mode.color} bold>
-              {`[${mode.label}]`}
-            </Text>
-            <Text> </Text>
-          </>
-        ) : null}
-        {proPill ? (
-          <>
-            <Text color={proPill.color} bold>
-              {`[${proPill.label}]`}
-            </Text>
-            <Text> </Text>
-          </>
-        ) : null}
-        <CostPill summary={props.summary} cold={cold} budgetUsd={props.budgetUsd} />
-        {showBalance && props.balance ? (
-          <>
-            <Text> </Text>
-            <BalancePill balance={props.balance} />
-          </>
-        ) : null}
-        {showCache ? (
-          <>
-            <Text> </Text>
-            <CachePill ratio={props.summary.cacheHitRatio} cold={cold} pct={cachePct} />
-          </>
-        ) : null}
-      </Box>
-      <ChromeRule />
-    </Box>
-  );
-}
-
-function formatBalanceLabel(balance: { currency: string; total: number }): string {
-  const sym = balance.currency === "USD" ? "$" : balance.currency === "CNY" ? "¥" : "";
-  const suf = sym ? "" : ` ${balance.currency}`;
-  return `w ${sym}${balance.total.toFixed(2)}${suf}`;
-}
-
-function CostPill({
-  summary,
-  cold,
-  budgetUsd,
-}: {
-  summary: SessionSummary;
-  cold: boolean;
-  budgetUsd?: number | null;
-}): React.ReactElement {
-  const cost = summary.totalCostUsd;
-  const color = cold ? COLOR.info : sessionCostColor(cost);
-  return (
-    <>
-      <Text color={color} bold={!cold} dimColor={cold}>
-        {`$${cost.toFixed(4)}`}
-      </Text>
-      {budgetUsd && budgetUsd > 0 ? (
-        <Text color={COLOR.info} dimColor>
-          {` / $${budgetUsd.toFixed(2)}`}
-        </Text>
-      ) : null}
-    </>
-  );
-}
-
-function BalancePill({
-  balance,
-}: {
-  balance: { currency: string; total: number };
-}): React.ReactElement {
-  const { total } = balance;
-  const color = total < 1 ? COLOR.err : total < 5 ? COLOR.warn : COLOR.ok;
-  return <Text color={color}>{formatBalanceLabel(balance)}</Text>;
-}
-
-function CachePill({
-  ratio,
-  cold,
-  pct,
-}: {
-  ratio: number;
-  cold: boolean;
-  pct: number;
-}): React.ReactElement {
-  const color = ratio >= 0.7 ? COLOR.ok : ratio >= 0.4 ? COLOR.warn : COLOR.err;
-  const filled = Math.max(0, Math.min(CACHE_BAR_CELLS, Math.round(ratio * CACHE_BAR_CELLS)));
-  const empty = CACHE_BAR_CELLS - filled;
-  return (
-    <>
-      <Text color={COLOR.info} dimColor>
-        {"cache "}
-      </Text>
-      <Text color={cold ? COLOR.info : color} dimColor={cold}>
-        {"█".repeat(filled)}
-      </Text>
-      <Text dimColor>{"░".repeat(empty)}</Text>
-      <Text color={cold ? undefined : color} bold={!cold} dimColor={cold}>
-        {cold && pct === 0 ? " —" : ` ${pct}%`}
-      </Text>
-    </>
-  );
-}
-
-function pickModePill(
-  planMode: boolean | undefined,
-  preset: Preset | undefined,
-): { label: string; color: string } | null {
-  if (planMode) return { label: "PLAN", color: COLOR.err };
-  if (!preset) return null;
-  if (preset === "pro") return { label: "pro", color: COLOR.accent };
-  if (preset === "flash") return { label: "flash", color: COLOR.info };
-  return { label: "auto", color: COLOR.primary };
-}
-
-function sessionCostColor(cost: number): string | undefined {
-  if (cost <= 0) return undefined;
-  if (cost >= 5) return COLOR.err;
-  if (cost >= 0.5) return COLOR.warn;
-  return COLOR.ok;
-}
-
-function basename(path: string): string {
-  const norm = path.replace(/\\/g, "/");
-  const i = norm.lastIndexOf("/");
-  return i === -1 ? norm : norm.slice(i + 1);
-}

src/cli/ui/McpHub.tsx

@@ -0,0 +1,84 @@
+/** `/mcp` slash modal — single hub with two tabs: Live (attached servers) + Marketplace (registry). */
+
+import { Box, Text } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig jsx=react needs React in value scope for JSX compilation
+import React, { useState } from "react";
+import { McpBrowser } from "./McpBrowser.js";
+import { McpMarketplace } from "./McpMarketplace.js";
+import { useKeystroke } from "./keystroke-context.js";
+import type { ApplyAppend } from "./mcp-reconnect-kickoff.js";
+import type { McpServerSummary } from "./slash/types.js";
+import { COLOR } from "./theme.js";
+
+export type McpHubTab = "live" | "marketplace";
+
+export interface McpHubProps {
+  initialTab: McpHubTab;
+  liveServers: McpServerSummary[];
+  configPath: string;
+  onClose: () => void;
+  postInfo: (text: string) => void;
+  applyAppend?: ApplyAppend;
+  reloadMcp?: () => Promise<{
+    added: string[];
+    removed: string[];
+    failed: Array<{ spec: string; reason: string }>;
+  }>;
+}
+
+export function McpHub({
+  initialTab,
+  liveServers,
+  configPath,
+  onClose,
+  postInfo,
+  applyAppend,
+  reloadMcp,
+}: McpHubProps) {
+  const [tab, setTab] = useState<McpHubTab>(initialTab);
+
+  // Hub-level: Tab key cycles tabs. Inner components don't bind Tab
+  // (Marketplace rebound to PgDn for load-more) so no conflict.
+  useKeystroke((ev) => {
+    if (ev.paste) return;
+    if (ev.tab) setTab((t) => (t === "live" ? "marketplace" : "live"));
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Box paddingX={1}>
+        <Text bold color={COLOR.brand}>
+          ◈ MCP
+        </Text>
+        <Text>{"  "}</Text>
+        <TabPill label="Live" count={liveServers.length} active={tab === "live"} />
+        <Text>{"  "}</Text>
+        <TabPill label="Marketplace" active={tab === "marketplace"} />
+        <Text dimColor>{"   tab to switch"}</Text>
+      </Box>
+      {tab === "live" ? (
+        <McpBrowser
+          servers={liveServers}
+          configPath={configPath}
+          onClose={onClose}
+          postInfo={postInfo}
+          applyAppend={applyAppend}
+        />
+      ) : (
+        <McpMarketplace onClose={onClose} postInfo={postInfo} reloadMcp={reloadMcp} />
+      )}
+    </Box>
+  );
+}
+
+function TabPill({ label, count, active }: { label: string; count?: number; active: boolean }) {
+  const text = count !== undefined ? `${label} (${count})` : label;
+  if (active) {
+    return (
+      <Text bold color={COLOR.brand}>
+        [{text}]
+      </Text>
+    );
+  }
+  return <Text dimColor>{` ${text} `}</Text>;
+}

src/cli/ui/McpMarketplace.tsx

@@ -0,0 +1,319 @@
+/** `/mcp browse` modal — registry marketplace inside the chat session. */
+
+import { Box, Text } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig jsx=react needs React in value scope for JSX compilation
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import { readConfig, writeConfig } from "../../config.js";
+import {
+  type RegistryHandle,
+  fetchSmitheryDetail,
+  loadMorePages,
+  openRegistry,
+  specStringFor,
+} from "../../mcp/registry-fetch.js";
+import type { RegistryEntry } from "../../mcp/registry-types.js";
+import { useKeystroke } from "./keystroke-context.js";
+import { COLOR } from "./theme.js";
+
+const VISIBLE_ROWS = 10;
+
+export interface McpMarketplaceProps {
+  onClose: () => void;
+  /** Pushed back into the chat scrollback after install/uninstall. */
+  postInfo: (text: string) => void;
+  /** Optional hot-reload — present in chat session, absent in standalone CLI use. */
+  reloadMcp?: () => Promise<{
+    added: string[];
+    removed: string[];
+    failed: Array<{ spec: string; reason: string }>;
+  }>;
+}
+
+interface State {
+  handle: RegistryHandle | null;
+  loading: boolean;
+  query: string;
+  selected: number;
+  status: string;
+  /** specs currently in config.mcp[] — refreshed after install/uninstall. */
+  installedSpecs: string[];
+}
+
+function rankAndFilter(entries: RegistryEntry[], query: string): RegistryEntry[] {
+  const q = query.trim().toLowerCase();
+  const list = q
+    ? entries.filter((e) => `${e.name} ${e.title} ${e.description}`.toLowerCase().includes(q))
+    : entries;
+  return [...list].sort((a, b) => {
+    const ap = a.popularity ?? -1;
+    const bp = b.popularity ?? -1;
+    if (ap !== bp) return bp - ap;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function readInstalledSpecs(): string[] {
+  return readConfig().mcp ?? [];
+}
+
+function isInstalled(installedSpecs: string[], entry: RegistryEntry): string | null {
+  if (!entry.install) return null;
+  try {
+    const spec = specStringFor(entry.name, entry.install);
+    return installedSpecs.includes(spec) ? spec : null;
+  } catch {
+    return null;
+  }
+}
+
+export function McpMarketplace({ onClose, postInfo, reloadMcp }: McpMarketplaceProps) {
+  const [state, setState] = useState<State>({
+    handle: null,
+    loading: true,
+    query: "",
+    selected: 0,
+    status: "opening registry…",
+    installedSpecs: readInstalledSpecs(),
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const handle = await openRegistry({});
+        if (cancelled) return;
+        setState((s) => ({
+          ...s,
+          handle,
+          loading: false,
+          status: `${handle.source} · ${handle.cache.entries.length} entries${
+            handle.fromCache ? " · cached" : ""
+          }`,
+        }));
+      } catch (err) {
+        if (cancelled) return;
+        setState((s) => ({ ...s, loading: false, status: `error: ${(err as Error).message}` }));
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const filtered = useMemo(() => {
+    if (!state.handle) return [];
+    return rankAndFilter(state.handle.cache.entries, state.query);
+  }, [state.handle, state.query]);
+
+  const selected = filtered[state.selected];
+
+  const fetchMore = useCallback(async () => {
+    if (!state.handle || state.loading) return;
+    if (state.handle.cache.pagination.nextCursor === null) {
+      setState((s) => ({ ...s, status: "all pages loaded" }));
+      return;
+    }
+    setState((s) => ({ ...s, loading: true, status: "loading more…" }));
+    try {
+      const r = await loadMorePages(state.handle, { pages: 5 });
+      setState((s) => ({
+        ...s,
+        loading: false,
+        status: `+${r.newEntries} · ${state.handle?.cache.entries.length ?? 0} total${
+          r.exhausted ? " · exhausted" : ""
+        }`,
+      }));
+    } catch (err) {
+      setState((s) => ({ ...s, loading: false, status: `error: ${(err as Error).message}` }));
+    }
+  }, [state.handle, state.loading]);
+
+  const installOrToggle = useCallback(
+    async (entry: RegistryEntry) => {
+      const installed = isInstalled(state.installedSpecs, entry);
+      if (installed) {
+        const cfg = readConfig();
+        const next = (cfg.mcp ?? []).filter((s) => s !== installed);
+        writeConfig({ ...cfg, mcp: next });
+        setState((s) => ({
+          ...s,
+          installedSpecs: next,
+          status: `uninstalled ${entry.name}`,
+        }));
+        if (reloadMcp) {
+          try {
+            await reloadMcp();
+            postInfo(`✓ uninstalled ${entry.name} — bridge dropped`);
+          } catch (err) {
+            postInfo(
+              `✓ uninstalled ${entry.name} — restart \`reasonix code\` to drop the bridge (reload failed: ${(err as Error).message})`,
+            );
+          }
+        } else {
+          postInfo(`✓ uninstalled ${entry.name} — restart \`reasonix code\` to drop the bridge`);
+        }
+        return;
+      }
+
+      let install = entry.install;
+      if (!install && entry.source === "smithery") {
+        setState((s) => ({ ...s, loading: true, status: "fetching smithery detail…" }));
+        try {
+          const detail = await fetchSmitheryDetail(entry.name);
+          if (detail) {
+            install = detail;
+            entry.install = detail;
+          }
+        } catch {
+          /* fall through to error below */
+        }
+        setState((s) => ({ ...s, loading: false }));
+      }
+      if (!install) {
+        setState((s) => ({
+          ...s,
+          status: `no install info for ${entry.name} — try \`npx -y @smithery/cli install ${entry.name}\``,
+        }));
+        return;
+      }
+
+      try {
+        const spec = specStringFor(entry.name, install);
+        const cfg = readConfig();
+        const existing = cfg.mcp ?? [];
+        if (existing.includes(spec)) {
+          setState((s) => ({
+            ...s,
+            installedSpecs: existing,
+            status: `already installed: ${spec}`,
+          }));
+          return;
+        }
+        const next = [...existing, spec];
+        writeConfig({ ...cfg, mcp: next });
+        setState((s) => ({ ...s, installedSpecs: next, status: `installed → ${spec}` }));
+        const envHint = install.requiredEnv?.length
+          ? `  ·  needs env: ${install.requiredEnv.join(", ")}`
+          : "";
+        if (reloadMcp) {
+          try {
+            const r = await reloadMcp();
+            const failedHere = r.failed.find((f) => f.spec === spec);
+            if (failedHere) {
+              postInfo(`▲ installed ${entry.name} — bridge failed: ${failedHere.reason}${envHint}`);
+            } else {
+              postInfo(`✓ installed ${entry.name} — bridged${envHint}`);
+            }
+          } catch (err) {
+            postInfo(
+              `✓ installed ${entry.name} — restart \`reasonix code\` to bridge (reload failed: ${(err as Error).message})${envHint}`,
+            );
+          }
+        } else {
+          postInfo(`✓ installed ${entry.name} — restart \`reasonix code\` to bridge${envHint}`);
+        }
+      } catch (err) {
+        setState((s) => ({ ...s, status: `install failed: ${(err as Error).message}` }));
+      }
+    },
+    [state.installedSpecs, postInfo, reloadMcp],
+  );
+
+  useKeystroke((ev) => {
+    if (ev.paste) return;
+    if (ev.escape) {
+      onClose();
+      return;
+    }
+    if (ev.upArrow) {
+      setState((s) => ({ ...s, selected: Math.max(0, s.selected - 1) }));
+      return;
+    }
+    if (ev.downArrow) {
+      setState((s) => ({ ...s, selected: Math.min(filtered.length - 1, s.selected + 1) }));
+      return;
+    }
+    if (ev.return) {
+      if (selected) void installOrToggle(selected);
+      return;
+    }
+    if (ev.pageDown) {
+      void fetchMore();
+      return;
+    }
+    if (ev.backspace || ev.delete) {
+      setState((s) => ({ ...s, query: s.query.slice(0, -1), selected: 0 }));
+      return;
+    }
+    if (ev.input && !ev.ctrl && !ev.meta) {
+      setState((s) => ({ ...s, query: s.query + ev.input, selected: 0 }));
+    }
+  });
+
+  const start = Math.max(
+    0,
+    Math.min(state.selected - Math.floor(VISIBLE_ROWS / 2), filtered.length - VISIBLE_ROWS),
+  );
+  const window = filtered.slice(Math.max(0, start), Math.max(0, start) + VISIBLE_ROWS);
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Box>
+        <Text bold color={COLOR.brand}>
+          ◈ MCP marketplace
+        </Text>
+        <Text dimColor>{`  ·  ${state.status}`}</Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text>filter: </Text>
+        <Text>{state.query || "(type to filter)"}</Text>
+        <Text dimColor>{`  ${filtered.length} match${filtered.length === 1 ? "" : "es"}`}</Text>
+      </Box>
+      <Box marginTop={1} flexDirection="column">
+        {window.length === 0 ? (
+          <Text dimColor>{state.loading ? "loading…" : "no entries"}</Text>
+        ) : (
+          window.map((e, i) => {
+            const idx = (start || 0) + i;
+            const active = idx === state.selected;
+            const tag =
+              e.source === "official" ? "[off]" : e.source === "smithery" ? "[smt]" : "[loc]";
+            const installedSpec = isInstalled(state.installedSpecs, e);
+            const installedBadge = installedSpec ? " ✓" : "";
+            const pop = e.popularity !== undefined ? ` · ${e.popularity.toLocaleString()}` : "";
+            return (
+              <Box key={e.name}>
+                <Text color={active ? COLOR.brand : undefined}>{active ? "▸ " : "  "}</Text>
+                <Text bold={active}>{e.name.padEnd(38).slice(0, 38)}</Text>
+                <Text dimColor>{` ${tag}${pop}${installedBadge}`}</Text>
+              </Box>
+            );
+          })
+        )}
+      </Box>
+      {selected ? (
+        <Box marginTop={1} flexDirection="column">
+          <Text bold>{selected.title}</Text>
+          {selected.description ? <Text dimColor>{selected.description.slice(0, 200)}</Text> : null}
+          {selected.install ? (
+            <Text dimColor>
+              {`spec: ${selected.install.runtime} ${selected.install.packageId ?? selected.install.url ?? "—"} · ${selected.install.transport}`}
+            </Text>
+          ) : (
+            <Text dimColor>(smithery listing — install detail fetched on Enter)</Text>
+          )}
+          {selected.install?.requiredEnv?.length ? (
+            <Text color="yellow">{`needs: ${selected.install.requiredEnv.join(", ")}`}</Text>
+          ) : null}
+        </Box>
+      ) : null}
+      <Box marginTop={1}>
+        <Text dimColor>
+          type filter · ↑↓ pick · enter{" "}
+          {selected && isInstalled(state.installedSpecs, selected) ? "uninstall" : "install"} · PgDn
+          load more · esc close
+        </Text>
+      </Box>
+    </Box>
+  );
+}

src/cli/ui/PlanCheckpointConfirm.tsx

@@ -0,0 +1,96 @@
+/** Modal picker for `PlanCheckpointError`: continue / revise / stop. */
+
+import { Box } from "ink";
+// biome-ignore lint/style/useImportType: tsconfig jsx=react needs React in value scope for JSX compilation
+import React from "react";
+import type { PlanStep } from "../../tools/plan.js";
+import { PlanStepList, type StepStatus } from "./PlanStepList.js";
+import { SingleSelect } from "./Select.js";
+import { ApprovalCard } from "./cards/ApprovalCard.js";
+import { useReserveRows } from "./layout/viewport-budget.js";
+
+export type CheckpointChoice = "continue" | "revise" | "stop";
+
+export interface PlanCheckpointConfirmProps {
+  stepId: string;
+  title?: string;
+  completed: number;
+  total: number;
+  /** Full step list from the approved plan, when available. */
+  steps?: PlanStep[];
+  /** Set of stepIds the model has marked complete so far. */
+  completedStepIds?: Set<string>;
+  onChoose: (choice: CheckpointChoice) => void;
+}
+
+function PlanCheckpointConfirmInner({
+  stepId,
+  title,
+  completed,
+  total,
+  steps,
+  completedStepIds,
+  onChoose,
+}: PlanCheckpointConfirmProps) {
+  const stepRows = steps?.length ?? 0;
+  useReserveRows("modal", { min: 10, max: Math.max(14, stepRows + 12) });
+
+  const label = title ? `${stepId} · ${title}` : stepId;
+  const counter = total > 0 ? `${completed}/${total}` : "";
+  const isLast = total > 0 && completed >= total;
+  const statuses = buildStatusMap(steps, completedStepIds, stepId, isLast);
+  const subtitle = counter ? `${counter}  ·  ${label}` : label;
+  return (
+    <ApprovalCard tone="ok" glyph="⛁" title="Checkpoint — step done" metaRight={subtitle}>
+      {steps && steps.length > 0 ? (
+        <Box marginBottom={1} flexDirection="column">
+          <PlanStepList steps={steps} statuses={statuses} focusStepId={stepId} />
+        </Box>
+      ) : null}
+      <SingleSelect
+        initialValue={isLast ? "stop" : "continue"}
+        items={[
+          {
+            value: "continue",
+            label: "Continue — run the next step",
+            hint: "Model resumes with the next step.",
+          },
+          {
+            value: "revise",
+            label: "Revise — give feedback before the next step",
+            hint: "Stay paused, type guidance; model adjusts the remaining plan.",
+          },
+          {
+            value: "stop",
+            label: "Stop — end the plan here",
+            hint: "Model summarizes what was done and ends.",
+          },
+        ]}
+        onSubmit={(v) => onChoose(v as CheckpointChoice)}
+        onCancel={() => onChoose("stop")}
+      />
+    </ApprovalCard>
+  );
+}
+
+export const PlanCheckpointConfirm = React.memo(PlanCheckpointConfirmInner);
+
+/** Current step renders as "done" — flush order isn't guaranteed at picker time. */
+function buildStatusMap(
+  steps: PlanStep[] | undefined,
+  completedStepIds: Set<string> | undefined,
+  currentStepId: string,
+  isLast: boolean,
+): Map<string, StepStatus> {
+  const map = new Map<string, StepStatus>();
+  if (!steps) return map;
+  for (const step of steps) {
+    if (completedStepIds?.has(step.id) || step.id === currentStepId) {
+      map.set(step.id, "done");
+    } else {
+      map.set(step.id, "pending");
+    }
+  }
+  void isLast;
+  return map;
+}

src/cli/ui/PlanConfirm.tsx

@@ -8,7 +8,8 @@ import { PlanStepList } from "./PlanStepList.js";
 import { SingleSelect } from "./Select.js";
 import { ApprovalCard } from "./cards/ApprovalCard.js";
 import { useReserveRows } from "./layout/viewport-budget.js";
-import { CARD, TONE } from "./theme/tokens.js";
+import { MarkdownView } from "./markdown-view.js";
+import { CARD, FG, TONE } from "./theme/tokens.js";
 
 export type PlanConfirmChoice = "approve" | "refine" | "revise" | "cancel";
 
@@ -21,9 +22,19 @@ export interface PlanConfirmProps {
   projectRoot?: string;
 }
 
+const PLAN_BODY_PREVIEW_LINES = 24;
+
 function PlanConfirmInner({ plan, steps, onChoose }: PlanConfirmProps) {
   const stepRows = steps?.length ?? 0;
-  useReserveRows("modal", { min: 10, max: Math.max(16, stepRows + 14) });
+  const hasSteps = stepRows > 0;
+  const planLines = plan.split("\n");
+  const truncatedBody = planLines.length > PLAN_BODY_PREVIEW_LINES;
+  const previewBody = truncatedBody ? planLines.slice(0, PLAN_BODY_PREVIEW_LINES).join("\n") : plan;
+  const previewRows = truncatedBody
+    ? PLAN_BODY_PREVIEW_LINES
+    : Math.min(planLines.length, PLAN_BODY_PREVIEW_LINES);
+  const reservedFor = hasSteps ? stepRows : previewRows;
+  useReserveRows("modal", { min: 10, max: Math.max(16, reservedFor + 14) });
 
   const hasOpenQuestions =
     /^#{1,6}\s*(open[-\s]?questions?|risks?|unknowns?|assumptions?|unclear)/im.test(plan) ||
@@ -45,9 +56,20 @@ function PlanConfirmInner({ plan, steps, onChoose }: PlanConfirmProps) {
           </Text>
         </Box>
       ) : null}
-      {steps && steps.length > 0 ? (
+      {hasSteps ? (
         <Box marginBottom={1} flexDirection="column">
-          <PlanStepList steps={steps} />
+          <PlanStepList steps={steps!} />
+        </Box>
+      ) : plan.trim().length > 0 ? (
+        <Box marginBottom={1} flexDirection="column">
+          <MarkdownView text={previewBody} />
+          {truncatedBody ? (
+            <Text color={FG.faint}>
+              {`… ${planLines.length - PLAN_BODY_PREVIEW_LINES} more line${
+                planLines.length - PLAN_BODY_PREVIEW_LINES === 1 ? "" : "s"
+              } above in scrollback`}
+            </Text>
+          ) : null}
         </Box>
       ) : null}
       <SingleSelect

src/cli/ui/Select.tsx

@@ -19,6 +19,8 @@ export interface SingleSelectProps<V extends string> {
   initialValue?: V;
   onSubmit: (value: V) => void;
   onCancel?: () => void;
+  /** Fired when Tab is pressed on the currently highlighted item. */
+  onTab?: (value: V) => void;
   /** Optional dim footer beneath the list. */
   footer?: string;
 }
@@ -27,6 +29,7 @@ export function SingleSelect<V extends string>({
   items,
   initialValue,
   onSubmit,
+  onTab,
   onCancel,
   footer,
 }: SingleSelectProps<V>) {
@@ -45,6 +48,9 @@ export function SingleSelect<V extends string>({
     } else if (ev.return) {
       const chosen = items[index];
       if (chosen && !chosen.disabled) onSubmit(chosen.value);
+    } else if (ev.tab) {
+      const chosen = items[index];
+      if (chosen && !chosen.disabled) onTab?.(chosen.value);
     } else if (ev.escape && onCancel) {
       onCancel();
     }

src/cli/ui/ShellConfirm.tsx

@@ -35,7 +35,7 @@ export function ShellConfirm({ command, allowPrefix, kind, onChoose }: ShellConf
         glyph="✗"
         title="Deny — provide context"
         metaRight="optional"
-        footerHint="⏎ submit  ·  esc skip (deny without reason)"
+        footerHint="type context  ·  ⏎ submit with reason  ·  esc skip (deny without reason)"
       >
         <DenyContextInput
           onSubmit={(context) => onChoose("deny", context || undefined)}
@@ -51,7 +51,7 @@ export function ShellConfirm({ command, allowPrefix, kind, onChoose }: ShellConf
       glyph={isBackground ? "⏱" : "?"}
       title={isBackground ? "Background process" : "Shell command"}
       metaRight="awaiting"
-      footerHint="↑↓ pick  ·  ⏎ confirm  ·  esc cancel"
+      footerHint="↑↓ pick  ·  ⏎ confirm  ·  Tab add context  ·  esc cancel"
     >
       <Box marginBottom={1}>
         <Text color={FG.faint}>{subtitle}</Text>
@@ -80,13 +80,16 @@ export function ShellConfirm({ command, allowPrefix, kind, onChoose }: ShellConf
           {
             value: "deny",
             label: "deny",
-            hint: "skip; agent will pick an alternative",
+            hint: "press Tab to add context telling the model why",
           },
         ]}
         onSubmit={(v) => {
           if (v === "deny") setPhase("deny");
           else onChoose(v as ShellConfirmChoice);
         }}
+        onTab={(v) => {
+          if (v === "deny") setPhase("deny");
+        }}
         onCancel={() => onChoose("deny")}
       />
     </ApprovalCard>

src/cli/ui/SlashSuggestions.tsx

@@ -86,6 +86,7 @@ function SuggestionRow({ spec, isSelected }: { spec: SlashCommandSpec; isSelecte
   const key = `slash.${spec.cmd}.description`;
   const translated = t(key);
   const summary = translated === key ? spec.summary : translated;
+  const aliasHint = spec.aliases?.length ? ` · /${spec.aliases.join(" /")}` : "";
   return (
     <Box>
       <Text color={isSelected ? COLOR.primary : COLOR.info} bold={isSelected}>
@@ -99,6 +100,7 @@ function SuggestionRow({ spec, isSelected }: { spec: SlashCommandSpec; isSelecte
       <Text color={isSelected ? COLOR.user : COLOR.info} dimColor={!isSelected}>
         {summary}
       </Text>
+      {aliasHint ? <Text dimColor>{aliasHint}</Text> : null}
     </Box>
   );
 }

src/cli/ui/StatsPanel.tsx

@@ -6,6 +6,7 @@ import type { EditMode } from "../../config.js";
 import type { SessionSummary } from "../../telemetry/stats.js";
 import { Bar, ChromeRule } from "./primitives.js";
 import { COLOR, GRADIENT } from "./theme.js";
+import { formatBalance, formatCost } from "./theme/tokens.js";
 
 const COLD_START_TURNS = 3;
 
@@ -91,9 +92,9 @@ function ChromeRow({
   const cacheColor =
     summary.cacheHitRatio >= 0.7 ? COLOR.ok : summary.cacheHitRatio >= 0.4 ? COLOR.warn : COLOR.err;
   const balanceLabel = balance
-    ? `[w ${balance.currency === "USD" ? "$" : ""}${balance.total.toFixed(2)}${balance.currency !== "USD" ? ` ${balance.currency}` : ""}]`
+    ? `[${formatBalance(balance.total, balance.currency, { label: true })}]`
     : "";
-  const costLabel = `[$${summary.totalCostUsd.toFixed(4)}]`;
+  const costLabel = `[${formatCost(summary.totalCostUsd, balance?.currency)}]`;
   const cacheLabel = "[c ▰▰▰▰▰▰ 100%]";
   const updateLabel = updateAvailable ? `↑ ${updateAvailable}` : "";
 

src/cli/ui/Wizard.tsx

@@ -443,5 +443,8 @@ export function buildSpec(name: string, argsByName: Record<string, string>): str
 }
 
 function quoteIfNeeded(s: string): string {
-  return /\s|"/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+  // Escape backslashes BEFORE quotes — otherwise a trailing `\` in the
+  // input would consume the closing quote when a downstream parser
+  // un-escapes the output (CodeQL js/incomplete-sanitization).
+  return /\s|"/.test(s) ? `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : s;
 }

src/cli/ui/cards/UsageCard.tsx

@@ -4,7 +4,7 @@ import React from "react";
 import { Card } from "../primitives/Card.js";
 import { CardHeader } from "../primitives/CardHeader.js";
 import type { UsageCard as UsageCardData } from "../state/cards.js";
-import { FG, TONE, formatCNY } from "../theme/tokens.js";
+import { FG, TONE, formatBalance, formatCost } from "../theme/tokens.js";
 
 const BAR_CELLS = 30;
 
@@ -32,7 +32,7 @@ export function UsageCard({ card }: { card: UsageCardData }): React.ReactElement
   const reasonRatio = card.tokens.reason / cap;
   const outputRatio = card.tokens.output / cap;
 
-  const headerMeta: string[] = [`turn ${card.turn}`, formatCNY(card.cost)];
+  const headerMeta: string[] = [`turn ${card.turn}`, formatCost(card.cost, card.balanceCurrency)];
   if (card.elapsedMs !== undefined) headerMeta.push(`${(card.elapsedMs / 1000).toFixed(1)}s`);
   return (
     <Card tone={FG.meta}>
@@ -66,11 +66,15 @@ export function UsageCard({ card }: { card: UsageCardData }): React.ReactElement
       </Box>
       <Box flexDirection="row" gap={1}>
         <Text color={FG.faint}>session</Text>
-        <Text bold color={FG.body}>{`⛁ ${formatCNY(card.sessionCost, 3)}`}</Text>
+        <Text bold color={FG.body}>
+          {`⛁ ${formatCost(card.sessionCost, card.balanceCurrency, 3)}`}
+        </Text>
         {card.balance !== undefined ? (
           <>
             <Text color={FG.faint}>· balance</Text>
-            <Text bold color={TONE.brand}>{`¥${card.balance.toFixed(2)}`}</Text>
+            <Text bold color={TONE.brand}>
+              {formatBalance(card.balance, card.balanceCurrency)}
+            </Text>
           </>
         ) : null}
       </Box>
@@ -89,9 +93,9 @@ function CompactUsageRow({ card }: { card: UsageCardData }): React.ReactElement
       </Text>
       <Text color={FG.faint}>· cache</Text>
       <Text color={TONE.ok}>{`${(card.cacheHit * 100).toFixed(0)}%`}</Text>
-      <Text color={FG.faint}>{`· ${formatCNY(card.cost)}${elapsed}`}</Text>
+      <Text color={FG.faint}>{`· ${formatCost(card.cost, card.balanceCurrency)}${elapsed}`}</Text>
       {card.balance !== undefined ? (
-        <Text color={TONE.brand}>{`· ¥${card.balance.toFixed(2)}`}</Text>
+        <Text color={TONE.brand}>{`· ${formatBalance(card.balance, card.balanceCurrency)}`}</Text>
       ) : null}
     </Box>
   );

src/cli/ui/clipboard.ts

@@ -1,6 +1,6 @@
 /** OSC 52 clipboard write + temp-file fallback. */
 
-import { writeFileSync } from "node:fs";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -13,7 +13,11 @@ export interface ClipboardWrite {
 }
 
 export function writeClipboard(text: string): ClipboardWrite {
-  const filePath = join(tmpdir(), `reasonix-clip-${Date.now()}.txt`);
+  // mkdtemp creates a private 0700 directory atomically — keeps the
+  // file out of the shared tmp namespace where a sibling process can
+  // race or read it (CodeQL js/insecure-temporary-file).
+  const dir = mkdtempSync(join(tmpdir(), "reasonix-clip-"));
+  const filePath = join(dir, "clip.txt");
   let osc52 = false;
   if (text.length <= OSC_52_LIMIT) {
     const b64 = Buffer.from(text, "utf8").toString("base64");

src/cli/ui/ctx-breakdown.tsx

@@ -145,7 +145,7 @@ export function CtxBreakdownBlock({ data }: { data: CtxBreakdownData }): React.R
         </Box>
       ) : null}
       <Box marginTop={1}>
-        <Text dimColor>{"  /compact shrinks oversized tool results · /new wipes log"}</Text>
+        <Text dimColor>{"  /compact folds (auto at 50%) · /new wipes log"}</Text>
       </Box>
     </Box>
   );

src/cli/ui/hash-memory.ts

@@ -1,6 +1,6 @@
 /** `#` writes project memory, `#g` global; `##+` stays a markdown heading; `\#` escapes and submits the literal `#`. */
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, fstatSync, mkdirSync, openSync, readSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { PROJECT_MEMORY_FILE } from "../../memory/project.js";
@@ -79,18 +79,28 @@ function appendBulletToFile(path: string, note: string, newFileHeader: string):
   const trimmed = note.trim();
   if (!trimmed) throw new Error("note body cannot be empty");
   const bullet = `- ${trimmed}\n`;
-  if (!existsSync(path)) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${newFileHeader}${bullet}`, "utf8");
-    return { path, created: true };
-  }
-  let prefix = "";
+  mkdirSync(dirname(path), { recursive: true });
+  // One `a+` open covers both branches: O_APPEND lands every write
+  // atomically at end-of-file (concurrent appenders interleave whole
+  // bullets), O_CREAT creates the file when it's missing, and we use
+  // `fstat().size === 0` as the "we just created it" signal to decide
+  // whether to emit the file header. Single fd from open through
+  // write — no path-based check between (CodeQL js/file-system-race).
+  const fd = openSync(path, "a+");
   try {
-    const existing = readFileSync(path, "utf8");
-    if (existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
-  } catch {
-    // Unreadable but exists — let appendFileSync surface the real error.
+    const stat = fstatSync(fd);
+    if (stat.size === 0) {
+      writeSync(fd, `${newFileHeader}${bullet}`);
+      return { path, created: true };
+    }
+    // Existing file — peek the trailing byte to decide whether to
+    // insert a leading newline. Same fd → no separate stat→read race.
+    const tail = Buffer.alloc(1);
+    readSync(fd, tail, 0, 1, stat.size - 1);
+    const prefix = tail[0] !== 0x0a ? "\n" : "";
+    writeSync(fd, `${prefix}${bullet}`);
+    return { path, created: false };
+  } finally {
+    closeSync(fd);
   }
-  appendFileSync(path, `${prefix}${bullet}`, "utf8");
-  return { path, created: false };
 }

src/cli/ui/hooks/apply-slash-result.ts

@@ -6,13 +6,6 @@ import type { Scrollback } from "./useScrollback.js";
 
 export type SlashOutcome = { kind: "consumed" } | { kind: "resubmit"; text: string };
 
-interface ActiveLoopShape {
-  prompt: string;
-  intervalMs: number;
-  nextFireAt: number;
-  iter: number;
-}
-
 export interface ApplySlashResultContext {
   log: Scrollback;
   stdoutWrite: (chunk: string) => void;
@@ -20,10 +13,10 @@ export interface ApplySlashResultContext {
   syncPendingCount: () => void;
   session: string | null;
   codeModeOn: boolean;
-  activeLoopRef: MutableRefObject<ActiveLoopShape | null>;
+  isLoopActive: () => boolean;
   stopLoop: () => void;
   quitProcess: () => void;
-  promptHistory: MutableRefObject<string[]>;
+  pushHistory: (text: string) => void;
   /** The verbatim text the user typed; used for promptHistory bookkeeping. */
   text: string;
 }
@@ -34,7 +27,7 @@ export function applySlashResult(result: SlashResult, ctx: ApplySlashResultConte
     // the process is exiting. Use quitProcess (process.exit) rather than
     // Ink's exit(): the singleton stdin reader keeps a `data` listener
     // attached, so exit() unmounts React but leaves the event loop alive.
-    if (ctx.activeLoopRef.current) ctx.stopLoop();
+    if (ctx.isLoopActive()) ctx.stopLoop();
     ctx.quitProcess();
     return { kind: "consumed" };
   }
@@ -50,7 +43,7 @@ export function applySlashResult(result: SlashResult, ctx: ApplySlashResultConte
       clearPendingEdits(ctx.session);
       ctx.syncPendingCount();
     }
-    if (ctx.activeLoopRef.current) ctx.stopLoop();
+    if (ctx.isLoopActive()) ctx.stopLoop();
     return { kind: "consumed" };
   }
   if (result.info) {
@@ -77,6 +70,6 @@ export function applySlashResult(result: SlashResult, ctx: ApplySlashResultConte
   if (result.resubmit) {
     return { kind: "resubmit", text: result.resubmit };
   }
-  ctx.promptHistory.current.push(ctx.text);
+  ctx.pushHistory(ctx.text);
   return { kind: "consumed" };
 }

src/cli/ui/hooks/handle-tool-event.ts

@@ -16,7 +16,7 @@ export interface ToolEventContext {
   toolStartedAtRef: MutableRefObject<number | null>;
   toolHistoryRef: MutableRefObject<Array<{ toolName: string; text: string }>>;
   setPendingShell: Dispatch<
-    SetStateAction<{ command: string; kind: "run_command" | "run_background" } | null>
+    SetStateAction<{ id: number; command: string; kind: "run_command" | "run_background" } | null>
   >;
   setPendingPlan: Dispatch<SetStateAction<string | null>>;
   setPendingRevision: Dispatch<
@@ -52,122 +52,6 @@ export function handleToolEvent(ev: LoopEvent, ctx: ToolEventContext): void {
     });
   }
 
-  if (
-    ctx.codeModeOn &&
-    (ev.toolName === "run_command" || ev.toolName === "run_background") &&
-    ev.content.includes('"NeedsConfirmationError:') &&
-    ev.toolArgs
-  ) {
-    try {
-      const parsed = JSON.parse(ev.toolArgs) as { command?: unknown };
-      if (typeof parsed.command === "string" && parsed.command.trim()) {
-        ctx.setPendingShell({
-          command: parsed.command.trim(),
-          kind: ev.toolName as "run_command" | "run_background",
-        });
-      }
-    } catch {
-      /* malformed args — skip the prompt */
-    }
-  }
-
-  if (
-    ctx.codeModeOn &&
-    ev.toolName === "submit_plan" &&
-    ev.content.includes('"PlanProposedError:')
-  ) {
-    try {
-      const parsed = JSON.parse(ev.content) as {
-        plan?: unknown;
-        steps?: unknown;
-        summary?: unknown;
-      };
-      if (typeof parsed.plan === "string" && parsed.plan.trim()) {
-        const planText = parsed.plan.trim();
-        ctx.setPendingPlan(planText);
-        const steps = Array.isArray(parsed.steps) ? (parsed.steps as PlanStep[]) : null;
-        ctx.planStepsRef.current = steps;
-        ctx.completedStepIdsRef.current = new Set();
-        ctx.planBodyRef.current = planText;
-        ctx.planSummaryRef.current =
-          typeof parsed.summary === "string" && parsed.summary.trim()
-            ? parsed.summary.trim()
-            : null;
-        ctx.persistPlanState();
-        const summary =
-          typeof parsed.summary === "string" && parsed.summary.trim() ? parsed.summary.trim() : "";
-        const title = summary ? `Plan · ${summary}` : "Plan submitted";
-        ctx.log.showPlan({
-          title,
-          steps: (steps ?? []).map((s) => ({ id: s.id, title: s.title, status: "queued" })),
-          variant: "active",
-        });
-      }
-    } catch {
-      /* malformed payload — skip the picker */
-    }
-  }
-
-  if (ev.toolName === "revise_plan" && ev.content.includes('"PlanRevisionProposedError:')) {
-    try {
-      const parsed = JSON.parse(ev.content) as {
-        reason?: unknown;
-        remainingSteps?: unknown;
-        summary?: unknown;
-      };
-      const reason = typeof parsed.reason === "string" ? parsed.reason.trim() : "";
-      const remainingSteps = Array.isArray(parsed.remainingSteps)
-        ? (parsed.remainingSteps as PlanStep[]).filter(
-            (s) =>
-              s &&
-              typeof s.id === "string" &&
-              s.id.trim() &&
-              typeof s.title === "string" &&
-              s.title.trim() &&
-              typeof s.action === "string" &&
-              s.action.trim(),
-          )
-        : [];
-      if (reason && remainingSteps.length > 0) {
-        const summary =
-          typeof parsed.summary === "string" ? parsed.summary.trim() || undefined : undefined;
-        ctx.setPendingRevision({ reason, remainingSteps, summary });
-      }
-    } catch {
-      /* malformed payload — skip the picker */
-    }
-  }
-
-  if (ev.toolName === "ask_choice" && ev.content.includes('"ChoiceRequestedError:')) {
-    try {
-      const parsed = JSON.parse(ev.content) as {
-        question?: unknown;
-        options?: unknown;
-        allowCustom?: unknown;
-      };
-      const question = typeof parsed.question === "string" ? parsed.question.trim() : "";
-      const options = Array.isArray(parsed.options)
-        ? (parsed.options as ChoiceOption[]).filter(
-            (o) =>
-              o &&
-              typeof o.id === "string" &&
-              o.id.trim() &&
-              typeof o.title === "string" &&
-              o.title.trim(),
-          )
-        : [];
-      if (question && options.length >= 2) {
-        ctx.setPendingChoice({
-          question,
-          options,
-          allowCustom: parsed.allowCustom === true,
-        });
-      }
-    } catch {
-      /* malformed payload — skip the picker */
-    }
-  }
-
   if (ev.toolName === "mark_step_complete") {
     try {
       const parsed = JSON.parse(ev.content) as Partial<StepCompletion>;

src/cli/ui/hooks/useCodeMode.ts

@@ -0,0 +1,93 @@
+import { type MutableRefObject, useCallback } from "react";
+import {
+  type ApplyResult,
+  type EditBlock,
+  type EditSnapshot,
+  applyEditBlocks,
+  snapshotBeforeEdits,
+} from "../../../code/edit-blocks.js";
+import { clearPendingEdits, savePendingEdits } from "../../../code/pending-edits.js";
+import { formatEditResults, partitionEdits } from "../edit-history.js";
+
+export interface UseCodeModeResult {
+  /** /apply callback. Empty `indices` means "all"; specific 1-based indices apply only those. */
+  codeApply: (indices?: readonly number[]) => string;
+  /** /discard callback. Same indices semantics as codeApply. */
+  codeDiscard: (indices?: readonly number[]) => string;
+}
+
+export interface UseCodeModeOptions {
+  codeMode: boolean;
+  pendingEdits: MutableRefObject<EditBlock[]>;
+  currentRootDir: string;
+  session: string | null;
+  syncPendingCount: () => void;
+  recordEdit: (
+    source: string,
+    blocks: readonly EditBlock[],
+    results: readonly ApplyResult[],
+    snaps: readonly EditSnapshot[],
+  ) => void;
+}
+
+/** Slash-command callbacks for `/apply` and `/discard` over the pending-edits queue. Owns the partition / snapshot / save / sync sequence; AppInner just forwards the strings to its log. */
+export function useCodeMode(opts: UseCodeModeOptions): UseCodeModeResult {
+  const { codeMode, pendingEdits, currentRootDir, session, syncPendingCount, recordEdit } = opts;
+
+  const codeApply = useCallback(
+    (indices?: readonly number[]): string => {
+      if (!codeMode) return "not in code mode";
+      const blocks = pendingEdits.current;
+      if (blocks.length === 0) {
+        return "nothing pending — the model hasn't proposed edits since the last /apply or /discard.";
+      }
+      const useSubset = indices !== undefined && indices.length > 0;
+      const { selected, remaining } = useSubset
+        ? partitionEdits(blocks, indices)
+        : { selected: blocks, remaining: [] as EditBlock[] };
+      if (selected.length === 0) {
+        return "▸ no edits matched those indices — nothing applied. Use /apply with no args to commit them all.";
+      }
+      const snaps = snapshotBeforeEdits(selected, currentRootDir);
+      const results = applyEditBlocks(selected, currentRootDir);
+      const anyApplied = results.some((r) => r.status === "applied" || r.status === "created");
+      if (anyApplied) recordEdit("review-apply", selected, results, snaps);
+      pendingEdits.current = remaining;
+      if (remaining.length === 0) clearPendingEdits(session ?? null);
+      else savePendingEdits(session ?? null, remaining);
+      syncPendingCount();
+      const tail =
+        remaining.length > 0
+          ? `\n▸ ${remaining.length} edit block(s) still pending — /apply or /discard to clear them.`
+          : "";
+      return formatEditResults(results) + tail;
+    },
+    [codeMode, currentRootDir, session, syncPendingCount, recordEdit, pendingEdits],
+  );
+
+  const codeDiscard = useCallback(
+    (indices?: readonly number[]): string => {
+      const blocks = pendingEdits.current;
+      if (blocks.length === 0) return "nothing pending to discard.";
+      const useSubset = indices !== undefined && indices.length > 0;
+      const { selected, remaining } = useSubset
+        ? partitionEdits(blocks, indices)
+        : { selected: blocks, remaining: [] as EditBlock[] };
+      if (selected.length === 0) {
+        return "▸ no edits matched those indices — nothing discarded.";
+      }
+      pendingEdits.current = remaining;
+      if (remaining.length === 0) clearPendingEdits(session ?? null);
+      else savePendingEdits(session ?? null, remaining);
+      syncPendingCount();
+      const tail =
+        remaining.length > 0
+          ? `  (${remaining.length} block(s) still pending)`
+          : ". Nothing was written to disk.";
+      return `▸ discarded ${selected.length} pending edit block(s)${tail}`;
+    },
+    [session, syncPendingCount, pendingEdits],
+  );
+
+  return { codeApply, codeDiscard };
+}

src/cli/ui/hooks/useInputRecall.ts

@@ -0,0 +1,41 @@
+import { useCallback, useRef } from "react";
+
+export interface UseInputRecallResult {
+  recallPrev: () => void;
+  recallNext: () => void;
+  pushHistory: (text: string) => void;
+  /** Reset cursor to the "fresh input" position — call after a successful submit. */
+  resetCursor: () => void;
+}
+
+/** Bash-style ↑/↓ recall over a turn-local prompt history. Cursor is `useRef` so toggles don't re-render. */
+export function useInputRecall(setInput: (s: string) => void): UseInputRecallResult {
+  const promptHistory = useRef<string[]>([]);
+  const historyCursor = useRef<number>(-1);
+
+  const recallPrev = useCallback(() => {
+    const hist = promptHistory.current;
+    if (hist.length === 0) return;
+    const nextCursor = Math.min(historyCursor.current + 1, hist.length - 1);
+    historyCursor.current = nextCursor;
+    setInput(hist[hist.length - 1 - nextCursor] ?? "");
+  }, [setInput]);
+
+  const recallNext = useCallback(() => {
+    if (historyCursor.current < 0) return;
+    const hist = promptHistory.current;
+    const nextCursor = historyCursor.current - 1;
+    historyCursor.current = nextCursor;
+    setInput(nextCursor < 0 ? "" : (hist[hist.length - 1 - nextCursor] ?? ""));
+  }, [setInput]);
+
+  const pushHistory = useCallback((text: string) => {
+    promptHistory.current.push(text);
+  }, []);
+
+  const resetCursor = useCallback(() => {
+    historyCursor.current = -1;
+  }, []);
+
+  return { recallPrev, recallNext, pushHistory, resetCursor };
+}

src/cli/ui/hooks/useLoopMode.ts

@@ -0,0 +1,143 @@
+import { type MutableRefObject, useCallback, useEffect, useRef, useState } from "react";
+import type { Scrollback } from "./useScrollback.js";
+
+interface ActiveLoop {
+  prompt: string;
+  intervalMs: number;
+  nextFireAt: number;
+  iter: number;
+}
+
+export interface ActiveLoopSnapshot {
+  prompt: string;
+  intervalMs: number;
+  iter: number;
+  nextFireMs: number;
+}
+
+export interface UseLoopModeResult {
+  startLoop: (intervalMs: number, prompt: string) => void;
+  stopLoop: () => void;
+  /** Snapshot for the `/loop` (no-arg) status branch. Returns null when no loop is active. */
+  getLoopStatus: () => ActiveLoopSnapshot | null;
+  /** Cheap predicate — used by handleSubmit's cancel-on-user-input guard and by apply-slash-result. */
+  isLoopActive: () => boolean;
+  /** True only during the timer's `handleSubmit` invocation — tells handleSubmit's cancel guard to skip itself so the loop's own re-submit doesn't kill the loop. */
+  isLoopFiring: () => boolean;
+  /** Reset by handleSubmit at the top of every call so the firing flag is one-shot. */
+  clearFiringFlag: () => void;
+  /** Reactive state for the LoopStatusRow render — null when no loop is active. */
+  activeLoop: ActiveLoop | null;
+}
+
+export interface UseLoopModeOptions {
+  log: Scrollback;
+  busyRef: MutableRefObject<boolean>;
+  /** Forward-ref to the latest `handleSubmit` — the closure shifts as state changes, so the timer dereferences fresh on each fire. */
+  handleSubmitRef: MutableRefObject<((raw: string) => Promise<void>) | null>;
+}
+
+/** Owns the active /loop config + its setTimeout-based scheduler. Re-issuing /loop replaces the slot; cancellation is centralized in stopLoop. */
+export function useLoopMode(opts: UseLoopModeOptions): UseLoopModeResult {
+  const { log, busyRef, handleSubmitRef } = opts;
+  const [activeLoop, setActiveLoop] = useState<ActiveLoop | null>(null);
+  const activeLoopRef = useRef<ActiveLoop | null>(null);
+  const loopTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const loopFiringRef = useRef<boolean>(false);
+
+  useEffect(() => {
+    activeLoopRef.current = activeLoop;
+  }, [activeLoop]);
+
+  const stopLoop = useCallback(() => {
+    if (loopTimerRef.current) {
+      clearTimeout(loopTimerRef.current);
+      loopTimerRef.current = null;
+    }
+    const cur = activeLoopRef.current;
+    if (!cur) return;
+    setActiveLoop(null);
+    log.pushInfo(`▸ loop stopped (after ${cur.iter} iter${cur.iter === 1 ? "" : "s"}).`);
+  }, [log]);
+
+  const startLoop = useCallback((intervalMs: number, prompt: string) => {
+    if (loopTimerRef.current) {
+      clearTimeout(loopTimerRef.current);
+      loopTimerRef.current = null;
+    }
+    setActiveLoop({
+      prompt,
+      intervalMs,
+      nextFireAt: Date.now() + intervalMs,
+      iter: 0,
+    });
+  }, []);
+
+  const getLoopStatus = useCallback((): ActiveLoopSnapshot | null => {
+    const cur = activeLoopRef.current;
+    if (!cur) return null;
+    return {
+      prompt: cur.prompt,
+      intervalMs: cur.intervalMs,
+      iter: cur.iter,
+      nextFireMs: Math.max(0, cur.nextFireAt - Date.now()),
+    };
+  }, []);
+
+  const isLoopActive = useCallback(() => activeLoopRef.current !== null, []);
+  const isLoopFiring = useCallback(() => loopFiringRef.current, []);
+  const clearFiringFlag = useCallback(() => {
+    loopFiringRef.current = false;
+  }, []);
+
+  // /loop scheduler. Re-runs whenever activeLoop's `nextFireAt` shifts —
+  // either because startLoop set a fresh schedule or because a previous
+  // firing bumped the next-fire time. Cleanup clears the in-flight
+  // timer so a stopLoop / replacement doesn't leak a fire after cancel.
+  useEffect(() => {
+    if (!activeLoop) return;
+    const delay = Math.max(0, activeLoop.nextFireAt - Date.now());
+    const timer = setTimeout(async () => {
+      loopTimerRef.current = null;
+      // Skip the firing entirely when a prior turn is still running.
+      // Re-arm in 1s so the loop catches up the moment busy clears,
+      // rather than waiting a full interval after a slow turn.
+      if (busyRef.current) {
+        setActiveLoop((cur) => (cur ? { ...cur, nextFireAt: Date.now() + 1000 } : cur));
+        return;
+      }
+      const cur = activeLoopRef.current;
+      if (!cur) return;
+      const nextIter = cur.iter + 1;
+      // Schedule the NEXT firing now (independent of how long this turn
+      // takes). Keeps the cadence honest even when individual turns run
+      // long.
+      setActiveLoop((c) =>
+        c ? { ...c, iter: nextIter, nextFireAt: Date.now() + cur.intervalMs } : c,
+      );
+      log.pushInfo(`▸ /loop iter ${nextIter} → ${cur.prompt}`);
+      loopFiringRef.current = true;
+      try {
+        await handleSubmitRef.current?.(cur.prompt);
+      } catch {
+        // Persistent submission errors → kill the loop rather than spam
+        // the screen. User can re-issue /loop once they fix the cause.
+        stopLoop();
+      } finally {
+        loopFiringRef.current = false;
+      }
+    }, delay);
+    loopTimerRef.current = timer;
+    return () => clearTimeout(timer);
+  }, [activeLoop, stopLoop, log, busyRef, handleSubmitRef]);
+
+  return {
+    startLoop,
+    stopLoop,
+    getLoopStatus,
+    isLoopActive,
+    isLoopFiring,
+    clearFiringFlag,
+    activeLoop,
+  };
+}

src/cli/ui/hooks/useQuit.ts

@@ -0,0 +1,19 @@
+import type { WriteStream } from "node:fs";
+import { type MutableRefObject, useCallback, useEffect } from "react";
+
+/** Ctrl+C / SIGINT → flush transcript + `process.exit(0)`. We call `process.exit` directly rather than Ink's `exit()` because the singleton stdin reader keeps a `data` listener attached — `exit()` would unmount the React tree but leave the event loop alive and the terminal would hang. */
+export function useQuit(transcriptRef: MutableRefObject<WriteStream | null>): () => void {
+  const quitProcess = useCallback(() => {
+    transcriptRef.current?.end();
+    process.exit(0);
+  }, [transcriptRef]);
+
+  useEffect(() => {
+    process.on("SIGINT", quitProcess);
+    return () => {
+      process.off("SIGINT", quitProcess);
+    };
+  }, [quitProcess]);
+
+  return quitProcess;
+}

src/cli/ui/hooks/useScrollback.ts

@@ -38,6 +38,7 @@ export interface Scrollback {
     cost: number;
     sessionCost: number;
     balance?: number;
+    balanceCurrency?: string;
     elapsedMs?: number;
   }): string;
   showPlan(args: {
@@ -219,6 +220,7 @@ export function useScrollback(): Scrollback {
           cost: args.cost,
           sessionCost: args.sessionCost,
           balance: args.balance,
+          balanceCurrency: args.balanceCurrency,
           elapsedMs: args.elapsedMs,
         });
         return id;

src/cli/ui/hooks/useTranscriptWriter.ts

@@ -0,0 +1,20 @@
+import type { WriteStream } from "node:fs";
+import { type MutableRefObject, useCallback } from "react";
+import type { LoopEvent } from "../../../loop.js";
+import { recordFromLoopEvent, writeRecord } from "../../../transcript/log.js";
+
+/** Returns a `LoopEvent` writer that no-ops when no transcript was opened. Wraps `recordFromLoopEvent` + `writeRecord` so callers don't carry the model/prefix metadata. */
+export function useTranscriptWriter(
+  transcriptRef: MutableRefObject<WriteStream | null>,
+  model: string,
+  prefixHash: string,
+): (ev: LoopEvent) => void {
+  return useCallback(
+    (ev: LoopEvent) => {
+      const stream = transcriptRef.current;
+      if (!stream) return;
+      writeRecord(stream, recordFromLoopEvent(ev, { model, prefixHash }));
+    },
+    [transcriptRef, model, prefixHash],
+  );
+}

src/cli/ui/layout/LiveRows.tsx

@@ -11,6 +11,7 @@ import { PILL_MODEL, PILL_SECTION, Pill, modelBadgeFor } from "../primitives/Pil
 import { Spinner } from "../primitives/Spinner.js";
 import { CARD, FG, TONE } from "../theme/tokens.js";
 import { useElapsedSeconds, useSlowTick, useTick } from "../ticker.js";
+import type { SubagentActivity } from "../useSubagent.js";
 
 export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -159,20 +160,8 @@ function subagentTitle(skillName: string | undefined, task: string): string {
   return `Sub-agent · ${short || "anonymous"}`;
 }
 
-/** Live block for a running subagent — Card-styled, fixed row count for flicker-safety. */
-export function SubagentRow({
-  activity,
-}: {
-  activity: {
-    task: string;
-    iter: number;
-    elapsedMs: number;
-    skillName?: string;
-    model?: string;
-    phase?: "exploring" | "summarising";
-    lastInner: { glyph: string; color: string; label: string; meta?: string } | null;
-  };
-}) {
+/** Live block for a single in-flight subagent — rich layout, used when only one is running. */
+export function SubagentRow({ activity }: { activity: SubagentActivity }) {
   useTick();
   const seconds = (activity.elapsedMs / 1000).toFixed(1);
   const phase = subagentPhaseLabel(activity.phase, activity.iter, activity.elapsedMs);
@@ -222,6 +211,78 @@ export function SubagentRow({
   );
 }
 
+/** 1 → rich; 2-max → compact rows; >max → compact + "+N more" fold. */
+export function SubagentLiveStack({
+  activities,
+  max = 3,
+}: {
+  activities: ReadonlyArray<SubagentActivity>;
+  max?: number;
+}) {
+  const tick = useTick();
+  if (activities.length === 0) return null;
+  if (activities.length === 1) return <SubagentRow activity={activities[0]!} />;
+  const visible = activities.slice(0, max);
+  const overflow = activities.length - visible.length;
+  const summarising = activities.filter((a) => a.phase === "summarising").length;
+  const metaParts = [`${activities.length} running`];
+  if (summarising > 0) metaParts.push(`${summarising} summarising`);
+  return (
+    <Card tone={CARD.subagent.color}>
+      <CardHeader
+        glyph="⌬"
+        tone={CARD.subagent.color}
+        title="subagents"
+        titleColor={PILL_SECTION.plan.fg}
+        titleBg={PILL_SECTION.plan.bg}
+        subtitle={metaParts.join(" · ")}
+        right={<Spinner kind="braille" color={CARD.subagent.color} />}
+      />
+      {visible.map((a, i) => (
+        <CompactSubagentLine key={a.runId} activity={a} tick={tick} index={i} />
+      ))}
+      {overflow > 0 ? <Text color={FG.faint}>{`  +${overflow} more running…`}</Text> : null}
+    </Card>
+  );
+}
+
+function CompactSubagentLine({
+  activity,
+  tick,
+  index,
+}: {
+  activity: SubagentActivity;
+  tick: number;
+  index: number;
+}) {
+  const summarising = activity.phase === "summarising";
+  const spinnerFrame = SPINNER_FRAMES[(tick + index) % SPINNER_FRAMES.length] ?? "·";
+  const glyph = summarising ? "▶" : spinnerFrame;
+  const glyphColor = summarising ? TONE.brand : CARD.subagent.color;
+  const seconds = (activity.elapsedMs / 1000).toFixed(1).padStart(5);
+  const title = activity.skillName ?? truncate(activity.task, 28);
+  const titlePadded = title.padEnd(28);
+  const last = activity.lastInner;
+  return (
+    <Box flexDirection="row">
+      <Text color={glyphColor} bold>
+        {`  ${glyph} `}
+      </Text>
+      <Text color={FG.body}>{titlePadded}</Text>
+      <Text color={FG.faint}>{`  iter ${String(activity.iter).padStart(2)} · ${seconds}s · `}</Text>
+      {last ? (
+        <>
+          <Text color={last.color}>{`${last.glyph} `}</Text>
+          <Text color={FG.body}>{truncate(last.label, 18)}</Text>
+          {last.meta ? <Text color={FG.faint}>{`  ${last.meta}`}</Text> : null}
+        </>
+      ) : (
+        <Text color={FG.faint}>queued…</Text>
+      )}
+    </Box>
+  );
+}
+
 function truncate(text: string, max: number): string {
   return text.length > max ? `${text.slice(0, max)}…` : text;
 }

src/cli/ui/layout/StatusRow.tsx

@@ -4,25 +4,17 @@ import React from "react";
 import { Countdown } from "../primitives/Countdown.js";
 import { useAgentState } from "../state/provider.js";
 import type { Mode, NetworkState, StatusBar } from "../state/state.js";
-import { FG, TONE, USD_TO_CNY } from "../theme/tokens.js";
+import { FG, TONE, balanceColor, formatBalance, formatCost } from "../theme/tokens.js";
 
 const RULE_PAD = 4;
 const RULE_MIN = 20;
 
-function balanceColor(cny: number): string {
-  if (cny < 5) return TONE.err;
-  if (cny < 20) return TONE.warn;
-  return TONE.brand;
-}
-
 export function StatusRow(): React.ReactElement {
   const status = useAgentState((s) => s.status);
   const session = useAgentState((s) => s.session);
   const { stdout } = useStdout();
   const cols = stdout?.columns ?? 80;
   const ruleWidth = Math.max(RULE_MIN, cols - RULE_PAD);
-  const turnCny = status.cost * USD_TO_CNY;
-  const sessionCny = status.sessionCost * USD_TO_CNY;
   const hasTurn = status.cost > 0;
 
   return (
@@ -48,16 +40,22 @@ export function StatusRow(): React.ReactElement {
             <Text bold color={TONE.brand}>
               {"▸ "}
             </Text>
-            <Text bold color={FG.body}>{`¥${turnCny.toFixed(4)} turn`}</Text>
+            <Text bold color={FG.body}>
+              {`${formatCost(status.cost, status.balanceCurrency)} turn`}
+            </Text>
           </>
         )}
         <Sep />
-        <Text color={FG.sub}>{`¥${sessionCny.toFixed(3)} session`}</Text>
+        <Text
+          color={FG.sub}
+        >{`${formatCost(status.sessionCost, status.balanceCurrency, 3)} session`}</Text>
         {status.balance !== undefined && (
           <>
             <Sep />
             <Text color={FG.faint}>{"wallet "}</Text>
-            <Text bold color={balanceColor(status.balance)}>{`¥${status.balance.toFixed(2)}`}</Text>
+            <Text bold color={balanceColor(status.balance, status.balanceCurrency)}>
+              {formatBalance(status.balance, status.balanceCurrency)}
+            </Text>
           </>
         )}
         <Sep />

src/cli/ui/markdown.tsx

@@ -328,31 +328,29 @@ function FallbackTable({
 }): React.ReactElement {
   return (
     <Box flexDirection="column">
-      {headerCells.map((h, ci) => {
-        const label = `${padToCells(h, labelPad - 2)}: `;
-        const values = bodyCells.map((r) => r[ci] ?? "");
-        return (
-          // biome-ignore lint/suspicious/noArrayIndexKey: header cells positional
-          <Box key={`fk-${ci}`} flexDirection="column">
-            {values.map((v, ri) => {
-              const lines = wrapToCells(v, valueCells);
-              return lines.map((line, li) => (
-                // biome-ignore lint/suspicious/noArrayIndexKey: fallback table lines are positional
-                <Box key={`fv-${ri}-${li}`}>
-                  {li === 0 ? (
-                    <Text bold color={FG.sub}>
-                      {label}
-                    </Text>
-                  ) : (
-                    <Text>{padToCells("", labelPad)}</Text>
-                  )}
-                  <Text color={FG.body}>{line}</Text>
-                </Box>
-              ));
-            })}
-          </Box>
-        );
-      })}
+      {bodyCells.map((row, ri) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: body rows positional
+        <Box key={`fr-${ri}`} flexDirection="column">
+          {ri > 0 ? <Text> </Text> : null}
+          {headerCells.map((h, ci) => {
+            const label = `${padToCells(h, labelPad - 2)}: `;
+            const lines = wrapToCells(row[ci] ?? "", valueCells);
+            return lines.map((line, li) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: fallback table lines are positional
+              <Box key={`fc-${ri}-${ci}-${li}`}>
+                {li === 0 ? (
+                  <Text bold color={FG.sub}>
+                    {label}
+                  </Text>
+                ) : (
+                  <Text>{padToCells("", labelPad)}</Text>
+                )}
+                <Text color={FG.body}>{line}</Text>
+              </Box>
+            ));
+          })}
+        </Box>
+      ))}
     </Box>
   );
 }
@@ -370,12 +368,17 @@ function Inline({ tokens }: { tokens: Token[] }): React.ReactElement {
 const FILE_REF_RE = /\b([A-Za-z0-9_./@\-]+\.[A-Za-z0-9]{1,6})(?::(\d+)(?:-(\d+))?)?\b/g;
 const MENTION_RE = /(?<![A-Za-z0-9_])@([A-Za-z0-9_./\-]+\.[A-Za-z0-9]{1,6})/g;
 
-function osc8(label: string, target: string, color: string): React.ReactElement {
-  const open = `\x1b]8;;${target}\x07`;
-  const close = "\x1b]8;;\x07";
+function looksLikeFileRef(path: string, hasLine: boolean): boolean {
+  if (hasLine) return true;
+  if (path.includes("/")) return true;
+  const ext = path.split(".").pop() ?? "";
+  return ext.length >= 2;
+}
+
+function osc8(label: string, _target: string, color: string): React.ReactElement {
   return (
     <Text color={color} underline>
-      {`${open}${label}${close}`}
+      {label}
     </Text>
   );
 }
@@ -402,6 +405,7 @@ function renderInlineText(raw: string): React.ReactElement {
     if (hits.some((h) => start < h.end && end > h.start)) continue;
     const path = m[1]!;
     const line = m[2];
+    if (!looksLikeFileRef(path, line !== undefined)) continue;
     const target = line ? `file://${path}:${line}` : `file://${path}`;
     hits.push({ start, end, node: osc8(m[0], target, TONE.brand) });
   }

src/cli/ui/mcp-append.ts

@@ -1,4 +1,4 @@
-/** Applies an MCP append-drift mid-session: registers each new tool in the loop's registry + prefix, and updates the summary's report. */
+/** Applies an MCP append-drift mid-session: registers each new tool in the loop's registry + prefix, and returns an updated summary. Immutable — does not mutate the input `target`. */
 
 import type { CacheFirstLoop } from "../../loop.js";
 import { registerSingleMcpTool } from "../../mcp/registry.js";
@@ -10,7 +10,7 @@ export function applyMcpAppend(
   loop: CacheFirstLoop,
   target: McpServerSummary,
   addedTools: McpTool[],
-): void {
+): McpServerSummary {
   const accepted: McpTool[] = [];
   for (const mcpTool of addedTools) {
     if (!mcpTool.name) continue;
@@ -27,14 +27,18 @@ export function applyMcpAppend(
     loop.prefix.addTool(spec);
     accepted.push(mcpTool);
   }
-  if (accepted.length === 0) return;
-  // Refresh the summary's snapshot so `/mcp` and the browser modal show the
-  // new shape on their next render.
-  if (target.report.tools.supported) {
-    const merged = [...target.report.tools.items, ...accepted];
-    // biome-ignore lint/suspicious/noExplicitAny: report is a typed snapshot we mutate in place; deeper refactor isn't worth it here
-    (target.report.tools as any).items = merged;
-    // biome-ignore lint/suspicious/noExplicitAny: same — toolCount mirrors items.length post-append
-    (target as any).toolCount = merged.length;
-  }
+  if (accepted.length === 0 || !target.report.tools.supported) return target;
+
+  const merged = [...target.report.tools.items, ...accepted];
+  return {
+    ...target,
+    toolCount: merged.length,
+    report: {
+      ...target.report,
+      tools: {
+        supported: true as const,
+        items: merged,
+      },
+    },
+  };
 }

src/cli/ui/mcp-reconnect-kickoff.ts

@@ -5,8 +5,8 @@ import type { McpTool } from "../../mcp/types.js";
 import { formatMcpLifecycleEvent } from "./mcp-lifecycle.js";
 import type { McpServerSummary } from "./slash/types.js";
 
-/** Applies append-drift mid-session: registers each new MCP tool in the registry + prefix. */
-export type ApplyAppend = (target: McpServerSummary, addedTools: McpTool[]) => void;
+/** Applies append-drift mid-session: registers each new MCP tool in the registry + prefix. Returns the updated summary. */
+export type ApplyAppend = (target: McpServerSummary, addedTools: McpTool[]) => McpServerSummary;
 
 /** Kicks off async reconnect; returns the start-line, schedules result via postInfo. */
 export function kickOffMcpReconnect(
@@ -18,17 +18,20 @@ export function kickOffMcpReconnect(
   // Only opt into "append" when the caller wired an applyAppend handler;
   // otherwise the reconnect refuses append-drift with a "restart" message.
   const accept = applyAppend ? (["identity", "append"] as const) : (["identity"] as const);
+  // Use a mutable local so the async closure can update it after applyAppend
+  // without reassigning the function parameter (linter: noParameterAssign).
+  let liveTarget = target;
   void (async () => {
     try {
       const result = await reconnectMcpServer({
-        host: target.host,
-        spec: target.spec,
+        host: liveTarget.host,
+        spec: liveTarget.spec,
         beforeTools,
         accept,
       });
       if (result.ok) {
         if (result.kind === "append" && applyAppend) {
-          applyAppend(target, result.addedTools);
+          liveTarget = applyAppend(liveTarget, result.addedTools);
         }
         postInfo(
           formatMcpLifecycleEvent({

src/cli/ui/mcp-server-list.ts

@@ -0,0 +1,13 @@
+import type { McpServerSummary } from "./slash/types.js";
+
+export function sameMcpServerSummary(a: McpServerSummary, b: McpServerSummary): boolean {
+  return a === b || (a.label === b.label && a.spec === b.spec);
+}
+
+export function replaceMcpServerSummary(
+  servers: McpServerSummary[],
+  target: McpServerSummary,
+  updated: McpServerSummary,
+): McpServerSummary[] {
+  return servers.map((server) => (sameMcpServerSummary(server, target) ? updated : server));
+}

src/cli/ui/slash/commands.ts

@@ -1,7 +1,7 @@
 import type { SlashArgContext, SlashCommandSpec } from "./types.js";
 
 export const SLASH_COMMANDS: readonly SlashCommandSpec[] = [
-  { cmd: "help", summary: "show the full command reference" },
+  { cmd: "help", summary: "show the full command reference", aliases: ["?"] },
   { cmd: "status", summary: "current model, flags, context, session" },
   {
     cmd: "preset",
@@ -52,8 +52,13 @@ export const SLASH_COMMANDS: readonly SlashCommandSpec[] = [
     argsHint: "<EN|zh-CN>",
     summary: "switch the runtime language",
     argCompleter: ["EN", "zh-CN"],
+    aliases: ["lang"],
   },
   { cmd: "mcp", summary: "list MCP servers + tools attached to this session" },
+  {
+    cmd: "mcp browse",
+    summary: "browse the MCP marketplace — search registry, install with Enter",
+  },
   {
     cmd: "resource",
     argsHint: "[uri]",
@@ -119,9 +124,8 @@ export const SLASH_COMMANDS: readonly SlashCommandSpec[] = [
   { cmd: "retry", summary: "truncate & resend your last message (fresh sample)" },
   {
     cmd: "compact",
-    argsHint: "[tokens]",
     summary:
-      "shrink oversized tool results AND tool-call args (edit_file search/replace) in the log; cap in tokens, default 4000",
+      "fold older turns into a summary message (cache-safe). Auto-fires at 50% ctx; this is the manual trigger.",
   },
   { cmd: "keys", summary: "show all keyboard shortcuts and prompt prefixes" },
   { cmd: "plans", summary: "list this session's active + archived plans, newest first" },
@@ -139,24 +143,22 @@ export const SLASH_COMMANDS: readonly SlashCommandSpec[] = [
     summary: "show the launch command to resume a saved session",
   },
   { cmd: "forget", summary: "delete the current session from disk" },
-  {
-    cmd: "prune-sessions",
-    summary: "delete sessions idle ≥N days (default 90) — frees disk on long-time installs",
-    argsHint: "[days]",
-  },
-  { cmd: "setup", summary: "reminds you to exit and run `reasonix setup`" },
   {
     cmd: "semantic",
     summary: "show semantic_search status — built? Ollama installed? how to enable",
   },
   { cmd: "clear", summary: "clear visible scrollback only (log/context kept)" },
-  { cmd: "new", summary: "start a fresh conversation (clear context + scrollback)" },
+  {
+    cmd: "new",
+    summary: "start a fresh conversation (clear context + scrollback)",
+    aliases: ["reset"],
+  },
   {
     cmd: "loop",
     argsHint: "<5s..6h> <prompt>  ·  stop  ·  (no args = status)",
     summary: "auto-resubmit <prompt> every <interval> until you type something / Esc / /loop stop",
   },
-  { cmd: "exit", summary: "quit the TUI" },
+  { cmd: "exit", summary: "quit the TUI", aliases: ["quit", "q"] },
   // Code-mode only
   {
     cmd: "init",
@@ -256,16 +258,31 @@ export function suggestSlashCommands(prefix: string, codeMode = false): SlashCom
   const p = prefix.toLowerCase();
   return SLASH_COMMANDS.filter((c) => {
     if (c.contextual === "code" && !codeMode) return false;
-    return c.cmd.startsWith(p);
+    if (c.cmd.startsWith(p)) return true;
+    return c.aliases?.some((a) => a.startsWith(p)) ?? false;
   });
 }
 
+/** alias → canonical cmd map, derived from SLASH_COMMANDS at module init. */
+const ALIAS_TO_CMD: Readonly<Record<string, string>> = (() => {
+  const m: Record<string, string> = {};
+  for (const spec of SLASH_COMMANDS) {
+    if (!spec.aliases) continue;
+    for (const a of spec.aliases) m[a] = spec.cmd;
+  }
+  return m;
+})();
+
+export function resolveSlashAlias(name: string): string {
+  return ALIAS_TO_CMD[name] ?? name;
+}
+
 /** Picker fires only when arg tail has no internal whitespace; past that it's a usage hint. */
 export function detectSlashArgContext(input: string, codeMode = false): SlashArgContext | null {
   // `/cmd <rest>` — one space, rest captured up to end-of-buffer.
   const m = /^\/(\S+) ([\s\S]*)$/.exec(input);
   if (!m) return null;
-  const cmdName = m[1]!.toLowerCase();
+  const cmdName = resolveSlashAlias(m[1]!.toLowerCase());
   const tail = m[2] ?? "";
   const spec = SLASH_COMMANDS.find(
     (s) => s.cmd === cmdName && (s.contextual !== "code" || codeMode),

src/cli/ui/slash/dispatch.ts

@@ -1,4 +1,5 @@
 import type { CacheFirstLoop } from "../../../loop.js";
+import { resolveSlashAlias } from "./commands.js";
 import { handlers as adminHandlers } from "./handlers/admin.js";
 import { handlers as basicHandlers } from "./handlers/basic.js";
 import { handlers as dashboardHandlers } from "./handlers/dashboard.js";
@@ -45,7 +46,7 @@ export function handleSlash(
   loop: CacheFirstLoop,
   ctx: SlashContext = {},
 ): SlashResult {
-  const h = HANDLERS[cmd];
+  const h = HANDLERS[resolveSlashAlias(cmd)];
   if (h) return h(args, loop, ctx);
   return { unknown: true, info: `unknown command: /${cmd}  (try /help)` };
 }

src/cli/ui/slash/handlers/admin.ts

@@ -4,10 +4,10 @@ import {
   type ResolvedHook,
   globalSettingsPath,
   projectSettingsPath,
-} from "../../../../hooks.js";
-import { t } from "../../../../i18n/index.js";
-import { aggregateUsage, defaultUsageLogPath, readUsageLog } from "../../../../telemetry/usage.js";
-import { VERSION, compareVersions, isNpxInstall } from "../../../../version.js";
+} from "@/hooks.js";
+import { t } from "@/i18n/index.js";
+import { aggregateUsage, defaultUsageLogPath, readUsageLog } from "@/telemetry/usage.js";
+import { VERSION, compareVersions, isNpxInstall } from "@/version.js";
 import { runDoctorChecks } from "../../../commands/doctor.js";
 import { renderDashboard } from "../../../commands/stats.js";
 import type { SlashHandler } from "../dispatch.js";

src/cli/ui/slash/handlers/basic.ts

@@ -1,4 +1,4 @@
-import { t } from "../../../../i18n/index.js";
+import { t } from "@/i18n/index.js";
 import { formatDuration, formatLoopStatus, parseLoopCommand } from "../../loop.js";
 import type { SlashHandler } from "../dispatch.js";
 
@@ -77,7 +77,6 @@ const help: SlashHandler = () => ({
     t("handlers.basic.helpMcp"),
     t("handlers.basic.helpResource"),
     t("handlers.basic.helpPrompt"),
-    t("handlers.basic.helpSetup"),
     t("handlers.basic.helpCompact"),
     t("handlers.basic.helpThink"),
     t("handlers.basic.helpTool"),
@@ -147,10 +146,6 @@ const help: SlashHandler = () => ({
   ].join("\n"),
 });
 
-const setup: SlashHandler = () => ({
-  info: t("handlers.basic.setupInfo"),
-});
-
 const retry: SlashHandler = (_args, loop) => {
   const prev = loop.retryLastUser();
   if (!prev) {
@@ -194,14 +189,10 @@ const loop: SlashHandler = (args, _loop, ctx) => {
 
 export const handlers: Record<string, SlashHandler> = {
   exit,
-  quit: exit,
   clear,
   new: resetLog,
-  reset: resetLog,
   keys,
   help,
-  "?": help,
-  setup,
   retry,
   loop,
 };

src/cli/ui/slash/handlers/dashboard.ts

@@ -1,4 +1,4 @@
-import { t } from "../../../../i18n/index.js";
+import { t } from "@/i18n/index.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const dashboard: SlashHandler = (args, _loop, ctx) => {

src/cli/ui/slash/handlers/edits.ts

@@ -5,9 +5,9 @@ import {
   fmtAgo,
   listCheckpoints,
   restoreCheckpoint,
-} from "../../../../code/checkpoints.js";
-import type { EditMode } from "../../../../config.js";
-import { t } from "../../../../i18n/index.js";
+} from "@/code/checkpoints.js";
+import type { EditMode } from "@/config.js";
+import { t } from "@/i18n/index.js";
 import { parseEditIndices } from "../../edit-history.js";
 import type { SlashHandler } from "../dispatch.js";
 import { runGitCommit, stripOuterQuotes } from "../helpers.js";

src/cli/ui/slash/handlers/init.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import * as pathMod from "node:path";
-import { t } from "../../../../i18n/index.js";
+import { t } from "@/i18n/index.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const INIT_PROMPT = [

src/cli/ui/slash/handlers/jobs.ts

@@ -1,5 +1,5 @@
-import { t } from "../../../../i18n/index.js";
-import type { JobRecord } from "../../../../tools/jobs.js";
+import { t } from "@/i18n/index.js";
+import type { JobRecord } from "@/tools/jobs.js";
 import type { SlashHandler } from "../dispatch.js";
 
 function statusIcon(r: JobRecord): string {

src/cli/ui/slash/handlers/language.ts

@@ -1,10 +1,5 @@
-import {
-  getSupportedLanguages,
-  notifyLanguageChange,
-  setLanguage,
-  t,
-} from "../../../../i18n/index.js";
-import type { LanguageCode } from "../../../../i18n/types.js";
+import { getSupportedLanguages, notifyLanguageChange, setLanguage, t } from "@/i18n/index.js";
+import type { LanguageCode } from "@/i18n/types.js";
 import type { SlashHandler } from "../dispatch.js";
 
 export const handlers: Record<string, SlashHandler> = {
@@ -30,5 +25,4 @@ export const handlers: Record<string, SlashHandler> = {
 
     return { info: t("slash.language.success") };
   },
-  lang: (args, loop, ctx) => handlers.language!(args, loop, ctx),
 };

src/cli/ui/slash/handlers/mcp.ts

@@ -1,5 +1,5 @@
-import { t } from "../../../../i18n/index.js";
-import type { CacheFirstLoop } from "../../../../loop.js";
+import { t } from "@/i18n/index.js";
+import type { CacheFirstLoop } from "@/loop.js";
 import { applyMcpAppend } from "../../mcp-append.js";
 import { toggleMcpDisabled } from "../../mcp-disable.js";
 import { slashHealthBadge } from "../../mcp-health.js";
@@ -19,15 +19,20 @@ const mcp: SlashHandler = (args, loop, ctx) => {
   if (sub === "reconnect") {
     return triggerReconnect(args[1], servers, ctx.postInfo, loop);
   }
-  // `/mcp text` (or non-TTY) falls through to the printed-card path. The
-  // default `/mcp` opens the interactive browser modal.
+  if (sub === "browse" || sub === "install" || sub === "marketplace") {
+    return { openMcpHub: { tab: "marketplace" } };
+  }
+  // Interactive default: ALWAYS open the hub. Live tab when servers
+  // are bridged, Marketplace tab otherwise (so a fresh user lands on
+  // "discover + install" instead of an empty list). `/mcp text` is the
+  // only path to the printed-card dump — used by replay / non-TTY.
   const wantsTextDump = sub === "text";
+  if (!wantsTextDump) {
+    return { openMcpHub: { tab: servers.length > 0 ? "live" : "marketplace" } };
+  }
   if (servers.length === 0 && specs.length === 0 && toolSpecs.length === 0) {
     return { info: t("handlers.mcp.noServers") };
   }
-  if (!wantsTextDump && servers.length > 0) {
-    return { openMcpBrowser: true };
-  }
   // Rich path — we have full inspection reports, so show each server
   // with its tools / resources / prompts grouped together.
   if (servers.length > 0) {

src/cli/ui/slash/handlers/memory.ts

@@ -1,10 +1,6 @@
-import { t } from "../../../../i18n/index.js";
-import {
-  PROJECT_MEMORY_FILE,
-  memoryEnabled,
-  readProjectMemory,
-} from "../../../../memory/project.js";
-import { type MemoryScope, MemoryStore } from "../../../../memory/user.js";
+import { t } from "@/i18n/index.js";
+import { PROJECT_MEMORY_FILE, memoryEnabled, readProjectMemory } from "@/memory/project.js";
+import { type MemoryScope, MemoryStore } from "@/memory/user.js";
 import type { SlashHandler } from "../dispatch.js";
 import { resolveMemoryTarget } from "../helpers.js";
 

src/cli/ui/slash/handlers/model.ts

@@ -1,5 +1,5 @@
-import { saveReasoningEffort } from "../../../../config.js";
-import { t } from "../../../../i18n/index.js";
+import { saveReasoningEffort } from "@/config.js";
+import { t } from "@/i18n/index.js";
 import { PRESETS } from "../../presets.js";
 import type { SlashHandler } from "../dispatch.js";
 

src/cli/ui/slash/handlers/observability.ts

@@ -1,10 +1,10 @@
-import { t } from "../../../../i18n/index.js";
+import { t } from "@/i18n/index.js";
 import {
   DEEPSEEK_CONTEXT_TOKENS,
   DEEPSEEK_PRICING,
   DEFAULT_CONTEXT_TOKENS,
-} from "../../../../telemetry/stats.js";
-import { countTokens } from "../../../../tokenizer.js";
+} from "@/telemetry/stats.js";
+import { countTokens } from "@/tokenizer.js";
 import { computeCtxBreakdown } from "../../ctx-breakdown.js";
 import type { SlashHandler } from "../dispatch.js";
 import { compactNum, formatToolList } from "../helpers.js";
@@ -160,23 +160,26 @@ function renderTinyBar(pct: number, width: number): string {
   return `[${"█".repeat(filled)}${"░".repeat(w - filled)}]`;
 }
 
-const compact: SlashHandler = (args, loop) => {
-  const tight = Number.parseInt(args[0] ?? "", 10);
-  const cap = Number.isFinite(tight) && tight >= 100 ? tight : 4000;
-  const { healedCount, tokensSaved, charsSaved } = loop.compact(cap);
-  if (healedCount === 0) {
-    return {
-      info: t("handlers.observability.compactNone", { cap: cap.toLocaleString() }),
-    };
-  }
-  return {
-    info: t("handlers.observability.compactInfo", {
-      count: healedCount,
-      cap: cap.toLocaleString(),
-      tokens: tokensSaved.toLocaleString(),
-      chars: charsSaved.toLocaleString(),
-    }),
-  };
+const compact: SlashHandler = (_args, loop, ctx) => {
+  void loop
+    .compactHistory()
+    .then((r) => {
+      if (!r.folded) {
+        ctx.postInfo?.(t("handlers.observability.compactNoop"));
+        return;
+      }
+      ctx.postInfo?.(
+        t("handlers.observability.compactDone", {
+          before: r.beforeMessages,
+          after: r.afterMessages,
+          chars: r.summaryChars.toLocaleString(),
+        }),
+      );
+    })
+    .catch((err: Error) => {
+      ctx.postInfo?.(t("handlers.observability.compactFailed", { reason: err.message }));
+    });
+  return { info: t("handlers.observability.compactStarting") };
 };
 
 const cost: SlashHandler = (args, loop, ctx) => {
@@ -205,7 +208,7 @@ const cost: SlashHandler = (args, loop, ctx) => {
   return {};
 };
 
-function estimateCost(userText: string, loop: import("../../../../loop.js").CacheFirstLoop) {
+function estimateCost(userText: string, loop: import("@/loop.js").CacheFirstLoop) {
   const pricing = DEEPSEEK_PRICING[loop.model];
   if (!pricing) {
     return { info: t("handlers.observability.costNoPricing", { model: loop.model }) };

src/cli/ui/slash/handlers/permissions.ts

@@ -3,9 +3,9 @@ import {
   clearProjectShellAllowed,
   loadProjectShellAllowed,
   removeProjectShellAllowed,
-} from "../../../../config.js";
-import { t } from "../../../../i18n/index.js";
-import { BUILTIN_ALLOWLIST } from "../../../../tools/shell.js";
+} from "@/config.js";
+import { t } from "@/i18n/index.js";
+import { BUILTIN_ALLOWLIST } from "@/tools/shell.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const permissions: SlashHandler = (args, _loop, ctx) => {

src/cli/ui/slash/handlers/plans.ts

@@ -1,6 +1,6 @@
 import { basename } from "node:path";
-import { listPlanArchives, loadPlanState, relativeTime } from "../../../../code/plan-store.js";
-import { t } from "../../../../i18n/index.js";
+import { listPlanArchives, loadPlanState, relativeTime } from "@/code/plan-store.js";
+import { t } from "@/i18n/index.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const plans: SlashHandler = (_args, loop) => {

src/cli/ui/slash/handlers/semantic.ts

@@ -2,9 +2,9 @@
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { probeOllama } from "../../../../index/semantic/embedding.js";
-import { t } from "../../../../index/semantic/i18n.js";
-import { findOllamaBinary } from "../../../../index/semantic/ollama-launcher.js";
+import { probeOllama } from "@/index/semantic/embedding.js";
+import { t } from "@/index/semantic/i18n.js";
+import { findOllamaBinary } from "@/index/semantic/ollama-launcher.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const semantic: SlashHandler = (_args, _loop, ctx) => {
@@ -74,15 +74,24 @@ interface IndexSummary {
 /** 10MB read cap so `/semantic` stays snappy on very large repos. */
 async function readIndexMeta(rootDir: string): Promise<IndexSummary | null> {
   const dataPath = path.join(rootDir, ".reasonix", "semantic", "index.jsonl");
+  let raw: string;
   try {
-    const stat = await fs.stat(dataPath);
-    if (stat.size > 10 * 1024 * 1024) {
-      // For huge indexes, give an order-of-magnitude estimate from
-      // file size (avg ~500 bytes/chunk in practice). Files won't
-      // be available, so we report just the chunk approximation.
-      return { chunks: Math.round(stat.size / 500), files: 0 };
+    // Bind size check and content to the same fd so a concurrent
+    // rebuild can't grow the file past the 10MB threshold between
+    // stat and read (CodeQL js/file-system-race).
+    const fh = await fs.open(dataPath, "r");
+    try {
+      const stat = await fh.stat();
+      if (stat.size > 10 * 1024 * 1024) {
+        // For huge indexes, give an order-of-magnitude estimate from
+        // file size (avg ~500 bytes/chunk in practice). Files won't
+        // be available, so we report just the chunk approximation.
+        return { chunks: Math.round(stat.size / 500), files: 0 };
+      }
+      raw = await fh.readFile("utf8");
+    } finally {
+      await fh.close();
     }
-    const raw = await fs.readFile(dataPath, "utf8");
     const seenPaths = new Set<string>();
     let chunks = 0;
     for (const line of raw.split("\n")) {

src/cli/ui/slash/handlers/sessions.ts

@@ -1,14 +1,7 @@
-import { t } from "../../../../i18n/index.js";
-import {
-  deleteSession,
-  listSessions,
-  pruneStaleSessions,
-  renameSession,
-} from "../../../../memory/session.js";
+import { t } from "@/i18n/index.js";
+import { deleteSession, listSessions, renameSession } from "@/memory/session.js";
 import type { SlashHandler } from "../dispatch.js";
 
-const STALE_THRESHOLD_DAYS = 90;
-
 const sessions: SlashHandler = () => ({ openSessionsPicker: true });
 
 const forget: SlashHandler = (_args, loop) => {
@@ -24,28 +17,6 @@ const forget: SlashHandler = (_args, loop) => {
   };
 };
 
-const pruneSessions: SlashHandler = (args) => {
-  const raw = args?.[0];
-  const days = raw ? Number.parseInt(raw, 10) : STALE_THRESHOLD_DAYS;
-  if (!Number.isFinite(days) || days < 1) {
-    return {
-      info: t("handlers.sessions.pruneUsage", { default: STALE_THRESHOLD_DAYS }),
-    };
-  }
-  const removed = pruneStaleSessions(days);
-  if (removed.length === 0) {
-    return { info: t("handlers.sessions.pruneNone", { days }) };
-  }
-  return {
-    info: t("handlers.sessions.pruneInfo", {
-      count: removed.length,
-      s: removed.length === 1 ? "" : "s",
-      days,
-      names: removed.join(", "),
-    }),
-  };
-};
-
 const rename: SlashHandler = (args, loop) => {
   const newName = args?.[0]?.trim();
   if (!newName) return { info: t("handlers.sessions.renameUsage") };
@@ -70,5 +41,4 @@ export const handlers: Record<string, SlashHandler> = {
   forget,
   rename,
   resume,
-  "prune-sessions": pruneSessions,
 };

src/cli/ui/slash/handlers/skill.ts

@@ -1,5 +1,5 @@
-import { t } from "../../../../i18n/index.js";
-import { SkillStore } from "../../../../skills.js";
+import { t } from "@/i18n/index.js";
+import { SkillStore } from "@/skills.js";
 import type { SlashHandler } from "../dispatch.js";
 
 const skill: SlashHandler = (args, _loop, ctx) => {

src/cli/ui/slash/types.ts

@@ -10,8 +10,8 @@ export interface SlashResult {
   info?: string;
   /** Open the SessionPicker modal mid-chat — used by `/sessions` slash. */
   openSessionsPicker?: boolean;
-  /** Open the MCP browser modal — used by `/mcp` slash in interactive contexts. */
-  openMcpBrowser?: boolean;
+  /** Open the unified MCP hub — `/mcp` defaults to "live", `/mcp browse` to "marketplace". */
+  openMcpHub?: { tab: "live" | "marketplace" };
   /** Open the arg-completer picker for this command (e.g. `/language` → language picker). */
   openArgPickerFor?: string;
   /** Exit the app. */
@@ -84,6 +84,7 @@ export interface SlashContext {
     cost: number;
     sessionCost: number;
     balance?: number;
+    balanceCurrency?: string;
     elapsedMs?: number;
   }) => void;
   dispatch?: (event: import("../state/events.js").AgentEvent) => void;
@@ -92,6 +93,13 @@ export interface SlashContext {
   /** `/apply-plan` clears the picker so its own `resubmit` doesn't double-fire approval. */
   clearPendingPlan?: () => void;
   reloadHooks?: () => number;
+  /** Diff config.mcp[] vs live bridges → add/close clients accordingly. Wired from chat.tsx mcpRuntime. */
+  reloadMcp?: () => Promise<{
+    added: string[];
+    removed: string[];
+    failed: Array<{ spec: string; reason: string }>;
+    summaries: McpServerSummary[];
+  }>;
   /** `null` → still in flight OR offline; consumers can't distinguish, so always offer `refreshLatestVersion`. */
   latestVersion?: string | null;
   refreshLatestVersion?: () => void;
@@ -124,6 +132,8 @@ export interface SlashCommandSpec {
   argsHint?: string;
   /** First-arg picker source — file paths intentionally absent (use `@path` mentions instead). */
   argCompleter?: "models" | "mcp-resources" | "mcp-prompts" | readonly string[];
+  /** Alternate names — typing any of these resolves to `cmd` for dispatch / suggestion / arg-context. */
+  aliases?: readonly string[];
 }
 
 export interface SlashArgContext {

src/cli/ui/state/cards.ts

@@ -116,6 +116,7 @@ export interface UsageCard extends CardBase {
   readonly cost: number;
   readonly sessionCost: number;
   readonly balance?: number;
+  readonly balanceCurrency?: string;
   /** Wall-clock for the turn — surfaced as `· 1.2s` in the header meta. */
   readonly elapsedMs?: number;
   /** Auto-emitted per-turn cards render as a single dim row; /cost emits the full breakdown. */

src/cli/ui/state/events.ts

@@ -117,6 +117,7 @@ const sessionUpdate = z.object({
     cost: z.number().optional(),
     sessionCost: z.number().optional(),
     balance: z.number().optional(),
+    balanceCurrency: z.string().optional(),
     cacheHit: z.number().optional(),
   }),
 });
@@ -241,6 +242,7 @@ const usageShow = z.object({
   cost: z.number().nonnegative(),
   sessionCost: z.number().nonnegative(),
   balance: z.number().optional(),
+  balanceCurrency: z.string().optional(),
   elapsedMs: z.number().nonnegative().optional(),
 });
 

src/cli/ui/state/reducer.ts

@@ -250,6 +250,7 @@ export function reduce(state: AgentState, event: AgentEvent): AgentState {
         cost: event.cost,
         sessionCost: event.sessionCost,
         balance: event.balance,
+        balanceCurrency: event.balanceCurrency,
         elapsedMs: event.elapsedMs,
       });
 

src/cli/ui/state/state.ts

@@ -28,6 +28,7 @@ export interface StatusBar {
   cost: number;
   sessionCost: number;
   balance?: number;
+  balanceCurrency?: string;
   cacheHit: number;
   countdownSeconds?: number;
   recording?: { sizeBytes: number; events: number; path: string };

src/cli/ui/theme/tokens.ts

@@ -59,7 +59,32 @@ export type CardTone = keyof typeof CARD;
 /** DeepSeek prices in CNY; our internal table is USD divided by 7.2. Multiply back for display. */
 export const USD_TO_CNY = 7.2;
 
-export function formatCNY(usd: number, fractionDigits = 4): string {
-  const cny = usd * USD_TO_CNY;
-  return `¥${cny.toFixed(fractionDigits)}`;
+const SYMBOL: Record<string, string> = { USD: "$", CNY: "¥" };
+
+/** Format an amount already in `currency`. Undefined currency → CNY (matches pre-fix behavior). */
+export function formatBalance(
+  amount: number,
+  currency?: string,
+  opts?: { fractionDigits?: number; label?: boolean },
+): string {
+  const cur = currency ?? "CNY";
+  const sym = SYMBOL[cur];
+  const digits = opts?.fractionDigits ?? 2;
+  const body = sym ? `${sym}${amount.toFixed(digits)}` : `${cur} ${amount.toFixed(digits)}`;
+  return opts?.label ? `w ${body}` : body;
+}
+
+/** Format an internal USD cost in the wallet's display currency. Undefined currency → CNY. */
+export function formatCost(costUsd: number, currency?: string, fractionDigits = 4): string {
+  const cur = currency ?? "CNY";
+  const amount = cur === "CNY" ? costUsd * USD_TO_CNY : costUsd;
+  return formatBalance(amount, cur, { fractionDigits });
+}
+
+/** Threshold color for a wallet balance. USD is converted to CNY before the threshold check. */
+export function balanceColor(amount: number, currency?: string): string {
+  const cny = (currency ?? "CNY") === "USD" ? amount * USD_TO_CNY : amount;
+  if (cny < 5) return TONE.err;
+  if (cny < 20) return TONE.warn;
+  return TONE.brand;
 }

src/cli/ui/useSubagent.ts

@@ -3,7 +3,7 @@ import type { LoopEvent } from "../../loop.js";
 import { appendUsage } from "../../telemetry/usage.js";
 import type { SubagentEvent, SubagentSink } from "../../tools/subagent.js";
 import type { Scrollback } from "./hooks/useScrollback.js";
-import { CARD, TONE } from "./theme/tokens.js";
+import { CARD, TONE, formatCost } from "./theme/tokens.js";
 
 function summariseInner(ev: LoopEvent): SubagentInnerSummary | null {
   if (ev.role === "tool_start") {
@@ -40,6 +40,10 @@ export interface SubagentInnerSummary {
 }
 
 export interface SubagentActivity {
+  /** Stable per-spawn id; key for parallel-row rendering. */
+  runId: string;
+  /** Wall-clock start so the stack stays in launch order even when events arrive interleaved. */
+  startedAt: number;
   task: string;
   iter: number;
   elapsedMs: number;
@@ -52,94 +56,103 @@ export interface SubagentActivity {
 export interface UseSubagentParams {
   session: string | undefined;
   log: Scrollback;
+  /** Read live wallet currency at end-event time so the cost suffix follows the wallet symbol. */
+  getWalletCurrency?: () => string | undefined;
 }
 
 export interface UseSubagentResult {
-  /** Live state for an in-flight subagent, null when none is running. */
-  activity: SubagentActivity | null;
+  /** In-flight runs, oldest first. Empty when none active. */
+  activities: ReadonlyArray<SubagentActivity>;
   sinkRef: React.MutableRefObject<SubagentSink>;
 }
 
-export function useSubagent({ session, log }: UseSubagentParams): UseSubagentResult {
-  const [activity, setActivity] = useState<SubagentActivity | null>(null);
+export function useSubagent({
+  session,
+  log,
+  getWalletCurrency,
+}: UseSubagentParams): UseSubagentResult {
+  const [activities, setActivities] = useState<ReadonlyArray<SubagentActivity>>([]);
   const sinkRef = useRef<SubagentSink>({ current: null });
+  // Subagent runs can outlive a balance refresh; the thunk lives in a ref so the
+  // sink callback (installed once at mount) always reads the latest wallet currency.
+  const getWalletCurrencyRef = useRef(getWalletCurrency);
+  useEffect(() => {
+    getWalletCurrencyRef.current = getWalletCurrency;
+  }, [getWalletCurrency]);
 
   useEffect(() => {
     sinkRef.current.current = (ev: SubagentEvent) => {
       if (ev.kind === "start") {
-        setActivity({
-          task: ev.task,
-          iter: ev.iter ?? 0,
-          elapsedMs: ev.elapsedMs ?? 0,
-          skillName: ev.skillName,
-          model: ev.model,
-          phase: "exploring",
-          lastInner: null,
-        });
-        return;
-      }
-      if (ev.kind === "progress") {
-        setActivity((prev) =>
-          prev
-            ? {
-                ...prev,
-                iter: ev.iter ?? prev.iter,
-                elapsedMs: ev.elapsedMs ?? prev.elapsedMs,
-              }
-            : {
-                task: ev.task,
-                iter: ev.iter ?? 0,
-                elapsedMs: ev.elapsedMs ?? 0,
-                skillName: ev.skillName,
-                model: ev.model,
-                phase: "exploring",
-                lastInner: null,
-              },
-        );
-        return;
-      }
-      if (ev.kind === "phase") {
-        setActivity((prev) => (prev ? { ...prev, phase: ev.phase } : prev));
-        return;
-      }
-      if (ev.kind === "inner" && ev.inner) {
-        const summary = summariseInner(ev.inner);
-        if (!summary) return;
-        setActivity((prev) => (prev ? { ...prev, lastInner: summary } : prev));
-        return;
-      }
-      // end
-      setActivity(null);
-      const seconds = ((ev.elapsedMs ?? 0) / 1000).toFixed(1);
-      // Inline cost: the one number most users look at. Saves a /stats round-trip.
-      const costTail =
-        ev.costUsd !== undefined && ev.costUsd > 0 ? ` · $${ev.costUsd.toFixed(4)}` : "";
-      const summary = ev.error
-        ? `⌬ subagent "${ev.task}" failed after ${seconds}s · ${ev.iter ?? 0} tool call(s) — ${ev.error}`
-        : `⌬ subagent "${ev.task}" done in ${seconds}s · ${ev.iter ?? 0} tool call(s) · ${ev.turns ?? 0} turn(s)${costTail}`;
-      log.pushInfo(summary);
-      // Persist a subagent summary row to ~/.reasonix/usage.jsonl so
-      // `/stats` and `reasonix stats` surface it. Skipped on error —
-      // we only record what actually cost money and did work.
-      if (!ev.error && ev.usage && ev.model) {
-        appendUsage({
-          session: session ?? null,
-          model: ev.model,
-          usage: ev.usage,
-          kind: "subagent",
-          subagent: {
+        setActivities((prev) => {
+          if (prev.some((a) => a.runId === ev.runId)) return prev;
+          const next: SubagentActivity = {
+            runId: ev.runId,
+            startedAt: Date.now() - (ev.elapsedMs ?? 0),
+            task: ev.task,
+            iter: ev.iter ?? 0,
+            elapsedMs: ev.elapsedMs ?? 0,
             skillName: ev.skillName,
-            taskPreview: ev.task.slice(0, 60),
-            toolIters: ev.iter ?? 0,
-            durationMs: ev.elapsedMs ?? 0,
-          },
+            model: ev.model,
+            phase: "exploring",
+            lastInner: null,
+          };
+          return [...prev, next];
         });
+        return;
       }
+      if (ev.kind === "end") {
+        setActivities((prev) => prev.filter((a) => a.runId !== ev.runId));
+        const seconds = ((ev.elapsedMs ?? 0) / 1000).toFixed(1);
+        const costTail =
+          ev.costUsd !== undefined && ev.costUsd > 0
+            ? ` · ${formatCost(ev.costUsd, getWalletCurrencyRef.current?.())}`
+            : "";
+        const summary = ev.error
+          ? `⌬ subagent "${ev.task}" failed after ${seconds}s · ${ev.iter ?? 0} tool call(s) — ${ev.error}`
+          : `⌬ subagent "${ev.task}" done in ${seconds}s · ${ev.iter ?? 0} tool call(s) · ${ev.turns ?? 0} turn(s)${costTail}`;
+        log.pushInfo(summary);
+        if (!ev.error && ev.usage && ev.model) {
+          appendUsage({
+            session: session ?? null,
+            model: ev.model,
+            usage: ev.usage,
+            kind: "subagent",
+            subagent: {
+              skillName: ev.skillName,
+              taskPreview: ev.task.slice(0, 60),
+              toolIters: ev.iter ?? 0,
+              durationMs: ev.elapsedMs ?? 0,
+            },
+          });
+        }
+        return;
+      }
+      // progress / phase / inner — patch the matching row, ignore stragglers from runs we never saw `start` for.
+      setActivities((prev) =>
+        prev.map((a) => {
+          if (a.runId !== ev.runId) return a;
+          if (ev.kind === "progress") {
+            return {
+              ...a,
+              iter: ev.iter ?? a.iter,
+              elapsedMs: ev.elapsedMs ?? a.elapsedMs,
+            };
+          }
+          if (ev.kind === "phase") {
+            return { ...a, phase: ev.phase ?? a.phase };
+          }
+          if (ev.kind === "inner" && ev.inner) {
+            const summary = summariseInner(ev.inner);
+            return summary ? { ...a, lastInner: summary } : a;
+          }
+          return a;
+        }),
+      );
     };
     return () => {
       sinkRef.current.current = null;
     };
   }, [session, log]);
 
-  return { activity, sinkRef };
+  return { activities, sinkRef };
 }