@kinqs/brainrouter-cli 0.3.6 → 0.3.7

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/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';
@@ -104,6 +104,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 +748,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). */

package/dist/agent/agent.js

@@ -23,6 +23,53 @@ import { renderCompactSystemMessage, runCompaction } from '../prompt/compactor.j
 import { buildFanOutHint, shouldSuggestFanOut } from '../prompt/breadthHint.js';
 const execPromise = promisify(exec);
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.DS_Store', '.next']);
+function parseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectChildIds(value) {
+    if (!value || typeof value !== 'object')
+        return [];
+    const ids = [];
+    const maybeRecord = value;
+    if (typeof maybeRecord.id === 'string')
+        ids.push(maybeRecord.id);
+    if (Array.isArray(maybeRecord.agents)) {
+        for (const entry of maybeRecord.agents) {
+            if (entry && typeof entry === 'object' && typeof entry.id === 'string') {
+                ids.push(entry.id);
+            }
+        }
+    }
+    return [...new Set(ids)];
+}
+function trackChildObservation(toolName, args, resultText, spawned, waited) {
+    if (toolName === 'spawn_agent' || toolName === 'spawn_agents') {
+        const ids = collectChildIds(parseJsonObject(resultText));
+        for (const id of ids) {
+            spawned.add(id);
+            if (toolName === 'spawn_agent' && args?.wait)
+                waited.add(id);
+        }
+        return;
+    }
+    if (toolName === 'wait_agent') {
+        const id = typeof args?.id === 'string' ? args.id : undefined;
+        if (id)
+            waited.add(id);
+        return;
+    }
+    if (toolName === 'wait_agents') {
+        const ids = Array.isArray(args?.ids) ? args.ids.filter((id) => typeof id === 'string') : [];
+        for (const id of ids)
+            waited.add(id);
+    }
+}
 export const LOCAL_TOOLS = [
     {
         name: 'read_file',
@@ -414,6 +461,10 @@ export class Agent {
     agentId = `agent-${Math.random().toString(36).slice(2, 8)}`;
     /** agent_id of the parent (set by spawn_agent for children). */
     parentAgentId;
+    /** Agent tier — forwarded to OrchestrationContext so grandchildren can inherit hierarchy checks. */
+    tier;
+    /** Spawn-chain depth (0 = direct chat-root child). Forwarded to hierarchy checks. */
+    agentDepth;
     constructor(mcpClient, llmConfig, options) {
         this.mcpClient = mcpClient;
         this.llmConfig = llmConfig;
@@ -437,6 +488,8 @@ export class Agent {
         this.systemPromptOverride = options.systemPromptOverride;
         this.parentTraceId = options.parentTraceId;
         this.parentSpanId = options.parentSpanId;
+        this.tier = options.tier;
+        this.agentDepth = options.agentDepth ?? 0;
     }
     /** Expose for orchestration so spawn_agent can record the parent linkage. */
     getAgentId() {
@@ -446,6 +499,47 @@ export class Agent {
     setParentAgentId(id) {
         this.parentAgentId = id;
     }
+    isModelVisibleMcpTool(tool) {
+        const hiddenBrainrouterTools = new Set([
+            'memory_capture_turn',
+            'memory_mark_cited',
+            'memory_resolve_session',
+            'memory_register_skill_hints',
+            'memory_hook_register',
+            'memory_hook_status',
+        ]);
+        const name = String(tool?.name ?? '');
+        const rawName = String(tool?.__rawName ?? this.rawMcpToolName(name));
+        if (!hiddenBrainrouterTools.has(rawName))
+            return true;
+        const serverId = typeof tool?.__serverId === 'string'
+            ? tool.__serverId
+            : this.serverIdFromMcpToolName(name);
+        const status = serverId && typeof this.mcpClient.getStatus === 'function'
+            ? this.mcpClient.getStatus(serverId)
+            : undefined;
+        // Hide only BrainRouter auto-pipeline/admin tools. Third-party MCP tools
+        // with coincidentally similar names stay visible.
+        return status?.identity !== 'brainrouter';
+    }
+    rawMcpToolName(name) {
+        const serverId = this.serverIdFromMcpToolName(name);
+        return serverId ? name.slice(`mcp__${serverId}__`.length) : name;
+    }
+    serverIdFromMcpToolName(name) {
+        if (!name.startsWith('mcp__'))
+            return undefined;
+        const rest = name.slice('mcp__'.length);
+        if (typeof this.mcpClient.getServerIds === 'function') {
+            const ids = this.mcpClient.getServerIds();
+            for (const id of ids.sort((a, b) => b.length - a.length)) {
+                if (rest.startsWith(`${id}__`))
+                    return id;
+            }
+        }
+        const idx = rest.indexOf('__');
+        return idx >= 0 ? rest.slice(0, idx) : undefined;
+    }
     allowedToolsForAccess() {
         // Lifecycle / inspection tools are always available regardless of access
         // mode — they don't touch the workspace and the agent needs them to end
@@ -504,27 +598,20 @@ export class Agent {
         // whenever the inventory shape changed (online → offline or vice
         // versa) so the next LLM call sees the correct system message.
         const prevTools = this.lastKnownMcpTools?.map((t) => t.name).sort().join(',');
-        this.lastKnownMcpTools = mcpTools.map((t) => ({ name: t.name }));
+        this.lastKnownMcpTools = mcpTools.map((t) => ({
+            name: String(t?.__rawName ?? this.rawMcpToolName(String(t?.name ?? ''))),
+        }));
         const newTools = this.lastKnownMcpTools.map((t) => t.name).sort().join(',');
         if (prevTools !== newTools && this.chatHistory.length > 0 && this.chatHistory[0].role === 'system') {
             this.chatHistory[0] = this.createSystemMessage();
         }
         const allowed = this.allowedToolsForAccess();
         const filteredLocalTools = LOCAL_TOOLS.filter(t => allowed.has(t.name));
-        // Hide MCP tools we already call automatically. Small models otherwise
-        // try to invoke them with the wrong arguments (most commonly
-        // memory_capture_turn — "Required, Required" comes from missing
-        // sessionKey + messages). These tools are still callable; the CLI just
-        // doesn't tell the LLM about them since the auto-pipeline owns them.
-        const HIDDEN_FROM_LLM = new Set([
-            'memory_capture_turn', // called automatically post-turn
-            'memory_mark_cited', // called automatically with real citation IDs
-            'memory_resolve_session', // called automatically at bootstrap
-            'memory_register_skill_hints', // boot-time, not turn-level
-            'memory_hook_register', // managed via /hooks
-            'memory_hook_status',
-        ]);
-        const visibleMcpTools = mcpTools.filter((t) => !HIDDEN_FROM_LLM.has(t.name));
+        // Multi-MCP parity: expose every connected third-party MCP tool and the
+        // model-safe BrainRouter MCP tools in one turn, using the pool's
+        // `mcp__<serverId>__<tool>` namespaces. BrainRouter's auto-pipeline/admin
+        // tools stay hidden because the CLI owns those flows.
+        const visibleMcpTools = mcpTools.filter((t) => this.isModelVisibleMcpTool(t));
         const allTools = [...filteredLocalTools, ...visibleMcpTools];
         callbacks.onStatusUpdate(`Loaded ${filteredLocalTools.length} local tools and ${mcpTools.length} MCP tools.`);
         // Auto-compact: if the chat history has grown past the configured token
@@ -612,6 +699,9 @@ export class Agent {
         // signatures so we can interrupt the loop with corrective feedback.
         const recentToolSignatures = [];
         const REPEAT_GUARD_LIMIT = 3;
+        const spawnedChildIdsThisTurn = new Set();
+        const waitedChildIdsThisTurn = new Set();
+        let spawnWaitGuardInjected = false;
         while (loopCount < maxLoops) {
             loopCount++;
             callbacks.onStatusUpdate(`Thinking (turn ${loopCount})...`);
@@ -639,6 +729,21 @@ export class Agent {
             this.chatHistory.push(assistantMsg);
             this.recordTranscript(assistantMsg);
             if (!response.toolCalls || response.toolCalls.length === 0) {
+                const unobservedChildIds = [...spawnedChildIdsThisTurn].filter((id) => !waitedChildIdsThisTurn.has(id));
+                if (unobservedChildIds.length > 0 && !spawnWaitGuardInjected) {
+                    spawnWaitGuardInjected = true;
+                    const waitTool = unobservedChildIds.length === 1 ? 'wait_agent' : 'wait_agents';
+                    const correction = [
+                        `You spawned ${unobservedChildIds.length} child agent${unobservedChildIds.length === 1 ? '' : 's'} in this turn but have not waited for their outputs yet.`,
+                        `Call \`${waitTool}\` now for: ${unobservedChildIds.join(', ')}.`,
+                        'Do not tell the user you are waiting in prose; use the tool call, then synthesize the returned child output.',
+                    ].join(' ');
+                    const guardMsg = { role: 'user', content: correction };
+                    this.chatHistory.push(guardMsg);
+                    this.recordTranscript(guardMsg);
+                    callbacks.onStatusUpdate(`Waiting required for ${unobservedChildIds.length} child agent${unobservedChildIds.length === 1 ? '' : 's'}...`);
+                    continue;
+                }
                 finalAnswer = response.content;
                 exitedCleanly = true;
                 break;
@@ -758,6 +863,8 @@ export class Agent {
                             parentTraceId: turnSpan.traceId,
                             parentSpanId: turnSpan.spanId,
                             parentAgentId: this.agentId,
+                            parentTier: this.tier,
+                            depth: this.agentDepth,
                             mcpClient: this.mcpClient,
                             llmConfig: this.llmConfig,
                             launchCwd: this.launchCwd,
@@ -772,6 +879,7 @@ export class Agent {
                             },
                         });
                         summary = getToolSummary(name, args, resultText);
+                        trackChildObservation(name, args, resultText, spawnedChildIdsThisTurn, waitedChildIdsThisTurn);
                     }
                     else if (isLocal) {
                         resultText = await this.executeLocalTool(name, args);
@@ -1104,7 +1212,7 @@ export class Agent {
                 try {
                     const res = await fetch(url, {
                         headers: {
-                            'User-Agent': 'Mozilla/5.0 (compatible; BrainRouterCLI/0.3.5)'
+                            'User-Agent': 'Mozilla/5.0 (compatible; BrainRouterCLI/0.3.7)'
                         }
                     });
                     if (!res.ok) {
@@ -1712,7 +1820,7 @@ async function runWebSearch(query, maxResults) {
     }
     try {
         const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1&skip_disambig=1`;
-        const res = await fetch(url, { headers: { 'User-Agent': 'BrainRouterCLI/0.3.5' } });
+        const res = await fetch(url, { headers: { 'User-Agent': 'BrainRouterCLI/0.3.7' } });
         if (!res.ok) {
             return `web_search failed: DuckDuckGo returned ${res.status} ${res.statusText}.`;
         }
@@ -2267,7 +2375,15 @@ export function buildChatCompletionPayload(config, messages, tools, options = {}
     return body;
 }
 export async function callOpenAI(config, messages, tools, options = {}) {
-    const endpoint = config.endpoint || 'https://api.openai.com/v1';
+    // Normalize the endpoint to a base URL (everything UP TO `/chat/completions`
+    // exclusive). Earlier callers stored the full chat-completions URL in
+    // `config.endpoint` (e.g. "https://api.openai.com/v1/chat/completions")
+    // because the in-terminal wizard's provider catalog wrote the full path.
+    // We then re-append `/chat/completions` below, producing a duplicate
+    // `/chat/completions/chat/completions` and a 404. Strip the suffix
+    // defensively so both shapes (full URL or base URL) work.
+    const rawEndpoint = config.endpoint || 'https://api.openai.com/v1';
+    const endpoint = rawEndpoint.replace(/\/+$/, '').replace(/\/chat\/completions$/, '');
     let apiKey = config.apiKey || process.env.OPENAI_API_KEY || '';
     const isLocal = endpoint.includes('localhost') || endpoint.includes('127.0.0.1');
     if (!apiKey && !isLocal) {

package/dist/cli/banner.d.ts

@@ -39,6 +39,12 @@ export interface BannerInputs {
     /** Version override (test fixture). */
     version?: string;
 }
+export interface DisplayedMcpState {
+    profile: string;
+    transport: string;
+    online: boolean;
+    identity: 'brainrouter' | 'third-party' | 'unknown';
+}
 /**
  * Pure renderer — returns the box as a single newline-joined string with
  * ANSI sequences from `theme`. Caller appends the trailing newline.
@@ -57,4 +63,18 @@ export declare function buildBannerInputs(config: Config, agent: {
 }, mcpClient: {
     isConnected: () => boolean;
     getIdentity?: () => 'brainrouter' | 'third-party' | 'unknown';
+    getStatus?: (serverId: string) => {
+        status: string;
+        identity: 'brainrouter' | 'third-party' | 'unknown';
+    } | undefined;
+    getActiveBrainrouterServerId?: () => string | undefined;
 }): BannerInputs;
+export declare function resolveDisplayedMcpState(config: Config, mcpClient: {
+    isConnected: () => boolean;
+    getIdentity?: () => 'brainrouter' | 'third-party' | 'unknown';
+    getStatus?: (serverId: string) => {
+        status: string;
+        identity: 'brainrouter' | 'third-party' | 'unknown';
+    } | undefined;
+    getActiveBrainrouterServerId?: () => string | undefined;
+}): DisplayedMcpState;

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.5 ──────────────────────────────╮
+ *   ╭─ 🧠 BrainRouter CLI 0.3.7 ──────────────────────────────╮
  *   │ workspace  BrainRouter  ·  c5b8c12d                     │
  *   │ mcp        local-http  ·  http  ·  online               │
  *   │ workflow   cli-shell-redesign  (in-progress)            │
@@ -26,10 +26,19 @@ 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.6';
+const VERSION = '0.3.7';
 const TITLE = '🧠 BrainRouter CLI';
-const MIN_WIDTH = 56;
+// Width floor for the BOXED banner. Below this we fall through to the
+// `renderPlainBanner` plaintext format. Was 56 — that caused the box to
+// overflow on terminals narrower than 58 cols (each row wrapped to
+// multiple terminal rows with broken border alignment). 38 fits a
+// 40-col terminal (the smallest realistic phone / split-pane width).
+const MIN_BOX_WIDTH = 38;
 const MAX_WIDTH = 100;
+// Below this width we skip the box entirely and render the rows as
+// "label: value" lines. The boxed format with horizontal borders +
+// title is meaningless when each border row wraps.
+const PLAIN_TEXT_THRESHOLD = 38;
 function shortHash(absPath) {
     return crypto.createHash('sha1').update(absPath).digest('hex').slice(0, 8);
 }
@@ -123,8 +132,14 @@ export function renderBanner(inputs, theme) {
     // Inner width is the widest "label + 2 spaces + value", clamped.
     const naturalInner = rows.reduce((w, r) => Math.max(w, labelWidth + 2 + r.value.length), titleText.length + 4);
     const targetCols = process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : MAX_WIDTH;
+    // Below the plaintext threshold the boxed layout is hostile (each
+    // border row wraps and looks chaotic). Fall back to a label:value
+    // text dump that the terminal can wrap naturally.
+    if (targetCols < PLAIN_TEXT_THRESHOLD) {
+        return renderPlainBanner(titleText, rows, theme);
+    }
     // Reserve 2 columns for the side borders.
-    const innerWidth = Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, Math.min(naturalInner, targetCols - 2)));
+    const innerWidth = Math.max(MIN_BOX_WIDTH, Math.min(MAX_WIDTH, Math.min(naturalInner, targetCols - 2)));
     const top = (() => {
         // ╭─ <title> ──╮  — title sits inline at the top border.
         const titlePiece = ` ${titleText} `;
@@ -140,6 +155,17 @@ export function renderBanner(inputs, theme) {
     const bottom = theme.primary(BOX.bottomLeft + BOX.horizontal.repeat(innerWidth) + BOX.bottomRight);
     return [top, ...bodyLines, bottom].join('\n');
 }
+/**
+ * Compact label:value text banner — used on terminals narrower than
+ * PLAIN_TEXT_THRESHOLD cols where the boxed layout's border rows
+ * would wrap and look broken. Same information, no chrome.
+ */
+function renderPlainBanner(titleText, rows, theme) {
+    const labelWidth = rows.reduce((w, r) => Math.max(w, r.label.length), 0);
+    const headerLine = theme.primary(titleText);
+    const bodyLines = rows.map((row) => theme.muted(padRight(row.label, labelWidth) + '  ') + theme.plain(row.value));
+    return [headerLine, ...bodyLines].join('\n');
+}
 /**
  * Convenience: assemble the inputs from live agent + config + workspace
  * state. Pure read; no side effects. Anything that throws while reading the
@@ -147,12 +173,7 @@ export function renderBanner(inputs, theme) {
  * workspace doesn't crash the banner.
  */
 export function buildBannerInputs(config, agent, mcpClient) {
-    const profile = config.activeServer;
-    const server = config.servers[profile];
-    const transport = server?.type ?? 'unknown';
-    // 10c: identity comes from the live wrapper when present; fall back to
-    // the config field for callers that pass a thin stub.
-    const mcpIdentity = mcpClient.getIdentity ? mcpClient.getIdentity() : (server?.identity ?? 'unknown');
+    const displayedMcp = resolveDisplayedMcpState(config, mcpClient);
     let workflow;
     let lastUsedWorkflow;
     try {
@@ -186,10 +207,10 @@ export function buildBannerInputs(config, agent, mcpClient) {
     catch { /* ignore — no goal yet */ }
     return {
         workspaceRoot: agent.workspaceRoot,
-        mcpProfile: profile,
-        mcpTransport: transport,
-        mcpOnline: mcpClient.isConnected(),
-        mcpIdentity,
+        mcpProfile: displayedMcp.profile,
+        mcpTransport: displayedMcp.transport,
+        mcpOnline: displayedMcp.online,
+        mcpIdentity: displayedMcp.identity,
         sessionKey: agent.sessionKey,
         model: agent.getModel(),
         workflow,
@@ -197,3 +218,15 @@ export function buildBannerInputs(config, agent, mcpClient) {
         goal,
     };
 }
+export function resolveDisplayedMcpState(config, mcpClient) {
+    const liveBrain = mcpClient.getActiveBrainrouterServerId?.();
+    const profile = liveBrain || config.activeServer;
+    const server = config.servers[profile];
+    const status = profile ? mcpClient.getStatus?.(profile) : undefined;
+    return {
+        profile,
+        transport: server?.type ?? 'unknown',
+        online: status ? status.status === 'connected' : mcpClient.isConnected(),
+        identity: status?.identity ?? server?.identity ?? mcpClient.getIdentity?.() ?? 'unknown',
+    };
+}