@kinqs/brainrouter-cli 0.3.7 → 0.3.8

package/dist/agent/toolCallRecovery.js

@@ -0,0 +1,130 @@
+// Strict tool-call recovery helpers (0.3.8-I4 / roadmap §8).
+//
+// Adapted from deer-flow/backend/packages/harness/deerflow/agents/middlewares/
+//   dangling_tool_call_middleware.py — same pattern: detect tool_calls that
+//   never received a paired tool_result and inject synthetic placeholders so
+//   strict OpenAI-compatible validators don't reject the next request.
+//
+// These helpers are intentionally pure (no agent.ts imports) so they can be
+// unit-tested in isolation and reused if another runtime grows similar needs.
+/**
+ * Drop duplicate tool_call ids inside a single assistant response. Keeps the
+ * LAST occurrence (closest to the model's final intent). Calls without a
+ * string id are passed through unchanged — the orphan safety net will catch
+ * them later.
+ *
+ * `onDuplicate` is invoked once per dropped duplicate so callers can log a
+ * warning without coupling this module to a logger.
+ */
+export function dedupeToolCalls(calls, onDuplicate) {
+    if (!Array.isArray(calls) || calls.length === 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (let i = calls.length - 1; i >= 0; i--) {
+        const c = calls[i];
+        const id = c?.id;
+        if (typeof id !== 'string' || id === '') {
+            out.push(c);
+            continue;
+        }
+        if (seen.has(id)) {
+            onDuplicate?.(id, i);
+            continue;
+        }
+        seen.add(id);
+        out.push(c);
+    }
+    return out.reverse();
+}
+/**
+ * Try-parse `tool_call.function.arguments`. On parse failure return a
+ * structured error string instead of throwing, so the caller can attach a
+ * synthetic tool_result that the next model turn can read.
+ */
+export function parseArgumentsOrError(call) {
+    const raw = call?.function?.arguments;
+    if (raw == null)
+        return { args: {}, rawArguments: '' };
+    if (typeof raw !== 'string') {
+        // Provider already parsed it for us.
+        return {
+            args: (raw && typeof raw === 'object') ? raw : {},
+            rawArguments: (() => { try {
+                return JSON.stringify(raw);
+            }
+            catch {
+                return String(raw);
+            } })(),
+        };
+    }
+    if (raw.trim() === '')
+        return { args: {}, rawArguments: raw };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            args: (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {},
+            rawArguments: raw,
+        };
+    }
+    catch (e) {
+        const msg = e?.message ?? String(e);
+        // Keep the raw arguments visible — the model often needs to see exactly
+        // what it produced to self-correct (e.g. trailing comma, missing quote).
+        const previewedRaw = raw.length > 400 ? `${raw.slice(0, 400)}…[truncated ${raw.length - 400} chars]` : raw;
+        return {
+            args: {},
+            error: `Tool argument JSON was malformed: ${msg}. Raw arguments emitted by the model: ${previewedRaw}. Re-issue the tool call with valid JSON arguments.`,
+            rawArguments: raw,
+        };
+    }
+}
+/**
+ * For every tool_call in `calls` that has no matching tool_result in
+ * `results`, build a synthetic tool message so the next LLM request stays
+ * well-formed (OpenAI strictly requires tool_call ↔ tool_result pairing).
+ *
+ * IMPORTANT: the synthetic `content` MUST start with `ERROR:` and be a plain
+ * string. The agent runtime's R1 child-drain guardrail tracks spawned
+ * children by `parseJsonObject(resultText)` on tool results — if the
+ * synthetic envelope parses as JSON with an `id` field, the guardrail would
+ * incorrectly think a child agent was spawned and try to wait on it.
+ */
+export function synthesizeOrphanResults(calls, results) {
+    if (!Array.isArray(calls) || calls.length === 0)
+        return [];
+    const have = new Set(results.map((r) => r.tool_call_id));
+    const synthetic = [];
+    for (const c of calls) {
+        const id = c?.id;
+        if (typeof id !== 'string' || id === '')
+            continue;
+        if (have.has(id))
+            continue;
+        synthetic.push({
+            role: 'tool',
+            tool_call_id: id,
+            name: c?.function?.name ?? 'unknown',
+            content: 'ERROR: tool call orphaned by model; no execution recorded. Re-issue the tool call if you still need this work done.',
+            isError: true,
+        });
+    }
+    return synthetic;
+}
+/**
+ * Use the caller's existing `normalizeToolName` to surface a "did you mean"
+ * suggestion when the LLM emits a tool name that doesn't exist as-is but
+ * normalizes to a real registered tool. Tolerates the single-underscore
+ * `mcp_<server>_<tool>` prefix (R5 convention) since `normalizeToolName`
+ * matches by flattened form.
+ */
+export function suggestSimilarToolName(raw, candidates, normalize) {
+    const trimmed = (raw ?? '').trim();
+    if (!trimmed || candidates.includes(trimmed))
+        return undefined;
+    const suggestion = normalize(trimmed, candidates);
+    if (suggestion && suggestion !== trimmed && candidates.includes(suggestion)) {
+        return suggestion;
+    }
+    return undefined;
+}

package/dist/agent/toolSafety.d.ts

@@ -0,0 +1,17 @@
+/**
+ * True iff `toolName` is on the conservative parallel-safe whitelist.
+ * Accepts both the bare local tool name (`read_file`) and the MCP-prefixed
+ * form (`mcp_brainrouter_memory_recall`). Anything else — including any
+ * unknown tool name — returns false so the caller falls back to safe
+ * serial execution.
+ */
+export declare function isParallelSafe(toolName: string): boolean;
+/** Companion to `isParallelSafe` — true iff the name resolves to a known MCP read tool. */
+export declare function isMcpReadTool(toolName: string): boolean;
+/**
+ * Kill switch: `BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS=false` (or `0`/`off`/`no`)
+ * forces every batch back to strict serial execution — the pre-R4 shape.
+ * Useful when debugging an issue and you want to rule out concurrency, or
+ * when running against an LLM provider that rate-limits tool dispatch.
+ */
+export declare function parallelExecutionEnabled(): boolean;

package/dist/agent/toolSafety.js

@@ -0,0 +1,102 @@
+// 0.3.8-R4 — Single source of truth for which tool calls are safe to
+// dispatch concurrently within one LLM response.
+//
+// Pre-R4 the runtime executed every tool call from one assistant message
+// strictly serially. That's safe but it's pure latency loss for the common
+// case of "read 5 files in one turn" — none of those reads share state or
+// depend on each other's results. Writes and shell commands still need to
+// serialize to preserve causality.
+//
+// `isParallelSafe(toolName)` is the conservative whitelist. Anything not on
+// the list is treated as serial — the failure mode is "we ran something
+// sequentially that could have been concurrent," which is the same
+// performance the pre-R4 code shipped with. Adding tools here is the only
+// way to opt them in.
+/**
+ * Local read-only tools whose execution is independent and has no
+ * observable side effect on the workspace, on child-session state, or on
+ * the agent's own bookkeeping. These can run concurrently within a single
+ * LLM response.
+ *
+ * Explicitly EXCLUDED (must stay serial):
+ *   - write_file / edit_file / apply_patch / run_command  — workspace mutation.
+ *   - spawn_agent / spawn_agents / task_agent / delegate_agent
+ *     / wait_agent / wait_agents / close_agent / route_agent
+ *     / read_agent_transcript  — orchestration / child-session mutation.
+ *     (R1's child-drain guardrail tracks every spawn/wait one-by-one;
+ *     running them in parallel would let bookkeeping diverge.)
+ *   - update_plan / goal_complete / goal_blocked  — session state mutation.
+ *   - ask_user_choice  — interactive picker; must not interleave with other UI.
+ *   - list_agents  — reads orchestration state but classified serial out of
+ *     caution; cheap and rarely batched.
+ */
+const PARALLEL_SAFE_LOCAL_TOOLS = new Set([
+    'read_file',
+    'list_dir',
+    'grep_search',
+    'glob_files',
+    'fetch_url',
+    'web_search',
+]);
+/**
+ * MCP read tools — bare tool names (without the `mcp_<server>_` prefix)
+ * that BrainRouter knows to be read-only. The pool normalises any legacy
+ * double-underscore emissions to the canonical single-underscore
+ * `mcp_<server>_<tool>` form at its boundary (0.3.8-R5), so the matcher
+ * here only deals with that one shape.
+ */
+const PARALLEL_SAFE_MCP_READ_TOOLS = new Set([
+    'memory_recall',
+    'memory_search',
+    'memory_file_history',
+    'memory_task_state',
+    'memory_contradictions',
+    'memory_inspect',
+    'memory_list_records',
+]);
+/**
+ * True iff `toolName` is on the conservative parallel-safe whitelist.
+ * Accepts both the bare local tool name (`read_file`) and the MCP-prefixed
+ * form (`mcp_brainrouter_memory_recall`). Anything else — including any
+ * unknown tool name — returns false so the caller falls back to safe
+ * serial execution.
+ */
+export function isParallelSafe(toolName) {
+    if (!toolName)
+        return false;
+    if (PARALLEL_SAFE_LOCAL_TOOLS.has(toolName))
+        return true;
+    const bare = stripMcpPrefix(toolName);
+    if (bare && PARALLEL_SAFE_MCP_READ_TOOLS.has(bare))
+        return true;
+    return false;
+}
+/** Companion to `isParallelSafe` — true iff the name resolves to a known MCP read tool. */
+export function isMcpReadTool(toolName) {
+    const bare = stripMcpPrefix(toolName);
+    return !!bare && PARALLEL_SAFE_MCP_READ_TOOLS.has(bare);
+}
+function stripMcpPrefix(name) {
+    // Canonical single-underscore shape: mcp_<server>_<tool>. Server names
+    // may contain underscores so we suffix-match against known bare tools
+    // instead of guessing where the server segment ends.
+    if (name.startsWith('mcp_')) {
+        for (const known of PARALLEL_SAFE_MCP_READ_TOOLS) {
+            if (name.endsWith('_' + known))
+                return known;
+        }
+    }
+    return undefined;
+}
+/**
+ * Kill switch: `BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS=false` (or `0`/`off`/`no`)
+ * forces every batch back to strict serial execution — the pre-R4 shape.
+ * Useful when debugging an issue and you want to rule out concurrency, or
+ * when running against an LLM provider that rate-limits tool dispatch.
+ */
+export function parallelExecutionEnabled() {
+    const raw = (process.env.BRAINROUTER_PARALLEL_SAFE_TOOL_CALLS ?? '').trim().toLowerCase();
+    if (raw === 'false' || raw === '0' || raw === 'off' || raw === 'no')
+        return false;
+    return true;
+}

package/dist/cli/banner.js

@@ -9,7 +9,7 @@ import { BOX } from './theme.js';
  * (chalk title + workspace line + connecting-to line) with a single visually
  * scannable block:
  *
- *   ╭─ 🧠 BrainRouter CLI 0.3.7 ──────────────────────────────╮
+ *   ╭─ 🧠 BrainRouter CLI 0.3.8 ──────────────────────────────╮
  *   │ workspace  BrainRouter  ·  c5b8c12d                     │
  *   │ mcp        local-http  ·  http  ·  online               │
  *   │ workflow   cli-shell-redesign  (in-progress)            │
@@ -26,7 +26,7 @@ import { BOX } from './theme.js';
  * The function returns a single string with embedded ANSI; the caller prints
  * it once. Pure-function so tests can assert against the rendered output.
  */
-const VERSION = '0.3.7';
+const VERSION = '0.3.8';
 const TITLE = '🧠 BrainRouter CLI';
 // Width floor for the BOXED banner. Below this we fall through to the
 // `renderPlainBanner` plaintext format. Was 56 — that caused the box to

package/dist/cli/cliPrompt.js

@@ -1,4 +1,5 @@
 import readline from 'node:readline';
+import { getAmbientChat } from './ink/ambientChat.js';
 /**
  * Shared bridge between the REPL's readline interface and modules outside
  * repl.ts that need to (a) write above the prompt without scrambling input,
@@ -33,6 +34,9 @@ export function isPickerActive() { return pickerActive; }
  * (e.g. piped non-interactive runs).
  */
 export function askYesNo(question, defaultValue = false) {
+    if (getAmbientChat() && process.stdin.isTTY) {
+        return runInkYesNo(question, defaultValue);
+    }
     if (!activeReadline || !process.stdin.isTTY) {
         return Promise.resolve(defaultValue);
     }
@@ -235,8 +239,69 @@ export function askChoice(question, options, opts = {}) {
         return Promise.reject(new NoTTYError('ask_user_choice requires an interactive TTY (no readline interface is active or stdin is not a TTY). ' +
             'Fall back to deciding yourself based on the available context, and state which option you picked and why in your reply.'));
     }
+    if (getAmbientChat()) {
+        return runInkChoice(question, options, opts);
+    }
     return runPicker(question, options, opts);
 }
+async function runInkYesNo(question, defaultValue) {
+    const { runPicker } = await import('./ink/runPicker.js');
+    const result = await runPicker({
+        title: question,
+        badge: 'Confirm',
+        rows: [
+            { id: 'yes', label: 'Yes', description: 'Allow this action' },
+            { id: 'no', label: 'No', description: 'Do not allow this action' },
+        ],
+        initialCursor: defaultValue ? 0 : 1,
+        allowOther: false,
+    });
+    if (result.kind !== 'pick')
+        return defaultValue;
+    return result.id === 'yes';
+}
+async function runInkChoice(question, options, opts) {
+    const { runPicker } = await import('./ink/runPicker.js');
+    const rows = options.map((option, i) => ({
+        id: `choice:${i}`,
+        label: option.label,
+        description: option.description,
+    }));
+    const result = await runPicker({
+        title: question,
+        badge: opts.header,
+        rows,
+        initialCursor: opts.initialCursor,
+        allowOther: true,
+        otherLabel: OTHER_LABEL,
+        otherDescription: OTHER_DESCRIPTION,
+        prefilledOther: opts.prefilledOther,
+        multiSelect: !!opts.multiSelect,
+        onCursorChange: opts.onCursorChange
+            ? (_id, index) => {
+                opts.onCursorChange?.(index);
+                return undefined;
+            }
+            : undefined,
+    });
+    if (result.kind === 'cancelled') {
+        throw new CancelledChoiceError();
+    }
+    if (result.kind === 'other') {
+        return result.text;
+    }
+    if (result.kind === 'multi') {
+        const answers = result.ids.map((id) => {
+            const idx = Number(id.slice('choice:'.length));
+            return options[idx]?.label;
+        }).filter((label) => !!label);
+        if (result.otherText)
+            answers.push(result.otherText);
+        return answers;
+    }
+    const idx = Number(result.id.slice('choice:'.length));
+    return options[idx]?.label ?? options[0].label;
+}
 function runPicker(question, options, opts) {
     return new Promise((resolve, reject) => {
         const rl = activeReadline;

package/dist/cli/commands/config.js

@@ -313,7 +313,7 @@ async function addMcpProfile(ctx, theme) {
     const nameRes = await promptText({
         theme,
         title: 'New MCP server — name',
-        subtitle: 'Short identifier. Used in tool prefixes: mcp__<name>__<tool>.',
+        subtitle: 'Short identifier. Used in tool prefixes: mcp_<name>_<tool>.',
         badge: 'MCP',
         placeholder: 'github, filesystem, my-brain, …',
         validate: (raw) => {

package/dist/cli/commands/mcp.d.ts

@@ -5,7 +5,7 @@
  *
  *   /mcp                    — alias for /mcp list
  *   /mcp list               — every configured profile + per-server status
- *   /mcp tools [server]     — MCP tools grouped by `mcp__<server>__*`
+ *   /mcp tools [server]     — MCP tools grouped by `mcp_<server>_*`
  *                             namespace; pass a server id to scope
  *   /mcp connect <name>     — connect a configured server that's idle/offline
  *   /mcp disconnect <name>  — close one server's transport (config preserved)

package/dist/cli/commands/mcp.js

@@ -5,7 +5,7 @@
  *
  *   /mcp                    — alias for /mcp list
  *   /mcp list               — every configured profile + per-server status
- *   /mcp tools [server]     — MCP tools grouped by `mcp__<server>__*`
+ *   /mcp tools [server]     — MCP tools grouped by `mcp_<server>_*`
  *                             namespace; pass a server id to scope
  *   /mcp connect <name>     — connect a configured server that's idle/offline
  *   /mcp disconnect <name>  — close one server's transport (config preserved)
@@ -22,6 +22,7 @@ import { resolveIdentityFromConfig } from '../../runtime/mcpClient.js';
 import { selectMcpServerIds } from '../../runtime/mcpPool.js';
 import { buildBannerInputs, renderBanner } from '../banner.js';
 import { resolveTheme } from '../theme.js';
+import { runMcpInstall } from './mcpInstall.js';
 export async function tryHandleMcpCommand(ctx) {
     const { command, args, mcpClient, config } = ctx;
     if (command !== '/mcp')
@@ -42,12 +43,28 @@ export async function tryHandleMcpCommand(ctx) {
             const res = await mcpClient.listTools();
             const allTools = res.tools || [];
             spinner.succeed(chalk.green(`${allTools.length} tools across ${connected.length} server${connected.length === 1 ? '' : 's'}`));
-            // Pool tools are exposed as `mcp__<serverId>__<rawTool>`. Group by serverId.
+            // Pool tools are exposed as `mcp_<serverId>_<rawTool>`. Group by serverId.
+            const knownIds = new Set(connected.map((s) => s.serverId));
             const byServer = {};
             for (const t of allTools) {
-                const m = /^mcp__([^_]+(?:_[^_]+)*?)__(.+)$/.exec(t.name);
-                const serverId = m?.[1] ?? '__unknown__';
-                const raw = m?.[2] ?? t.name;
+                let serverId = '__unknown__';
+                let raw = t.name;
+                if (t.name.startsWith('mcp_')) {
+                    const rest = t.name.slice('mcp_'.length);
+                    // Server ids may contain underscores; match the longest known id.
+                    const id = [...knownIds].sort((a, b) => b.length - a.length).find((k) => rest.startsWith(`${k}_`));
+                    if (id) {
+                        serverId = id;
+                        raw = rest.slice(id.length + 1);
+                    }
+                    else {
+                        const idx = rest.indexOf('_');
+                        if (idx > 0) {
+                            serverId = rest.slice(0, idx);
+                            raw = rest.slice(idx + 1);
+                        }
+                    }
+                }
                 if (onlyServer && serverId !== onlyServer)
                     continue;
                 (byServer[serverId] ||= []).push(raw);
@@ -64,7 +81,7 @@ export async function tryHandleMcpCommand(ctx) {
                     const identTag = formatIdentityTag(ident);
                     console.log(`  ${chalk.bold.green(id)} ${identTag} (${byServer[id].length})`);
                     for (const name of byServer[id].sort()) {
-                        console.log(`    ${chalk.gray('•')} ${name}  ${chalk.gray(`mcp__${id}__${name}`)}`);
+                        console.log(`    ${chalk.gray('•')} ${name}  ${chalk.gray(`mcp_${id}_${name}`)}`);
                     }
                 }
             }
@@ -200,6 +217,11 @@ export async function tryHandleMcpCommand(ctx) {
         }
         return true;
     }
+    if (sub === 'install') {
+        const result = runMcpInstall(args.slice(1), config);
+        console.log(result.output);
+        return true;
+    }
     if (sub === 'disconnect') {
         if (!targetName) {
             console.log(chalk.red('\nUsage: /mcp disconnect <name>\n'));
@@ -218,7 +240,7 @@ export async function tryHandleMcpCommand(ctx) {
         }
         return true;
     }
-    console.log(chalk.red(`\nUnknown /mcp subcommand "${sub}". Usage: /mcp list | /mcp tools [server] | /mcp connect <name> | /mcp disconnect <name> | /mcp reconnect [name]\n`));
+    console.log(chalk.red(`\nUnknown /mcp subcommand "${sub}". Usage: /mcp list | /mcp tools [server] | /mcp connect <name> | /mcp disconnect <name> | /mcp reconnect [name] | /mcp install <vendor>|list\n`));
     return true;
 }
 function formatIdentityTag(identity) {

package/dist/cli/commands/mcpInstall.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `/mcp install` — generates per-vendor MCP config snippets for non-CLI
+ * hosts (Claude Desktop, Cursor, Windsurf, VS Code Continue, Zed, Cline).
+ *
+ * Pattern: print-only. We do NOT write to vendor config files — the user
+ * pastes the block themselves. Direct-write is a future enhancement
+ * (roadmap: tracked under post-0.4.0 polish; intentionally not a follow-up).
+ *
+ * Adapted from semble's per-agent install docs pattern
+ * (openSrc/semble/src/semble/agents/) — one focused entry per vendor.
+ */
+import type { Config } from '../../config/config.js';
+export interface RenderResult {
+    ok: boolean;
+    output: string;
+}
+export interface RunOpts {
+    platform?: NodeJS.Platform;
+}
+export declare function runMcpInstall(args: string[], config: Config, opts?: RunOpts): RenderResult;

package/dist/cli/commands/mcpInstall.js

@@ -0,0 +1,87 @@
+/**
+ * `/mcp install` — generates per-vendor MCP config snippets for non-CLI
+ * hosts (Claude Desktop, Cursor, Windsurf, VS Code Continue, Zed, Cline).
+ *
+ * Pattern: print-only. We do NOT write to vendor config files — the user
+ * pastes the block themselves. Direct-write is a future enhancement
+ * (roadmap: tracked under post-0.4.0 polish; intentionally not a follow-up).
+ *
+ * Adapted from semble's per-agent install docs pattern
+ * (openSrc/semble/src/semble/agents/) — one focused entry per vendor.
+ */
+import chalk from 'chalk';
+import { displayPath, getVendor, listVendors, renderSnippet, VENDORS } from '../../runtime/vendorSnippets.js';
+/**
+ * Resolve the active BrainRouter profile from config. Returns null when
+ * the user hasn't logged in yet — caller prints a `/login` hint.
+ */
+function resolveActiveBrainrouter(config) {
+    const name = config.activeServer;
+    if (!name)
+        return null;
+    const profile = config.servers?.[name];
+    if (!profile)
+        return null;
+    if (profile.type !== 'http')
+        return null;
+    const url = profile.url?.trim();
+    const apiKey = profile.apiKey?.trim();
+    if (!url || !apiKey)
+        return null;
+    return { url, apiKey };
+}
+export function runMcpInstall(args, config, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const sub = (args[0] ?? '').toLowerCase();
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        return {
+            ok: true,
+            output: `${chalk.bold('Usage')}\n` +
+                `  /mcp install list           — list supported vendors\n` +
+                `  /mcp install <vendor>       — print paste-ready snippet for one vendor\n\n` +
+                `Vendors: ${listVendors().map((v) => v.id).join(', ')}\n`,
+        };
+    }
+    if (sub === 'list') {
+        const lines = [chalk.bold('\nSupported MCP hosts')];
+        for (const v of listVendors()) {
+            const p = displayPath(v.configPath(platform), platform);
+            lines.push(`  ${chalk.bold.cyan(v.id.padEnd(18))} ${chalk.gray(v.label.padEnd(28))} ${chalk.gray(p)}`);
+        }
+        lines.push('', chalk.gray(`Run "/mcp install <id>" for a paste-ready snippet.`), '');
+        return { ok: true, output: lines.join('\n') };
+    }
+    const entry = getVendor(sub);
+    if (!entry) {
+        return {
+            ok: false,
+            output: chalk.red(`\nUnknown vendor "${sub}".\n`) +
+                chalk.gray(`Known: ${Object.keys(VENDORS).join(', ')}\n`),
+        };
+    }
+    const active = resolveActiveBrainrouter(config);
+    if (!active) {
+        return {
+            ok: false,
+            output: chalk.red('\nNo active BrainRouter profile with URL + API key.\n') +
+                chalk.gray('Run `/login` to configure one, then re-run this command.\n'),
+        };
+    }
+    const snippet = renderSnippet(entry, { url: active.url, apiKey: active.apiKey });
+    const configPath = displayPath(entry.configPath(platform), platform);
+    const out = [];
+    out.push('');
+    out.push(chalk.bold.cyan(`${entry.label}  (${entry.id})`));
+    out.push(chalk.gray(`Config file: ${configPath}`));
+    if (entry.note)
+        out.push(chalk.gray(`Note:        ${entry.note}`));
+    out.push('');
+    out.push(chalk.yellow('⚠  This block contains your live API key — paste into your vendor config and do not commit.'));
+    out.push('');
+    out.push(snippet);
+    out.push('');
+    out.push(chalk.gray(`Restart: ${entry.restart}`));
+    out.push(chalk.gray('Web reference: brainrouter-docs/mcp-install.md'));
+    out.push('');
+    return { ok: true, output: out.join('\n') };
+}

package/dist/cli/commands/orchestration.js

@@ -44,6 +44,39 @@ export async function tryHandleOrchestrationCommand(ctx) {
                     console.log();
                     return true;
                 }
+                // `--watch`: poll the same data shape every second and re-render the
+                // running-children list inline. Same shape as `/agents` and the Ink
+                // status row so the user gets a single mental model (roadmap §3).
+                if (args.includes('--watch')) {
+                    const intervalMs = 1000;
+                    const maxTicks = 600; // ~10 min safety cap; Ctrl-C exits early.
+                    let ticks = 0;
+                    console.log(chalk.bold('\nWatching child agents (Ctrl-C to stop)…'));
+                    await new Promise((resolve) => {
+                        const handle = setInterval(() => {
+                            reconcileStale(agent.workspaceRoot);
+                            const running = listSessions(agent.workspaceRoot)
+                                .filter((s) => s.status === 'pending' || s.status === 'running');
+                            const stamp = new Date().toISOString().slice(11, 19);
+                            if (running.length === 0) {
+                                process.stdout.write(`\r[${stamp}] no running children${' '.repeat(40)}`);
+                            }
+                            else {
+                                const parts = running.map((s) => `${s.id.slice(0, 14)} (${s.role})`).join(', ');
+                                process.stdout.write(`\r[${stamp}] running: ${parts}${' '.repeat(10)}`);
+                            }
+                            if (++ticks >= maxTicks) {
+                                clearInterval(handle);
+                                process.stdout.write('\n');
+                                resolve();
+                            }
+                        }, intervalMs);
+                        const onSig = () => { clearInterval(handle); process.stdout.write('\n'); process.off('SIGINT', onSig); resolve(); };
+                        process.once('SIGINT', onSig);
+                    });
+                    console.log();
+                    return true;
+                }
                 reconcileStale(agent.workspaceRoot);
                 const sessions = listSessions(agent.workspaceRoot);
                 // `--json` for scripting. Emits a single JSON line on stdout so

package/dist/cli/commands/releaseNotes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `/release-notes` slash command — show the changelog for the running CLI version.
+ *
+ *   /release-notes            → current version's notes
+ *   /release-notes <version>  → specific version
+ *   /release-notes list       → every shipped version, sorted descending
+ *
+ * Changelog files ship inside the published package at `changelog/<version>.md`.
+ * The repo-root `brainrouter-changelog/` is copied into `brainrouter-cli/changelog/`
+ * by `prepublishOnly` so users who install via npm see them.
+ */
+import type { CommandContext } from './_context.js';
+export interface ReleaseNotesDeps {
+    /** Override the changelog directory (tests). Defaults to bundled `changelog/`. */
+    changelogDir?: string;
+    /** Override the current version (tests). Defaults to package.json#version. */
+    currentVersion?: string;
+}
+export declare function tryHandleReleaseNotesCommand(ctx: CommandContext, deps?: ReleaseNotesDeps): Promise<boolean>;
+/**
+ * Pure handler — returns the rendered string. Split from `tryHandle*` so unit
+ * tests can assert on the output without capturing stdout.
+ */
+export declare function runReleaseNotes(args: string[], deps?: ReleaseNotesDeps): string;