@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/dist/cli/commands/mcp.js

@@ -1,53 +1,88 @@
 /**
- * 0.3.6 item 11: `/mcp` slash-command surface. Scope-limited foundation —
- * the full multi-MCP federation (parallel cross-MCP tool calls, MCP
- * marketplace, capability tiers) is deferred to 0.4.0. What ships here:
+ * `/mcp` slash-command surface. 0.3.7 multi-MCP rewrite — third-party
+ * MCPs connect concurrently while BrainRouter MCP profiles are mutually
+ * exclusive so exactly one brain is active at a time.
  *
- *   /mcp           — show status of the active MCP (alias for /mcp list)
- *   /mcp list      — list every configured profile with identity + status
- *   /mcp reconnect — reconnect the currently-active profile
- *   /mcp tools     — list MCP tools grouped by namespace (pre-Item-11
- *                    `/mcp` no-arg behaviour, moved here verbatim)
+ *   /mcp                    — alias for /mcp list
+ *   /mcp list               — every configured profile + per-server status
+ *   /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)
+ *   /mcp reconnect [name]   — reconnect ONE (when name given) or the selected pool
  *
- * The reconnect path leans on `mcpClient.close()` + `mcpClient.connect()`
- * with the same config the CLI launched against — no plumbing required
- * for the user beyond typing the command.
+ * Backwards-compat: `/mcp reconnect` with no arg reconnects the same
+ * selected set used at boot: all third-party MCPs plus the active
+ * BrainRouter MCP. Pass an explicit name to target one.
  */
 import chalk from 'chalk';
 import { spinner as makeSpinner } from '../spinner.js';
+import { saveConfig } from '../../config/config.js';
+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')
         return false;
     const sub = (args[0] ?? 'list').toLowerCase();
+    const targetName = args[1]?.trim();
     if (sub === 'tools') {
-        // Pre-Item-11 `/mcp` no-arg behaviour: namespace-grouped tool listing.
-        // Kept verbatim under a subcommand so the muscle memory survives.
-        const profileName = config.activeServer;
-        const server = config.servers[profileName];
-        console.log(chalk.bold('\nMCP server'));
-        console.log(`  Profile: ${chalk.green(profileName)} (${chalk.cyan(server?.type ?? 'unknown')})`);
-        if (server?.type === 'http') {
-            console.log(`  URL:     ${chalk.blue(server.url ?? '')}`);
-        }
-        else if (server?.type === 'stdio') {
-            console.log(`  Cmd:     ${chalk.blue(server.command ?? '')} ${server.args?.join(' ') || ''}`);
-        }
-        const spinner = makeSpinner(chalk.gray('Fetching MCP tool surface...')).start();
+        const onlyServer = targetName;
+        console.log(chalk.bold('\nMCP tools (pooled)'));
+        const statuses = mcpClient.getStatuses();
+        const connected = statuses.filter((s) => s.status === 'connected');
+        if (connected.length === 0) {
+            console.log(chalk.yellow('  No MCP servers connected. Try /mcp reconnect.\n'));
+            return true;
+        }
+        const spinner = makeSpinner(chalk.gray('Fetching pooled tool surface...')).start();
         try {
             const res = await mcpClient.listTools();
-            const tools = res.tools || [];
-            spinner.succeed(chalk.green(`${tools.length} MCP tools available`));
-            const namespaces = {};
-            for (const t of tools) {
-                const parts = (t.name || '').split('_');
-                const ns = parts.length > 1 ? parts[0] : 'misc';
-                (namespaces[ns] ||= []).push(t.name);
+            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.
+            const knownIds = new Set(connected.map((s) => s.serverId));
+            const byServer = {};
+            for (const t of allTools) {
+                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);
+            }
+            const serverIds = Object.keys(byServer).sort();
+            if (serverIds.length === 0) {
+                console.log(chalk.gray(`\n  No tools for server "${onlyServer}".\n`));
+                return true;
             }
-            for (const ns of Object.keys(namespaces).sort()) {
-                console.log(`\n  ${chalk.bold.cyan(ns)} (${namespaces[ns].length})`);
-                for (const name of namespaces[ns].sort()) {
-                    console.log(`    ${chalk.gray('•')} ${name}`);
+            for (const section of groupServerIdsByEcosystem(serverIds, (id) => mcpClient.getStatus(id)?.identity ?? 'unknown')) {
+                console.log(`\n${section.title}`);
+                for (const id of section.ids) {
+                    const ident = mcpClient.getStatus(id)?.identity ?? 'unknown';
+                    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}`)}`);
+                    }
                 }
             }
         }
@@ -58,64 +93,216 @@ export async function tryHandleMcpCommand(ctx) {
         return true;
     }
     if (sub === 'list') {
-        const activeName = config.activeServer;
         const profiles = Object.keys(config.servers ?? {});
         if (profiles.length === 0) {
-            console.log(chalk.yellow('\nNo MCP profiles configured. Run `brainrouter login` or `brainrouter config` to set one up.\n'));
+            console.log(chalk.yellow('\nNo MCP profiles configured. Run `/login` or `brainrouter config` to set one up.\n'));
             return true;
         }
-        console.log(chalk.bold('\nConfigured MCP profiles'));
-        for (const name of profiles) {
+        console.log(chalk.bold('\nMCP servers'));
+        const statuses = mcpClient.getStatuses();
+        const statusById = new Map(statuses.map((s) => [s.serverId, s]));
+        const activeName = config.activeServer;
+        for (const section of groupServerIdsByEcosystem(profiles, (name) => {
             const profile = config.servers[name];
-            const isActive = name === activeName;
-            // Identity: explicit config field > live wrapper > 'unknown'.
-            let identity = profile.identity ?? 'unknown';
-            if (isActive && typeof mcpClient.getIdentity === 'function') {
-                identity = mcpClient.getIdentity();
+            return statusById.get(name)?.identity ?? profile?.identity ?? 'unknown';
+        })) {
+            console.log(`\n${section.title}`);
+            for (const name of section.ids) {
+                const profile = config.servers[name];
+                const poolStatus = statusById.get(name);
+                // Identity: pool live > config metadata > 'unknown'.
+                const identity = poolStatus?.identity ?? profile.identity ?? 'unknown';
+                // Status: pool live > 'not in pool' (configured but never tried).
+                const liveStatus = poolStatus?.status;
+                const statusLabel = liveStatus === 'connected' ? chalk.green('online') :
+                    liveStatus === 'failed' ? chalk.red('failed') :
+                        liveStatus === 'connecting' ? chalk.yellow('connecting') :
+                            liveStatus === 'offline' ? chalk.gray('disconnected') :
+                                chalk.gray('idle');
+                const idLabel = formatIdentityTag(identity);
+                const marker = name === activeName ? chalk.bold('★ ') : '  ';
+                const transport = profile.type;
+                const target = profile.type === 'http' ? profile.url ?? '<no url>' : profile.command ?? '<no command>';
+                const toolTag = poolStatus?.toolCount != null ? chalk.gray(`${poolStatus.toolCount} tools`) : '';
+                const errTag = liveStatus === 'failed' && poolStatus?.error ? chalk.red(` · ${poolStatus.error}`) : '';
+                console.log(`${marker}${chalk.bold(name)}  ${idLabel}  ${transport}  ${statusLabel}  ${chalk.gray(target)}  ${toolTag}${errTag}`);
             }
-            const onlineLabel = isActive
-                ? (mcpClient.isConnected() ? chalk.green('online') : chalk.red('offline'))
-                : chalk.gray('idle');
-            const idLabel = identity === 'brainrouter'
-                ? chalk.cyan('brainrouter')
-                : identity === 'third-party'
-                    ? chalk.yellow('third-party')
-                    : chalk.gray('unknown');
-            const marker = isActive ? chalk.bold('★ ') : '  ';
-            const transport = profile.type;
-            const target = profile.type === 'http' ? profile.url ?? '<no url>' : profile.command ?? '<no command>';
-            console.log(`${marker}${chalk.bold(name)}  ${idLabel}  ${transport}  ${onlineLabel}  ${chalk.gray(target)}`);
-        }
-        console.log(chalk.gray('\n★ = active profile.  /mcp reconnect to refresh the active connection.\n'));
+        }
+        console.log(chalk.gray('\n★ = highlighted profile in the banner.'));
+        console.log(chalk.gray('  Multi-MCP: third-party MCPs connect together; only one BrainRouter MCP is active. Use /mcp connect|disconnect|reconnect <name> to manage.\n'));
         return true;
     }
     if (sub === 'reconnect') {
-        const activeName = config.activeServer;
-        const profile = config.servers?.[activeName];
-        if (!profile) {
-            console.log(chalk.red(`\nNo active MCP profile to reconnect (\`activeServer\` = ${JSON.stringify(activeName)}).\n`));
+        if (!targetName) {
+            // No name → reconnect every configured server in the pool.
+            const ids = selectMcpServerIds(config.servers ?? {}, config.activeServer);
+            if (ids.length === 0) {
+                console.log(chalk.red(`\nNo MCP profiles configured.\n`));
+                return true;
+            }
+            console.log(chalk.gray(`Reconnecting all servers (${ids.length})…`));
+            await Promise.allSettled(ids.map(async (id) => {
+                try {
+                    await mcpClient.reconnectOne(id);
+                    const s = mcpClient.getStatus(id);
+                    if (s?.status === 'connected') {
+                        console.log(chalk.green(`  ✓ ${id}`));
+                    }
+                    else {
+                        console.log(chalk.red(`  ✗ ${id} — ${s?.error ?? 'failed'}`));
+                    }
+                }
+                catch (err) {
+                    console.log(chalk.red(`  ✗ ${id} — ${err?.message ?? err}`));
+                }
+            }));
+            console.log();
+            return true;
+        }
+        if (!config.servers?.[targetName]) {
+            console.log(chalk.red(`\nNo profile named "${targetName}".\n`));
             return true;
         }
-        console.log(chalk.gray(`Reconnecting "${activeName}"…`));
+        console.log(chalk.gray(`Reconnecting "${targetName}"…`));
         try {
-            try {
-                await mcpClient.close();
+            await disconnectOtherBrainrouterServers(ctx, targetName);
+            await mcpClient.reconnectOne(targetName);
+            const s = mcpClient.getStatus(targetName);
+            if (s?.status === 'connected') {
+                const activated = activateBrainrouterProfile(ctx, targetName);
+                console.log(chalk.green(`✓ Reconnected to "${targetName}".\n`));
+                if (activated) {
+                    console.log(chalk.gray(`  Active BrainRouter profile saved as "${targetName}" for this and future sessions.\n`));
+                    printRefreshedBanner(ctx);
+                }
             }
-            catch { /* idempotent */ }
-            await mcpClient.connect(profile, config.llm, activeName);
-            // Re-probe tools so identity tagging and the prompt's tool list refresh.
-            try {
-                await mcpClient.listTools();
+            else {
+                console.log(chalk.red(`✗ "${targetName}" remained ${s?.status ?? 'offline'} — ${s?.error ?? 'unknown'}\n`));
             }
-            catch { /* tool-list failure is non-fatal */ }
-            console.log(chalk.green(`✓ Reconnected to "${activeName}" (${profile.type}).\n`));
         }
         catch (err) {
             console.log(chalk.red(`✗ Reconnect failed: ${err?.message ?? err}\n`));
-            console.log(chalk.gray('The CLI stays in offline mode. Check the MCP server, then try `/mcp reconnect` again.\n'));
         }
         return true;
     }
-    console.log(chalk.red(`\nUnknown /mcp subcommand "${sub}". Usage: /mcp list | /mcp reconnect | /mcp tools\n`));
+    if (sub === 'connect') {
+        if (!targetName) {
+            console.log(chalk.red('\nUsage: /mcp connect <name>\n'));
+            return true;
+        }
+        const profile = config.servers?.[targetName];
+        if (!profile) {
+            console.log(chalk.red(`\nNo profile named "${targetName}". Available: ${Object.keys(config.servers ?? {}).join(', ') || '(none)'}.\n`));
+            return true;
+        }
+        console.log(chalk.gray(`Connecting "${targetName}"…`));
+        try {
+            await disconnectOtherBrainrouterServers(ctx, targetName);
+            await mcpClient.connectOne(targetName, profile, config.llm, 5_000);
+            const s = mcpClient.getStatus(targetName);
+            if (s?.status === 'connected') {
+                const activated = activateBrainrouterProfile(ctx, targetName);
+                console.log(chalk.green(`✓ "${targetName}" online (${s.toolCount ?? 0} tools).\n`));
+                if (activated) {
+                    console.log(chalk.gray(`  Active BrainRouter profile saved as "${targetName}" for this and future sessions.\n`));
+                    printRefreshedBanner(ctx);
+                }
+            }
+            else {
+                console.log(chalk.red(`✗ "${targetName}" failed — ${s?.error ?? 'unknown'}\n`));
+            }
+        }
+        catch (err) {
+            console.log(chalk.red(`✗ Connect failed: ${err?.message ?? err}\n`));
+        }
+        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'));
+            return true;
+        }
+        if (!mcpClient.getStatus(targetName)) {
+            console.log(chalk.yellow(`\n"${targetName}" is not in the pool.\n`));
+            return true;
+        }
+        try {
+            await mcpClient.disconnectOne(targetName);
+            console.log(chalk.green(`✓ "${targetName}" disconnected. Config preserved — /mcp connect ${targetName} to bring it back.\n`));
+        }
+        catch (err) {
+            console.log(chalk.red(`✗ Disconnect failed: ${err?.message ?? err}\n`));
+        }
+        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] | /mcp install <vendor>|list\n`));
+    return true;
+}
+function formatIdentityTag(identity) {
+    return identity === 'brainrouter' ? chalk.cyan('brainrouter') :
+        identity === 'third-party' ? chalk.yellow('third-party') :
+            chalk.gray('unknown');
+}
+function groupServerIdsByEcosystem(ids, identityFor) {
+    const brainrouter = [];
+    const other = [];
+    for (const id of ids.slice().sort()) {
+        if (identityFor(id) === 'brainrouter')
+            brainrouter.push(id);
+        else
+            other.push(id);
+    }
+    const sections = [];
+    if (brainrouter.length > 0) {
+        sections.push({ title: chalk.bold.cyan('BrainRouter MCP (Our Ecosystem)'), ids: brainrouter });
+    }
+    if (other.length > 0) {
+        sections.push({ title: chalk.bold.yellow('Third-party MCPs (Other)'), ids: other });
+    }
+    return sections;
+}
+async function disconnectOtherBrainrouterServers(ctx, targetName) {
+    const targetProfile = ctx.config.servers?.[targetName];
+    if (!targetProfile)
+        return;
+    if (resolveIdentityFromConfig(targetProfile, targetName) !== 'brainrouter')
+        return;
+    for (const [id, profile] of Object.entries(ctx.config.servers ?? {})) {
+        if (id === targetName)
+            continue;
+        if (resolveIdentityFromConfig(profile, id) !== 'brainrouter')
+            continue;
+        const status = ctx.mcpClient.getStatus(id);
+        if (status?.status === 'connected' || status?.status === 'connecting') {
+            await ctx.mcpClient.disconnectOne(id);
+        }
+    }
+}
+function activateBrainrouterProfile(ctx, targetName) {
+    const status = ctx.mcpClient.getStatus(targetName);
+    const profile = ctx.config.servers?.[targetName];
+    const isBrainrouter = status?.identity === 'brainrouter' ||
+        (profile ? resolveIdentityFromConfig(profile, targetName) === 'brainrouter' : false);
+    if (!isBrainrouter)
+        return false;
+    ctx.config.activeServer = targetName;
+    saveConfig(ctx.config);
     return true;
 }
+function printRefreshedBanner(ctx) {
+    const theme = resolveTheme(ctx.agent.workspaceRoot);
+    const banner = renderBanner(buildBannerInputs(ctx.config, ctx.agent, ctx.mcpClient), theme);
+    if (ctx.repl.replaceBanner) {
+        ctx.repl.replaceBanner('\n' + banner);
+    }
+    else {
+        console.log(chalk.gray('Updated active BrainRouter banner:'));
+        console.log(banner);
+        console.log();
+    }
+}

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

@@ -5,6 +5,7 @@
 import chalk from 'chalk';
 import { childSessionKey } from '../../runtime/mcpUtils.js';
 import { listRoles } from '../../orchestration/roles.js';
+import { listAll as listAgentDefs } from '../../orchestration/agentRegistry.js';
 import { formatSessionSummary, getSession, listSessions, reconcileStale } from '../../orchestration/orchestrator.js';
 import { readPreferences, writePreferences } from '../../state/preferencesStore.js';
 import { readTranscriptEntries } from '../../state/sessionStore.js';
@@ -26,6 +27,56 @@ export async function tryHandleOrchestrationCommand(ctx) {
             }
         case '/agents':
             {
+                if (args[0] === 'defs') {
+                    const defs = listAgentDefs(agent.workspaceRoot);
+                    console.log(chalk.bold('\nAgent Definitions:'));
+                    const ID_W = Math.max(...defs.map((l) => l.def.id.length), 4) + 2;
+                    const TIER_W = 12;
+                    const SRC_W = 10;
+                    console.log(chalk.gray(`  ${'ID'.padEnd(ID_W)}${'TIER'.padEnd(TIER_W)}${'SOURCE'.padEnd(SRC_W)}PATH`));
+                    for (const loaded of defs) {
+                        const idStr = chalk.cyan(loaded.def.id.padEnd(ID_W));
+                        const tierColor = loaded.def.tier === 'reasoning' ? chalk.blue : chalk.yellow;
+                        const tierStr = tierColor(loaded.def.tier.padEnd(TIER_W));
+                        const srcStr = chalk.gray(loaded.source.padEnd(SRC_W));
+                        console.log(`  ${idStr}${tierStr}${srcStr}${chalk.gray(loaded.filePath)}`);
+                    }
+                    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;