@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/README.md

@@ -6,8 +6,6 @@ recall, skills, and capture.
 
 Ships the `brainrouter` binary.
 
----
-
 ## Install
 
 ```bash
@@ -23,52 +21,44 @@ command not found`.
 
 | How Node is installed | Use `sudo`? |
 |---|---|
-| Homebrew (`brew install node`) | ❌ No — global prefix is user-writable |
-| nvm / asdf / fnm | ❌ No — same reason |
-| System Node on macOS / Linux | ✅ Yes — global prefix is `/usr/local/...` |
-
-Check yours:
-
-```bash
-npm config get prefix
-```
+| Homebrew (`brew install node`) | No — global prefix is user-writable |
+| nvm / asdf / fnm | No — same reason |
+| System Node on macOS / Linux | Yes — global prefix is `/usr/local/...` |
 
-If the path is under `/Users/...`, `/opt/homebrew/...`, or your home dir
-→ no sudo. If it's `/usr/local/...` → use sudo.
+Check yours: `npm config get prefix`. If the path is under `/Users/...`,
+`/opt/homebrew/...`, or your home dir — no sudo. If it's `/usr/local/...` — use sudo.
 
 Verify the install:
 
 ```bash
 which brainrouter           # prints the path to the binary
-brainrouter --version       # prints 0.3.5
+brainrouter --version       # prints 0.3.7
 ```
 
----
-
 ## Configure
 
-Two configuration surfaces, both one-time:
-
-### 1. The chat LLM and MCP server profile
+Run `brainrouter` for the first time and the **setup wizard** starts
+automatically:
 
-```bash
-brainrouter config          # interactive — set LLM provider, model, key, endpoint
-brainrouter login           # interactive — set MCP server URL + API key
+```
+Welcome → Theme → Provider → API key → Model → MCP → AGENT.md → Done
 ```
 
-Both write to `~/.config/brainrouter/config.json`.
+It writes everything to `~/.config/brainrouter/config.json` — no manual
+file editing needed.
 
-For local-model setups (LM Studio / Ollama), point the LLM endpoint at
-`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
+To re-run the wizard later: type `/init` inside the REPL.
 
-### 2. (Optional) Runtime knobs — `~/.config/brainrouter/cli.env` or `./brainrouter-cli.env`
+To change a single setting: use `/config <key> <value>` or the `/config`
+home panel. To re-configure the MCP server connection: use `/login`.
 
-Only needed if you want to tune sandbox, tool-loop limits, trace logging,
-or web-search backend. See the [`.env.example`](.env.example) bundled with
-this package for the full list. LLM credentials do **not** go here — they
-live in `config.json`.
+For local-model setups (LM Studio / Ollama), point the LLM endpoint at
+`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
 
----
+**Runtime knobs** (sandbox, trace log, web-search backend, tool-loop limits)
+are set as shell environment variables. See
+[`brainrouter-docs/configuration.md`](https://github.com/kinqsradiollc/BrainRouter/blob/main/brainrouter-docs/configuration.md)
+for the full list.
 
 ## Run
 
@@ -83,22 +73,15 @@ Inside the REPL, type `/help` for the full slash-command list (60+
 commands across session / memory / workflow / orchestration / observability
 surfaces).
 
-### Offline mode
-
-If the MCP server isn't reachable, the CLI still boots — but only local
-tools (file edits, shell, web fetch, `spawn_agent`) work. Memory recall,
-capture, and skills are disabled until the server is back. The startup
-banner shows `⚠️  OFFLINE MODE` when this happens. Pass `--strict-mcp` to
+**Offline mode** — if the MCP server isn't reachable, the CLI still boots
+with only local tools (file edits, shell, web fetch, `spawn_agent`). Memory
+recall, capture, and skills are disabled until the server is back. The
+startup banner shows `offline` when this happens. Pass `--strict-mcp` to
 make the CLI exit instead of degrading.
 
-### Stdio mode
-
-If you'd rather have the CLI spawn the MCP server as a child process
-instead of running it separately, use `brainrouter config` → "Set Active
-Server Profile" → `default` (the bundled stdio profile). You don't need
-to run anything else — the CLI manages the server's lifecycle.
-
----
+**Stdio mode** — to have the CLI spawn the MCP server as a child process
+instead of running it separately: open `/config`, go to MCP settings, and
+pick the bundled `stdio` profile. The CLI manages the server's lifecycle.
 
 ## Workspace detection
 
@@ -113,8 +96,6 @@ BRAINROUTER_WORKSPACE=/absolute/path/to/project brainrouter
 
 Inside the REPL, run `/workspace` to confirm the active root and session key.
 
----
-
 ## What you also probably want
 
 A BrainRouter MCP server for the cognitive memory. The CLI works without
@@ -127,9 +108,7 @@ $EDITOR ~/.config/brainrouter/server.env          # set BRAINROUTER_LLM_API_KEY,
 brainrouter-mcp --http --port 3747                # in a separate terminal
 ```
 
-Then `brainrouter login` and point at `http://localhost:3747/mcp`.
-
----
+Then run `/login` inside the REPL and point at `http://localhost:3747/mcp`.
 
 ## Docs
 
@@ -138,8 +117,6 @@ Then `brainrouter login` and point at `http://localhost:3747/mcp`.
 - **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
 - **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
 
----
-
 ## License
 
 MIT

package/agents/architect.json

@@ -0,0 +1,18 @@
+{
+  "id": "architect",
+  "displayName": "Architect",
+  "whenToUse": "Design alternatives and tradeoffs for a feature or system change. No file writes.",
+  "prompt": "## Role: Architect\nYou design solutions; you do not write production code.\n\n### Memory-first opening (mandatory)\n- `memory_search` and `memory_graph_query` for the feature/domain — past architecture decisions often constrain new ones.\n- `memory_contradictions` (action: list) — if prior designs contradict the proposed change, flag it.\n- Cite any architecture_decision records you find with their recordId.\n\nAlways present at least two design alternatives with explicit tradeoffs (complexity, blast radius, reversibility, test cost).\nEnd with a clear recommendation and the smallest first vertical slice.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_architect",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/explorer.json

@@ -0,0 +1,18 @@
+{
+  "id": "explorer",
+  "displayName": "Explorer",
+  "whenToUse": "Read-only codebase investigation. Returns concrete file paths, line ranges, and a short list of facts.",
+  "prompt": "## Role: Explorer\nYou are a read-only investigator. Do not edit files or run shell commands.\nGoal: map the relevant code, return concrete file paths with line ranges, and surface the few facts the parent needs to decide.\n\n### Memory-first opening (mandatory)\n- Step 1: `memory_search` for the topic of investigation. Past explorers may have mapped this already — do not re-discover what BrainRouter already knows.\n- Step 2: `memory_graph_query` with the dominant feature/entity name to surface related memories across 2 hops.\n- Step 3: `memory_file_history` for any file the parent specifically mentions.\n- Cite every recordId you build on. Your output begins with a `### Memory consulted` block listing the record IDs and what they told you.\n\nOutput structure: 1) Memory consulted, 2) Summary (3-5 bullets), 3) Key files with line ranges, 4) Open questions, 5) Suggested next probe.\nNever claim work is complete without naming actual files you read AND showing the memory you consulted.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_explorer",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/reviewer.json

@@ -0,0 +1,18 @@
+{
+  "id": "reviewer",
+  "displayName": "Reviewer",
+  "whenToUse": "Code review stance; findings first, severity-ordered. Read-only.",
+  "prompt": "## Role: Reviewer\nYou review changes critically. Findings first; severity-ordered (blocker, major, minor, nit).\n\n### Memory-first opening (mandatory)\n- `memory_search` for prior reviews on the same files or feature — never re-flag an issue another reviewer already decided is acceptable.\n- `memory_file_history` for each file in the diff — known regressions and prior bug fixes inform your verdict.\n- Cite related recordIds inline in each finding so the parent can see the precedent.\n\nFor each finding: file:line, what is wrong, why it matters, suggested fix.\nDo not make edits. The parent will decide what to apply.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_reviewer",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/verifier.json

@@ -0,0 +1,18 @@
+{
+  "id": "verifier",
+  "displayName": "Verifier",
+  "whenToUse": "Runs tests and checks; reports pass/fail with evidence.",
+  "prompt": "## Role: Verifier\nYou verify that recent changes work. Run the smallest useful set of tests/typechecks.\n\n### Memory-first opening (mandatory)\n- `memory_search` for prior failure modes on these tests — flaky tests, environment caveats, and known-bad commands live in memory.\n- `memory_file_history` for any test file involved — past fixes for the same suite are highly relevant.\n\nReport: which command(s) you ran, exit codes, failing output (trimmed), and a clear PASS/FAIL verdict.\nNever claim PASS without actually executing a check. On failure, call `memory_task_update` with the blocker so the next worker can pick it up.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "shell",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_verifier",
+  "tier": "worker",
+  "outputContract": null
+}

package/agents/worker.json

@@ -0,0 +1,18 @@
+{
+  "id": "worker",
+  "displayName": "Worker",
+  "whenToUse": "Implementation-focused. May edit files when granted write access.",
+  "prompt": "## Role: Worker\nYou implement a single bounded task. Keep edits minimal and scoped.\n\n### Memory-first opening (mandatory)\n- `memory_recall` for the task topic — past instructions, conventions, and tool_preference records often dictate HOW to implement.\n- `memory_file_history` for the files you intend to touch — known fragility lives there.\n- If the parent gave you `seedRecordIds`, treat those as authoritative context.\n- `memory_task_state` if this looks like a continuation — pick up where prior work left off.\n\nRead before editing. Prefer edit_file over write_file when possible. Prefer apply_patch for multi-file edits.\nOn completion call `memory_task_update` with the outcome, then report exactly which files you changed and any follow-ups the verifier should run.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "write",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_worker",
+  "tier": "worker",
+  "outputContract": null
+}

package/changelog/0.2.0.md

@@ -0,0 +1,15 @@
+# 0.2.0 — 2026-05-15
+
+Admin & dashboard polish.
+
+- **Admin Users console** at `/users` — paginated list; create / enable / disable / delete with self-protection; API key resets.
+- **Memories Hub** — debounced text search, type filter chips, active/archived toggle, inline edit modal, infinite scroll, bulk actions.
+- **Expanded Profile settings** — display-name editing, masked API key with click-to-copy, rotate-key confirmation, copy-paste MCP client config (STDIO + HTTP/SSE).
+- **Contradiction resolution UI** — open/resolved filter, resolve/dismiss controls, real-time pending badge in the sidebar.
+- **Auth hardening** — Remember-Me JWT persistence, signup password strength, rate-limit 20 attempts / 15 min per IP, dynamic CORS via `BRAINROUTER_CORS_ORIGIN`.
+- **MCP onboarding banner** with copyable SSE connection variables.
+
+## Fixes
+- Recall Inspector no longer crashes on null/undefined potential scores.
+- AuthGuard no longer flashes loading state when validating session persistence on mount.
+- Stale JWT tokens cleared after protected API call failures.

package/changelog/0.3.0.md

@@ -0,0 +1,20 @@
+# 0.3.0 — 2026-05-16
+
+Terminal Agent CLI + multi-agent orchestration + memory engine.
+
+## Features
+- **Terminal Agent CLI (`brainrouter`)** — memory-native coding agent with ~70 slash commands, durable per-session transcripts, and LLM-driven compaction.
+- **Multi-agent orchestration** — first-class `spawn_agent` with five built-in roles:
+  - **explorer** — read-only research
+  - **architect** — design tradeoffs
+  - **reviewer** — severity-ordered findings
+  - **worker** — write-access implementation
+  - **verifier** — test/shell validation
+- **Web Chat (`/chat`)** — interactive in-browser agent with full memory engine access (recall, scenes, consolidation, contradictions).
+- **HTTP Chat Completions endpoint** — MCP server exposes `/api/chat-completions` so any HTTP client can drive a BrainRouter agent.
+- **Memory consolidation** — generates human-readable filesystem snapshots (`MEMORY.md`, `user.md`, `feedback.md`, `project.md`, `reference.md`).
+- **Filtered & freshness-boosted recall** — `memory_recall` / `memory_search` accept type / scene / time / priority filters; new captures get a freshness bump.
+- **Graph expansion & spreading activation** — 2-hop BFS over the knowledge graph; citation-driven reinforcement (LTP, +5% per cite, capped +30%); synaptic pruning of uncited memories.
+- **Hookify Markdown rules** — drop a `.md` file with YAML frontmatter into `.brainrouter/hooks/` to install warn/block guardrails on tool calls without writing code.
+- **Working-memory canvas** — large child-agent outputs auto-offload to a working-memory canvas via `memory_working_*` tools instead of polluting parent context.
+- **Skill memetic potential** — repeatedly invoking a skill heats it up so its context gets pre-injected; half-life decay keeps cold skills out of the prompt.

package/changelog/0.3.1.md

@@ -0,0 +1,22 @@
+# 0.3.1 — 2026-05-17
+
+Reliability hardening — silent failures, races, and edge cases.
+
+## Fixes
+- **🚨 Silent memory failure.** The CLI was looking for the wrong recall-response key, so every memory recall returned zero records and the citation / decay loop was effectively dead.
+- **MCP child never saw LLM credentials** when spawned from a non-package directory. Symptoms: extraction failures piled up, cognitive table stayed empty.
+- **`OPENAI_API_KEY` fallback bypassed by empty config string** (`??` nullish coalescing on an empty string).
+- **Goal budget off-by-one.** Budget=10 fired 11 iterations.
+- **Silent verifier child agents could bypass shell-approval prompts** — privilege-escalation path through `spawn_agent` closed. Silent children now refuse shell unless explicitly auto-approved.
+- **No MCP timeout** — a hung MCP server used to hang the whole turn forever. Now races against `BRAINROUTER_MCP_TIMEOUT_MS` (60s default).
+- **No auto-compaction** — long sessions silently blew the request-body cap. Now auto-compacts at 80k tokens (`BRAINROUTER_AUTO_COMPACT_TOKENS`).
+- **Hallucinated tool names hard-failed.** `Read_File` / `read-file` / `read.file` now fuzzy-match against the real tool registry first.
+- **JSON state corruption killed the REPL.** Bad `goal.json` or transcript files now quarantine to `<path>.corrupt-<ts>` and recover instead of bricking boot.
+- **Sweeper interval misconfiguration could flood the LLM backend** — added a 30s code-level floor with a warning log and a reentrancy guard.
+
+## Features
+- **LLM concurrency semaphore** — cap simultaneous LLM calls per process via `BRAINROUTER_LLM_MAX_CONCURRENT` (default 2 MCP / 4 CLI). Set to `1` on consumer hardware running LM Studio; raise to `16+` for cloud backends.
+- **LM Studio "Model is unloaded" auto-recovery** — detects the specific 400 body and retries once after the JIT load completes.
+- **HTTP MCP transport documented and verified** end-to-end. Switch via `~/.config/brainrouter/config.json` → `"activeServer": "local-http"`.
+- **`/doctor` extraction health check** — reports `healthy | backlog | DEGRADED` with the last extractor error inline.
+- **Stronger fan-out detection** — broader phrase matching ("test all", "review every", "audit the whole codebase") and clearer spawn-agent visual output.

package/changelog/0.3.2.md

@@ -0,0 +1,15 @@
+# 0.3.2 — 2026-05-19
+
+Observability + headless + UX polish.
+
+- **OTEL trace nesting** for spawned child agents — fan-out trees now reconstruct correctly in observability tools.
+- **Headless mode rejects slash commands** with a clear error and exit code 2 instead of silently routing them to the LLM.
+- **GitHub PR info in statusline** (`/statusline mode,branch,pr`) with a 30s cache.
+- **Dynamic terminal tab title** prefixed with `(N)` when continuation or child agents are pending — useful for background tabs.
+- **`brainrouter agents [--json]`** — list child sessions from the command line without entering the REPL.
+- **Paginated `/help`** with category groups; drill in with `/help <category>`.
+- **Streaming `/diff`** for large edits, with `--staged` and `--all` flags.
+
+## Fixes
+- Slash commands followed by tab or newline now match correctly.
+- Prompt history no longer records consecutive duplicate user prompts.

package/changelog/0.3.3.md

@@ -0,0 +1,19 @@
+# 0.3.3 — 2026-05-21
+
+`/goal` state machine + structural refactors.
+
+## Features
+- **`usage_limited` goal status** — resumable state distinct from `paused` (user-initiated) and `blocked` (agent gave up); triggered when iteration or token cap runs out.
+- **Token budget on goals** — optional `maxTokens` cap. When reached, the goal transitions to `usage_limited`. Protects a fixed dollar budget without estimating turn counts.
+- **Replace-confirmation prompt** — `/goal <new text>` won't silently overwrite an in-progress goal.
+- **Wrap-up steering** on the final budget turn — the model is directed to consolidate and finalize instead of starting new investigations.
+- **`/goal edit`** — unified update entrypoint for status, text, budget, and tokens.
+- **`/goal tokens <N>`** — set or clear the per-goal token cap.
+
+## Improvements
+- **REPL split** into seven category command files (memory, ui, workflow, orchestration, obs, guard, session). Slash commands behave identically — only the layout changed.
+- **Source tree restructured** into responsibility folders under `brainrouter-cli/src/`.
+- **Monorepo versions synchronized** to 0.3.3 across all seven packages (prior releases had drifted).
+
+## Fixes
+- **MCP no longer pollutes the workspace tree.** Working memory, session state, and `/feedback` now live under `~/.brainrouter/` instead of in your project. Empty `<workspace>/.brainrouter/` shells from prior installs auto-clean.

package/changelog/0.3.4.md

@@ -0,0 +1,20 @@
+# 0.3.4 — 2026-05-22
+
+First public npm release. Four packages under `@kinqs/`:
+
+| Package | What it is |
+|---|---|
+| `@kinqs/brainrouter-cli` | Installs the `brainrouter` CLI binary |
+| `@kinqs/brainrouter-mcp-server` | Installs `brainrouter-mcp` (MCP server) |
+| `@kinqs/brainrouter-sdk` | Typed client helpers |
+| `@kinqs/brainrouter-types` | Shared TypeScript types |
+
+## Features
+- **CLI offline mode** — MCP unreachable no longer hard-exits; `--strict-mcp` opts back into fail-fast. Banner shows `⚠️ OFFLINE MODE`.
+- **Inspection-tool previews** — `list_dir`, `grep_search`, `glob_files` render results inline even when small models forget to echo them.
+- **`bash` / `shell` / `sh` aliases** for `run_command` (Claude Code parity). Gated on `run_command` being available, so read-only mode can't sneak shell access.
+
+## Improvements
+- **CLI env separation** — `~/.config/brainrouter/config.json` is the canonical chat-LLM credential store; `.env` is restricted to runtime knobs (sandbox, timeouts, web search).
+- **Dashboard migration** to `brainrouter-dashboard/` (Next.js 15, same page set).
+- **SETUP.md** — maintainer runbook covering first-time setup, daily run, upgrade, publish, troubleshooting, nuclear-reset paths.

package/changelog/0.3.5.md

@@ -0,0 +1,9 @@
+# 0.3.5 — 2026-05-22
+
+Global-install UX fix.
+
+- **`brainrouter-mcp init`** — scaffolds `~/.config/brainrouter/server.env` from the bundled template (chmod 0600). Won't overwrite an existing file.
+- **Env-loader priority chain** — `$BRAINROUTER_ENV_FILE` → `~/.config/brainrouter/server.env` → `./.env`. Server prints which file it loaded at startup.
+- **Published READMEs rewritten** for global-install users (the actual npm flow ending with `brainrouter` on `$PATH`); SETUP.md split into "install from npm" vs "clone and build" paths.
+
+Backward compatible — existing monorepo dev (`brainrouter/.env`) still works in the third priority slot.

package/changelog/0.3.6.md

@@ -0,0 +1,9 @@
+# 0.3.6 — 2026-05-25
+
+Smarter recall, friendlier CLI, more reliable agent loop.
+
+- **Multi-workflow concurrency.** `/workflow switch <slug>` flips between `/feature-dev` / `/spec` / `/review` workflows in the same workspace; `/workflows` lists them with artifact markers. Goals stay session-scoped (workflows are pure storage + navigation).
+- **New session knobs.** `/effort low|medium|high` (forwarded as `reasoning_effort` to gpt-5 / o-series / gpt-oss / deepseek-r/v / qwen3 / magistral), `/mode planning|fast` + `/review-policy request|proceed` (replace `/yolo` + `autoApproveShell`), `/grill-me <task>` (2–5 clarifying questions before any edit), `ask_user_choice` (mid-turn arrow-key picker).
+- **Context budget — 70% lighter system prompt + gated recall.** Static prompt cut from ~4,750 → ~1,400 tokens; briefing now fires only on turn 1, post-compaction, or messages carrying ≥2 entity-shaped tokens. Goal text deduplicated to a single per-turn anchor.
+- **MCP identity + offline UX + multi-MCP foundation.** BrainRouter MCP auto-detected (config / name / URL / stdio / tool signature); when offline, the system prompt swaps to a `⚠️ OFFLINE` block and banner/statusline gain a distinct `brain` indicator. New `/mcp list` / `/mcp reconnect` / `/mcp tools` dispatcher.
+- **REPL stdin no longer freezes** after spinner-based slash commands (`ora`'s `discardStdin: true` was tearing down readline's keypress listener).

package/changelog/0.3.7.md

@@ -0,0 +1,20 @@
+# 0.3.7 — 2026-05-26
+
+Terminal UI redesign, in-terminal configuration, full Ink chat REPL, and multi-agent registry foundations.
+
+- **Full Ink chat REPL.** Every surface — banner, composer, scrollback, tool events, slash palette, footer — now renders through a single Ink tree. The old readline turn loop is removed. Inline slash palette with fuzzy ranking and keyboard navigation; `/config` / `/login` / `/init` render as overlays inside the chat tree, eliminating raw-mode conflicts.
+- **First-run wizard.** `Welcome → Theme → Provider → API key → Model → MCP → AGENT.md → Done` auto-triggers on first launch when no config is found. Re-enterable via `/init`; `/init agentmd` preserves the legacy AGENT.md-only scaffold mode.
+- **`/config` settings panel + multi-profile MCP manager.** Bare `/config` opens an arrow-key settings home; `/config <key>` prints current value, `/config <key> <value>` sets it. The MCP row is a full profile manager — list, add, edit, probe, and remove profiles without restarting the CLI.
+- **`/login` slash command.** In-REPL MCP profile editor: transport picker → URL/key fields → reachability probe → save and hot-connect to the running pool.
+- **`/model` picker.** Fetches the live model list from the active endpoint's `/v1/models` and lets you swap without leaving the REPL.
+- **Identity-based MCP tool prefix.** Servers with `identity: "brainrouter"` expose tools as `mcp__brainrouter__<tool>` regardless of their JSON config key, so skills targeting the canonical prefix survive profile renames.
+- **Multi-MCP pool.** CLI connects to all configured servers concurrently on boot; tools are merged into one inventory with `mcp__<serverId>__<tool>` prefixing. `/mcp connect|disconnect|reconnect` commands; one server failing does not cascade.
+- **Data-driven agent registry.** Five built-in agents (`explorer`, `architect`, `reviewer`, `worker`, `verifier`) are JSON files under `brainrouter-cli/agents/`. Three-tier merge: built-in → user-global (`~/.config/brainrouter/agents/`) → workspace (`.brainrouter/agents/`), with workspace taking precedence. `spawn_agent` gains an `agentId` param for registry lookup; `/agents defs` lists all known definitions.
+- **Spawn tier hierarchy + depth caps.** Each agent definition carries a `tier` (`reasoning` | `worker`). `chat` may spawn anything; `reasoning` agents may only spawn `worker` children; `worker` agents cannot delegate. Depth capped at 3 (overridable via `BRAINROUTER_MAX_SPAWN_DEPTH`).
+- **CLI/server env separation.** CLI reads credentials only from `~/.config/brainrouter/config.json`; package `.env` files are no longer read. MCP child stderr is piped so server logs don't bleed into the Ink UI.
+
+## Fixes
+- `/config provider <id>` now prompts for the new provider's API key instead of reusing the old one.
+- `/login` can update LLM credentials after initial MCP profile setup.
+- HTTP MCP setup collects the BrainRouter API key for both local and remote HTTP transports.
+- Wizard Skip clears stale `activeServer` instead of silently reconnecting to an old profile.

package/changelog/0.3.8.md

@@ -0,0 +1,30 @@
+# 0.3.8 — 2026-05-26
+
+CLI delegation reliability, parallel reads, native Anthropic adapter, and a tranche of quick wins carried from 0.3.7.
+
+- **Runtime child-drain guardrail.** `Agent.runTurn` now tracks child agents spawned during the current turn and refuses to accept a no-tool prose answer ("I am waiting…") while children are still pending or running. Auto-calls `wait_agents` with a bounded timeout (`BRAINROUTER_CHILD_DRAIN_TIMEOUT_MS`, default 30 s); on timeout returns an explicit "children still running" envelope with id/role/status/summary plus a `/continue` hint instead of vague silence.
+- **`task_agent` / `delegate_agent` tool split.** New foreground `task_agent` wrapper blocks until the child completes or the bounded timeout fires (returns completed output or a timeout envelope). New background `delegate_agent` wrapper returns a running child id plus a "continue working" hint — non-blocking. `spawn_agent({ wait: true })` remains backward-compatible. System prompt policy now steers: direct answer → direct tool → `task_agent` → `delegate_agent`.
+- **Child progress visibility in Ink.** Child tool start/end events propagate from `tools.ts` through new `onChildToolStart` / `onChildToolEnd` orchestration callbacks. Ink scrollback renders paired rows per child tool call with child id, role, tool, duration, success/error, and short summary. Parent wait state shows a live "running children" status row; `/agents` and `/agents --watch` use the same data shape.
+- **Safe parallel execution for read-only tools.** When the model emits multiple tool calls in one response, independent read-only tools (`read_file`, `list_dir`, `grep_search`, `glob_files`, `fetch_url`, `web_search`, MCP memory reads) run concurrently via `Promise.allSettled`; write/shell/orchestration tools stay strictly serial in their original order to preserve causality. Tool-result messages append to chatHistory in original call order so the model's next turn sees a deterministic trace. Unknown tool names fail safe to serial. New `toolSafety.ts` is the single source of truth for the parallel-safe list.
+- **Cron-style `/schedule`.** Recurring jobs via standard 5-field cron expressions (`/schedule cron "*/15 * * * *" /ci-status`); accepts `*`, lists, ranges, steps. One-shot `/schedule in 5m /foo` and `/schedule at 14:30 /foo` remain unchanged. New `scheduleStore.ts` persists `{id, cron, command, owner, lastRun, nextRun, enabled}` under `.brainrouter/schedules.json`; in-process `scheduleTicker.ts` wakes every 30 s, scans due jobs, dispatches them through the same path as one-shots. Catch-up after laptop sleep fires each missed window at most once. `/schedule list|remove|enable|disable` for management.
+- **`/release-notes` in-CLI.** New slash command renders the changelog for the current installed version directly in the Ink REPL. `/release-notes <version>` for past versions; `/release-notes list` shows every bundled version. Build copies `brainrouter-changelog/*.md` into the published `brainrouter-cli/changelog/` so the notes ship with the npm package.
+- **Strict tool-call recovery.** New `toolCallRecovery.ts` (adapted from deer-flow's pattern) hardens the agent loop against malformed LLM tool calls: dedupes duplicate tool_call ids in one response (last wins, warning logged); on `JSON.parse` failure attaches a synthetic error tool_result instead of aborting the turn; synthesises orphan-result envelopes for any tool_call that never executed so OpenAI's strict pairing stays well-formed; unknown tool names return a "did you mean: <closest>" hint via the existing `normalizeToolName` helper.
+- **Per-vendor MCP install snippets.** New `/mcp install <vendor>` prints the paste-ready JSON block and config file path for Claude Desktop, Cursor, Windsurf, VS Code Continue, and Zed, with the active brainrouter profile's URL/API key already substituted. `/mcp install list` enumerates supported vendors with OS-resolved paths. New `brainrouter-docs/mcp-install.md` mirrors the in-CLI output for the web.
+- **Native Anthropic `/v1/messages` adapter.** New `anthropicAdapter.ts` talks Anthropic's native shape directly instead of routing through the OpenAI-compat shim when the active profile is Anthropic. Tool calls round-trip via `tool_use` / `tool_result` content blocks. System prompt extracted to the top-level `system` field. Opt-in prompt caching (`BRAINROUTER_ANTHROPIC_CACHE=1` adds `cache_control: { type: 'ephemeral' }` on system + last assistant). Extended thinking on Claude 4-series Sonnet/Opus when `/effort high` is active. Streaming intentionally out of scope. OpenAI path byte-identical for non-Anthropic providers.
+- **Hooks JSON authoring doc.** New `brainrouter-docs/hooks.md` covers the `.brainrouter/hooks.json` and `.brainrouter/hookify/*.json` schemas with three worked examples (block `rm -rf`, post-turn `npm test` warning, commit-message ticket-prefix flag), debugging tips, and synchronous-loop limits.
+- **Ink question overlays.** `ask_user_choice` now renders through the active Ink chat overlay instead of the legacy raw stdout picker, so option rows stay visible while the chat screen repaints. Multi-select prompts show checkboxes; the free-form `Other` fallback is preserved. `askYesNo` confirmations use a visible in-chat yes/no picker while the Ink REPL is active.
+
+## Fixes
+
+- **Briefing now finds prefixed memory tools.** `🧠 Briefing: 0 records from (none)` no longer appears when the brain MCP is connected and exposes `mcp_brainrouter_memory_recall`. Root cause: `toolNames.has('memory_recall')` in `briefing.ts` and the `/mcp` doctor checked bare names against `listTools()` output, but the pool emits prefixed names. New `hasMcpTool` helper in `runtime/mcpUtils.ts` matches both bare and `mcp_<server>_<tool>` shapes; briefing, `/mcp` doctor, `isBrainOnline`, and `stripMcpPrefix` all collapsed to single-underscore lookups.
+- **Single-underscore tool naming standardised.** `mcp_<server>_<tool>` is the canonical form everywhere; double-underscore `mcp__<server>__<tool>` is deprecated and normalised at the pool boundary in `mcpPool.ts` so downstream code can assume one shape. CI grep guard ensures no `mcp__` references reappear outside the pool's normaliser.
+- **R1 guardrail recognises `task_agent` / `delegate_agent`.** Discovered during R2 review: `trackChildObservation` only matched `spawn_agent` / `spawn_agents`, so `delegate_agent` returns silently bypassed the child-drain guardrail. Extended to all four tool names; `task_agent` marks the child as already-waited (avoids double-drain), `delegate_agent` remains unwaited so the guardrail can force a wait before the parent answers.
+- **`task_agent` / `delegate_agent` access-mode gating.** Added to the read-only allowed-tool set alongside `spawn_agent`; without this, `read`-mode agents got "tool not permitted" errors on every call.
+- **`handleDelegateAgent` propagates errors verbatim.** When `handleSpawn` returns a non-object payload (no parseable id), the wrapper now passes it through instead of wrapping in `{raw, nextAction}` — preserves both the failure message and the child id the R1 guardrail needs.
+- **`handleWait` timeout no longer leaks setTimeout handles.** Cleared on every resolution path.
+- **`parseInt` NaN guard for `BRAINROUTER_MAX_SPAWN_DEPTH`.** Garbled env values now fall back to the default (3) instead of disabling the depth cap entirely.
+- **JWT base64url tampering detection.** `verifyJwt` in `brainrouter/src/api/auth/crypto.ts` now compares signatures in base64url string space; previous raw-byte comparison missed single-character changes to the final character's padding bits.
+
+## Deferred to 0.4.x
+
+- **`@mentions` tab completion.** Branch staged (`feature/0.3.8-11-at-mentions-tab-completion`) but PR not opened in cycle; carried forward.

package/changelog/README.md

@@ -0,0 +1,41 @@
+# BrainRouter Changelog Index
+
+Per-version release notes live here. The root
+[`CHANGELOG.md`](../CHANGELOG.md) stays short and only inlines the
+current in-flight release plus the latest shipped release.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ·
+Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## Versions
+
+| Version | Date | State | Highlights |
+|---|---:|---|---|
+| **[0.3.8](0.3.8.md)** | 2026-05-26 | Shipped | CLI delegation reliability, parallel-safe reads, cron `/schedule`, `/release-notes`, hooks docs, strict tool-call recovery, per-vendor MCP install snippets, native Anthropic adapter, briefing prefix fix, Ink question overlays |
+| **[0.3.7](0.3.7.md)** | 2026-05-26 | Shipped | Ink chat REPL, wizard, `/config`, `/login`, CLI/server env separation |
+| **[0.3.6](0.3.6.md)** | 2026-05-25 | Shipped | Context budget, MCP identity/offline UX, multi-MCP foundation, multi-workflow |
+| [0.3.5](0.3.5.md) | 2026-05-22 | Shipped | Global-install UX fix |
+| [0.3.4](0.3.4.md) | 2026-05-22 | Shipped | First public npm release |
+| [0.3.3](0.3.3.md) | 2026-05-21 | Shipped | `/goal` state machine and token budget |
+| [0.3.2](0.3.2.md) | 2026-05-19 | Shipped | Observability, headless behavior, statusline polish |
+| [0.3.1](0.3.1.md) | 2026-05-17 | Shipped | Reliability hardening |
+| [0.3.0](0.3.0.md) | 2026-05-16 | Shipped | Terminal Agent CLI, multi-agent orchestration, memory engine |
+| [0.2.0](0.2.0.md) | 2026-05-15 | Shipped | Admin console, Memories Hub, contradiction UI |
+
+---
+
+## Writing Rules
+
+1. Add user-visible changes to the in-flight version file in this
+   folder.
+2. Keep root [`CHANGELOG.md`](../CHANGELOG.md) as a concise summary,
+   not a duplicate of the full release file.
+3. When a version ships, replace `Unreleased` with the release date in
+   both places.
+4. Future planned work belongs in [`ROADMAP.md`](../ROADMAP.md), not in
+   changelog files.
+
+The [`changelog-generator` skill](../skills/lifecycle/changelog-generator/SKILL.md)
+can help assemble release notes from commits and task files.

package/dist/agent/agent.d.ts

@@ -1,4 +1,4 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 import type { LLMConfig } from '../config/config.js';
 import type { AccessMode } from '../orchestration/roles.js';
 import { type RecalledRecord } from '../memory/briefing.js';
@@ -33,6 +33,28 @@ export interface RunTurnCallbacks {
         preview?: string;
         error?: string;
     }) => void;
+    /**
+     * Optional: paired live child tool events surfaced from spawn_agent
+     * children up to the parent REPL. Lets the UI render explicit
+     * "child began Read(...)" / "child finished — 1.2s" rows in scrollback
+     * so long child runs no longer look like the parent has paused
+     * (roadmap §3 child progress visibility).
+     */
+    onChildToolStart?: (event: {
+        childId: string;
+        role: string;
+        tool: string;
+        args: Record<string, any>;
+    }) => void;
+    onChildToolEnd?: (event: {
+        childId: string;
+        role: string;
+        tool: string;
+        ok: boolean;
+        summary: string;
+        preview?: string;
+        durationMs: number;
+    }) => void;
     /**
      * Optional: invoked when the agent's automatic memory pipeline runs —
      * pre-turn briefing, post-turn capture, citation marking. Surfacing these
@@ -104,6 +126,10 @@ export interface AgentOptions {
      */
     parentTraceId?: string;
     parentSpanId?: string;
+    /** Agent tier — propagated from the definition so hierarchy checks work in grandchildren. */
+    tier?: 'chat' | 'reasoning' | 'worker';
+    /** Nesting depth in the spawn chain; 0 = direct child of the chat root (default). */
+    agentDepth?: number;
 }
 export declare const LOCAL_TOOLS: ({
     name: string;
@@ -744,11 +770,18 @@ export declare class Agent {
     readonly agentId: string;
     /** agent_id of the parent (set by spawn_agent for children). */
     private parentAgentId?;
+    /** Agent tier — forwarded to OrchestrationContext so grandchildren can inherit hierarchy checks. */
+    readonly tier?: 'chat' | 'reasoning' | 'worker';
+    /** Spawn-chain depth (0 = direct chat-root child). Forwarded to hierarchy checks. */
+    readonly agentDepth: number;
     constructor(mcpClient: McpClientWrapper, llmConfig: LLMConfig, options: AgentOptions);
     /** Expose for orchestration so spawn_agent can record the parent linkage. */
     getAgentId(): string;
     /** Internal — used by spawn_agent to record which parent dispatched us. */
     setParentAgentId(id: string | undefined): void;
+    private isModelVisibleMcpTool;
+    private rawMcpToolName;
+    private serverIdFromMcpToolName;
     private allowedToolsForAccess;
     runTurn(prompt: string, callbacks: RunTurnCallbacks): Promise<string>;
     /** Rough token estimate (1 token ≈ 4 characters of English / code). */