@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/index.js

@@ -1,171 +1,106 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import url from 'node:url';
-import { Command } from 'commander';
-import inquirer from 'inquirer';
-import chalk from 'chalk';
-import { loadConfig, saveConfig } from './config/config.js';
-import { McpClientWrapper } from './runtime/mcpClient.js';
-import { Agent } from './agent/agent.js';
-import { startREPL } from './cli/repl.js';
-import { applyWorkspaceRoot, findWorkspaceRoot } from './config/workspace.js';
 /**
- * Load `.env` files into the CLI's `process.env`.
- *
- * The CLI and the MCP server have separate concerns and now ship separate
- * config files:
- *
- *   - `brainrouter-cli/.env`  — CLI-only knobs (chat LLM, tool loop,
- *                                sandbox, web search, trace log).
- *   - `brainrouter/.env`      — MCP-only knobs (extraction LLM, embeddings,
- *                                reranker, memory engine, server auth).
+ * Filter out Node.js platform warnings that the user has no way to act on
+ * and that scroll real CLI banner content off-screen on short terminals.
  *
- * Loading order:
- *   1) `brainrouter-cli/.env` (PRIMARY for CLI process).
- *   2) `brainrouter/.env`     (FALLBACK — only for the LLM credentials, so
- *                              a user who set up only the MCP config still
- *                              gets a working CLI agent and vice versa).
+ *   - `ExperimentalWarning: SQLite is an experimental feature` — emitted by
+ *     `node:sqlite`. The CLI itself no longer imports sqlite, but the
+ *     stdio MCP child process does, and its warnings surface on the parent's
+ *     stderr. Stable in Node 22+ in practice; the warning is correct but
+ *     uninformative.
+ *   - `DeprecationWarning: ... dotenv ...` — dotenv@16 prints a teaser for
+ *     its hosted product on every load on newer Node releases.
  *
- * Shell env (anything already in `process.env`) wins over both — explicit
- * env > .env file, as is conventional.
+ * BrainRouter's own warnings flow through unchanged. `NODE_NO_WARNINGS=1`
+ * would silence those too, so we intercept selectively instead.
  *
- * The MCP child uses `import "dotenv/config"` which resolves relative to
- * `process.cwd()`. The CLI sets the spawned child's cwd to the MCP package
- * directory (see runtime/mcpClient.ts), so `brainrouter/.env` is loaded by
- * the child directly — the CLI does NOT need to pre-load it for the MCP's
- * sake.
+ * Two interception points: (1) remove Node's built-in `warning` listener
+ * and add our own filtered one — this catches warnings emitted from
+ * subprocesses or transitive imports during ESM resolution; (2) replace
+ * `process.emitWarning` so future direct callers also get the filter.
+ * Both are needed because ESM hoists imports above any code in this file,
+ * so an emitWarning override alone misses import-time warnings.
  */
+function isSuppressibleWarning(message, type) {
+    const looksExperimental = type === 'ExperimentalWarning' ||
+        /experimental feature|SQLite is an experimental/i.test(message);
+    const looksDotenvNoise = /dotenv@\d|dotenvx|dotenv\.org/i.test(message);
+    return looksExperimental || looksDotenvNoise;
+}
+// Detach Node's default warning printer and replace with a filtered one.
+// process.listeners returns each Function attached; the default one is a
+// single internal listener that does the stderr printing.
+for (const listener of process.listeners('warning')) {
+    process.removeListener('warning', listener);
+}
+process.on('warning', (warning) => {
+    if (isSuppressibleWarning(warning?.message ?? '', warning?.name ?? ''))
+        return;
+    // Mirror Node's default formatting for everything else so users see the
+    // familiar "(node:PID) <Name>: <message>" shape.
+    process.stderr.write(`(node:${process.pid}) ${warning?.name ?? 'Warning'}: ${warning?.message ?? warning}\n`);
+});
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+    const message = typeof warning === 'string' ? warning : warning?.message ?? '';
+    const type = typeof rest[0] === 'string' ? rest[0]
+        : (rest[0] && typeof rest[0] === 'object' && 'type' in rest[0]) ? rest[0].type
+            : (warning instanceof Error ? warning.name : '');
+    if (isSuppressibleWarning(message, type))
+        return;
+    return originalEmitWarning(warning, ...rest);
+});
 /**
- * Vars the CLI process consumes from a sibling `brainrouter/.env` fallback.
- *
- * LLM credentials are deliberately EXCLUDED — `~/.config/brainrouter/config.json`
- * is the canonical source for chat-LLM creds, endpoint, and model (set via
- * `brainrouter login` or `brainrouter config`). Pulling them from `.env` in
- * parallel created a silent precedence bug: env would shadow `config.json`
- * because `loadBrainrouterEnv()` runs at module-load time before
- * `loadConfig()`, and downstream callers like `mcpClient.connect()` check
- * `mergedEnv.BRAINROUTER_LLM_ENDPOINT` before falling back to `llmConfig`.
- *
- * The only var we still allow through the fallback is `BRAINROUTER_API_KEY`
- * — that's MCP-server auth (not LLM), and stdio mode propagates it from the
- * CLI's process.env into the spawned child. If your `config.json` server
- * profile already carries the API key in its `env` block, you don't need
- * this fallback either, and it can go away in a follow-up cleanup.
+ * Crash diagnostics — surface ANY exit reason so the user (or we) can
+ * see WHY the process died if the REPL ever silently quits. The
+ * symptom the user reported was "REPL prints banner, then bash prompt"
+ * with no error. If that happens again under any future regression,
+ * one of these handlers will catch it and print the cause.
  *
- * Anything outside this set is a pure MCP-server knob (embedding endpoint,
- * JWT secret, extraction sweep config, prewarming, graph timeouts, admin
- * creds) that just pollutes the CLI's environment with no effect — the MCP
- * child loads `brainrouter/.env` directly via its own `dotenv/config`.
+ * `BRAINROUTER_DEBUG_EXIT=1` (default off) enables verbose exit tracing
+ * including the beforeExit event so we can see whether the event loop
+ * drained (= stdin refcount issue) vs explicit process.exit (= bug).
  */
-const CLI_FALLBACK_ALLOWLIST = new Set([
-    'BRAINROUTER_API_KEY',
-]);
-function loadEnvFile(file, allowlist) {
-    try {
-        const raw = fs.readFileSync(file, 'utf8');
-        let count = 0;
-        for (const line of raw.split('\n')) {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith('#'))
-                continue;
-            const eq = trimmed.indexOf('=');
-            if (eq <= 0)
-                continue;
-            const key = trimmed.slice(0, eq).trim();
-            let value = trimmed.slice(eq + 1).trim();
-            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-                value = value.slice(1, -1);
-            }
-            // Allowlist gate: when loading the MCP fallback file, only adopt vars
-            // the CLI actually reads. Primary CLI .env loads pass no allowlist and
-            // accept everything (it's the CLI's own config).
-            if (allowlist && !allowlist.has(key))
-                continue;
-            if (key && !(key in process.env)) {
-                process.env[key] = value;
-                count++;
-            }
-        }
-        return count;
-    }
-    catch {
-        return 0;
-    }
-}
-function loadBrainrouterEnv() {
-    const here = path.dirname(url.fileURLToPath(import.meta.url));
-    let count = 0;
-    let primary;
-    let fallback;
-    // PRIMARY: brainrouter-cli/.env (this package's own config).
-    // dist/index.js → ../.. = brainrouter-cli/, so .env sits next to package.json.
-    const cliCandidates = [
-        path.resolve(here, '..', '..', '.env'), // monorepo: brainrouter-cli/.env
-        path.resolve(here, '..', '..', '..', 'brainrouter-cli', '.env'), // installed/nested
-        path.resolve(process.cwd(), 'brainrouter-cli', '.env'), // running from repo root
-    ];
-    for (const file of cliCandidates) {
-        if (fs.existsSync(file)) {
-            primary = file;
-            count += loadEnvFile(file);
-            break;
-        }
-    }
-    // FALLBACK: brainrouter/.env (MCP-side config). Only used to backstop the
-    // LLM credentials so a partial setup still works. The MCP child loads
-    // brainrouter/.env on its own anyway via cwd hint, so we don't need to
-    // import its server-only knobs (embedding endpoint, JWT secret, sweep
-    // intervals, prewarming) — those just clutter the CLI's process.env. The
-    // allowlist limits the fallback to vars the CLI actually reads.
-    //
-    // Only record the fallback in the result when it actually contributed at
-    // least one new var. If the primary file already set all the LLM creds,
-    // mentioning the fallback path in the startup banner is noise — the user
-    // already has the CLI fully configured locally and doesn't need to know
-    // a sibling .env was read but ignored.
-    const mcpCandidates = [
-        path.resolve(here, '..', '..', '..', 'brainrouter', '.env'),
-        path.resolve(process.cwd(), 'brainrouter', '.env'),
-    ];
-    for (const file of mcpCandidates) {
-        if (fs.existsSync(file)) {
-            const added = loadEnvFile(file, CLI_FALLBACK_ALLOWLIST);
-            if (added > 0) {
-                fallback = file;
-                count += added;
-            }
-            break;
-        }
-    }
-    return { primary, fallback, count };
-}
-const envLoadResult = loadBrainrouterEnv();
-if (envLoadResult.primary || envLoadResult.fallback) {
-    // Something contributed at least one var — show what loaded so the user can
-    // trace where runtime knobs (sandbox, timeouts, trace log, web search) are
-    // coming from. LLM creds intentionally do NOT flow through this path; they
-    // live in ~/.config/brainrouter/config.json.
-    const sources = [];
-    if (envLoadResult.primary)
-        sources.push(envLoadResult.primary);
-    if (envLoadResult.fallback)
-        sources.push(`${envLoadResult.fallback} (fallback)`);
-    const tag = envLoadResult.count > 0
-        ? chalk.gray(` (${envLoadResult.count} new var${envLoadResult.count === 1 ? '' : 's'})`)
-        : chalk.gray(' (all keys already set in shell)');
-    console.error(chalk.gray(`env: loaded ${sources.join(', ')}`) + tag);
+process.on('uncaughtException', (err) => {
+    process.stderr.write(`\n[brainrouter] Uncaught exception killed the process:\n${err?.stack ?? err}\n`);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    process.stderr.write(`\n[brainrouter] Unhandled promise rejection killed the process:\n${reason?.stack ?? reason}\n`);
+    process.exit(1);
+});
+if (process.env.BRAINROUTER_DEBUG_EXIT === '1') {
+    process.on('beforeExit', (code) => {
+        process.stderr.write(`[brainrouter:debug] beforeExit code=${code} (event loop drained — likely Ink stdin.unref leak)\n`);
+    });
+    process.on('exit', (code) => {
+        process.stderr.write(`[brainrouter:debug] exit code=${code}\n`);
+    });
 }
-// No banner when nothing loaded — that's the normal case for users who
-// configured the CLI via `brainrouter login` / `brainrouter config`. The old
-// "set BRAINROUTER_LLM_API_KEY in your shell" hint contradicted the
-// config.json-is-canonical design and confused users who already had a
-// fully populated config.
+import fs from 'node:fs';
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { loadConfig, loadOrInitConfig, saveConfig, getConfigPath } from './config/config.js';
+import { McpClientWrapper } from './runtime/mcpClient.js';
+import { McpClientPool, selectMcpServerIds } from './runtime/mcpPool.js';
+import { Agent } from './agent/agent.js';
+import { runChat } from './cli/ink/runChat.js';
+import { applyWorkspaceRoot, findWorkspaceRoot } from './config/workspace.js';
+import { runWizard, isOnboarded } from './cli/ink/runWizard.js';
+// The CLI deliberately does NOT load any `.env` file. Source of truth for
+// runtime config is `~/.config/brainrouter/config.json` (LLM creds, MCP
+// server profiles, theme, etc.), set interactively via the wizard / `/login`
+// / `/config`. The MCP server is a separate concern and loads its own
+// `server.env` from its own working directory — that's the server's
+// business, not the CLI's. Shell env (real `process.env`) still flows
+// through normally for everything that reads it (e.g. `OPENAI_API_KEY`
+// fallback inside `callOpenAI`).
 const program = new Command();
 program
     .name('brainrouter')
     .description('BrainRouter CLI — Premium interactive terminal-based agent client.')
-    .version('0.3.5');
+    .version('0.3.7');
 // Chat Command (default)
 program
     .command('chat', { isDefault: true })
@@ -174,29 +109,81 @@ program
     .option('-m, --model <name>', 'LLM model override')
     .option('-w, --workspace <path>', 'Workspace root for files, commands, memory session, and MCP --root')
     .option('--strict-mcp', 'Exit if the MCP server is unreachable (default: continue in offline mode with local tools only)')
+    .option('--quiet', 'Suppress recall tables, briefing dumps, and tool-completion previews (model prose only). Toggle in-session with /quiet.')
     .action(async (options) => {
     if (options.workspace) {
         process.env.BRAINROUTER_WORKSPACE = options.workspace;
     }
+    if (options.quiet) {
+        // Quiet mode is durable in preferences, but `--quiet` should turn it
+        // on for THIS session without permanently flipping the user's saved
+        // setting. Set a process env that the REPL preference-merger checks.
+        process.env.BRAINROUTER_QUIET = '1';
+    }
     const workspace = findWorkspaceRoot();
     applyWorkspaceRoot(workspace.workspaceRoot);
-    console.log(chalk.gray(`Workspace: ${workspace.workspaceRoot} (${workspace.reason})`));
+    // Workspace path + detection reason intentionally NOT printed here — the
+    // boxed startup banner shows the workspace row, and `/workspace` exposes
+    // the launch CWD + detection reason on demand. Keeping a duplicate
+    // stale-chrome line above the banner undermines the banner-first design.
+    // 0.3.7 — first-run auto-trigger. When no config exists OR the
+    // onboarded marker is missing, drop the user straight into the
+    // wizard before constructing the Agent / MCP client. This replaces
+    // the pre-0.3.7 "Error: No BrainRouter config found ... run
+    // `brainrouter login`" exit-with-error path. The wizard owns its
+    // own readline for the wizard's lifetime; when it returns we
+    // continue into the REPL with the freshly-saved config.
+    if (!fs.existsSync(getConfigPath()) || !isOnboarded()) {
+        try {
+            const wizardResult = await runWizard({
+                workspaceRoot: workspace.workspaceRoot,
+            });
+            if (wizardResult.state.aborted) {
+                console.error(chalk.gray('Wizard aborted before saving — exiting. Run `brainrouter` again any time to retry.'));
+                process.exit(0);
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(`Wizard failed: ${err?.message ?? err}`));
+            process.exit(1);
+        }
+    }
     const config = loadConfig();
-    const profileName = options.profile || config.activeServer;
-    const configuredServer = config.servers[profileName];
-    if (!configuredServer) {
-        console.error(chalk.red(`Error: Profile "${profileName}" not found in config.`));
+    // 0.3.7 — multi-MCP support. Third-party MCPs are additive and all
+    // connect concurrently. BrainRouter MCPs are different: users may store
+    // several BrainRouter profiles (local/staging/remote/self-hosted), but
+    // only one brain should be active at a time. `activeServer` selects that
+    // BrainRouter profile when it points at one; otherwise we use the first
+    // configured BrainRouter profile. `--profile <name>` still scopes the run
+    // to exactly one server for explicit single-server mode.
+    const requestedProfile = options.profile;
+    const allServerIds = Object.keys(config.servers);
+    if (allServerIds.length === 0) {
+        console.error(chalk.red('Error: No MCP server profiles in config.'));
+        console.error(chalk.gray('Run `/login` inside the REPL or `brainrouter login` to add a profile.'));
         process.exit(1);
     }
-    const serverConfig = { ...configuredServer };
-    if (serverConfig.type === 'stdio') {
-        const args = serverConfig.args ?? [];
-        const rootIndex = args.indexOf('--root');
-        serverConfig.args = rootIndex >= 0
-            ? [...args.slice(0, rootIndex + 1), workspace.workspaceRoot, ...args.slice(rootIndex + 2)]
-            : [...args, '--root', workspace.workspaceRoot];
+    if (requestedProfile && !config.servers[requestedProfile]) {
+        console.error(chalk.red(`Error: Profile "${requestedProfile}" not found in config.`));
+        console.error(chalk.gray(`Available profiles: ${allServerIds.join(', ')}.`));
+        process.exit(1);
+    }
+    const targetIds = selectMcpServerIds(config.servers, config.activeServer, requestedProfile);
+    // Pre-process each target's serverConfig to thread workspaceRoot
+    // into the stdio `--root` arg shape the MCP server expects.
+    const targetServers = {};
+    for (const id of targetIds) {
+        const cloned = { ...config.servers[id] };
+        if (cloned.type === 'stdio') {
+            const args = cloned.args ?? [];
+            const rootIndex = args.indexOf('--root');
+            cloned.args = rootIndex >= 0
+                ? [...args.slice(0, rootIndex + 1), workspace.workspaceRoot, ...args.slice(rootIndex + 2)]
+                : [...args, '--root', workspace.workspaceRoot];
+        }
+        targetServers[id] = cloned;
+        config.servers[id] = cloned;
     }
-    config.servers[profileName] = serverConfig;
     const llm = config.llm || {
         provider: 'openai',
         model: 'gpt-4o-mini',
@@ -205,34 +192,34 @@ program
     if (options.model) {
         llm.model = options.model;
     }
-    const mcpClient = new McpClientWrapper();
-    console.log(chalk.gray(`Connecting to MCP server profile "${profileName}"...`));
-    try {
-        await mcpClient.connect(serverConfig, llm);
-        console.log(chalk.green('Successfully connected to BrainRouter MCP Server!'));
-    }
-    catch (err) {
-        // Degraded "offline mode": the MCP server is the cognitive memory layer
-        // (recall, skills, capture, citations) — losing it is painful but not
-        // fatal. Local tools (read_file, write_file, list_dir, grep_search,
-        // run_command, spawn_agent) still work, and the agent's runTurn already
-        // try/catches every MCP call. Keep the REPL up so the user can edit
-        // code, drive shell commands, and recover when the server comes back.
-        // Pass --strict-mcp to flip back to hard-fail (useful in CI).
-        console.error(chalk.red(`Failed to connect to MCP server: ${err.message}`));
+    // Connect everyone concurrently — offline servers don't block.
+    // "Connecting..." status lines intentionally dropped (see prior
+    // comment); the banner's per-server row is the success signal.
+    const mcpClient = new McpClientPool();
+    const statuses = await mcpClient.connectAll(targetServers, llm, { timeoutMs: 5_000 });
+    const failures = statuses.filter((s) => s.status === 'failed');
+    if (failures.length === statuses.length) {
+        // Every server failed — equivalent to the pre-0.3.7 "MCP
+        // unreachable" path; same --strict-mcp semantics apply.
+        const summary = failures.map((s) => `${s.serverId}: ${s.error ?? 'unknown error'}`).join('\n  ');
+        console.error(chalk.red(`Failed to connect to any MCP server:\n  ${summary}`));
         if (options.strictMcp) {
             console.error(chalk.gray('--strict-mcp set; exiting.'));
             process.exit(1);
         }
-        console.warn(chalk.yellow('⚠️  Continuing in OFFLINE MODE — memory recall, skills, and capture are disabled.\n' +
-            '    Local tools (file edits, shell, web fetch, spawn_agent) remain available.\n' +
-            '    Start the MCP server and restart the CLI to restore full functionality.\n'));
+        // Falls through to offline-mode REPL — banner shows the warning.
+    }
+    else if (failures.length > 0) {
+        // Partial failure — surface the failing server names without
+        // exiting; user can /mcp reconnect <id> later.
+        const failed = failures.map((s) => s.serverId).join(', ');
+        console.error(chalk.yellow(`⚠ ${failures.length} of ${statuses.length} MCP servers offline: ${failed}. Other servers connected; use /mcp to inspect.`));
     }
     const agent = new Agent(mcpClient, llm, {
         workspaceRoot: workspace.workspaceRoot,
         launchCwd: workspace.launchCwd,
     });
-    startREPL(agent, mcpClient, config, workspace);
+    await runChat({ agent, mcpClient, config, workspace });
 });
 // One-shot non-interactive run — pipe-friendly for scripting/CI.
 //   brainrouter run "summarize the changes in src/"
@@ -284,28 +271,41 @@ program
     const workspace = findWorkspaceRoot();
     applyWorkspaceRoot(workspace.workspaceRoot);
     const config = loadConfig();
-    const profileName = options.profile || config.activeServer;
-    const serverConfig = { ...config.servers[profileName] };
-    if (!serverConfig) {
-        console.error(`Error: Profile "${profileName}" not found.`);
+    // Multi-MCP: like `chat`, connect third-party servers concurrently but
+    // only one BrainRouter MCP profile at a time. `--profile <name>` scopes
+    // to exactly one.
+    const requestedProfile = options.profile;
+    const allServerIds = Object.keys(config.servers);
+    if (allServerIds.length === 0) {
+        console.error('Error: No MCP server profiles in config.');
         process.exit(1);
     }
-    if (serverConfig.type === 'stdio') {
-        const args = serverConfig.args ?? [];
-        const rootIndex = args.indexOf('--root');
-        serverConfig.args = rootIndex >= 0
-            ? [...args.slice(0, rootIndex + 1), workspace.workspaceRoot, ...args.slice(rootIndex + 2)]
-            : [...args, '--root', workspace.workspaceRoot];
+    if (requestedProfile && !config.servers[requestedProfile]) {
+        console.error(`Error: Profile "${requestedProfile}" not found.`);
+        process.exit(1);
+    }
+    const targetIds = selectMcpServerIds(config.servers, config.activeServer, requestedProfile);
+    const targetServers = {};
+    for (const id of targetIds) {
+        const cloned = { ...config.servers[id] };
+        if (cloned.type === 'stdio') {
+            const args = cloned.args ?? [];
+            const rootIndex = args.indexOf('--root');
+            cloned.args = rootIndex >= 0
+                ? [...args.slice(0, rootIndex + 1), workspace.workspaceRoot, ...args.slice(rootIndex + 2)]
+                : [...args, '--root', workspace.workspaceRoot];
+        }
+        targetServers[id] = cloned;
     }
     const llm = config.llm ?? { provider: 'openai', model: 'gpt-4o-mini', apiKey: '' };
     if (options.model)
         llm.model = options.model;
-    const mcpClient = new McpClientWrapper();
-    try {
-        await mcpClient.connect(serverConfig, llm);
-    }
-    catch (err) {
-        console.error(`MCP connect failed: ${err.message}`);
+    const mcpClient = new McpClientPool();
+    const statuses = await mcpClient.connectAll(targetServers, llm, { timeoutMs: 5_000 });
+    const allFailed = statuses.length > 0 && statuses.every((s) => s.status === 'failed');
+    if (allFailed) {
+        const summary = statuses.map((s) => `${s.serverId}: ${s.error ?? 'unknown'}`).join('; ');
+        console.error(`MCP connect failed (all servers): ${summary}`);
         if (options.strictMcp)
             process.exit(1);
         // Offline mode for one-shot: same rationale as the chat command — local
@@ -314,6 +314,12 @@ program
         // summarize" while the MCP server is down. CI can pass --strict-mcp.
         console.error('Continuing in offline mode (no memory recall / skills). Pass --strict-mcp to exit instead.');
     }
+    else {
+        const failed = statuses.filter((s) => s.status === 'failed');
+        if (failed.length > 0) {
+            process.stderr.write(`[mcp] ${failed.length} of ${statuses.length} servers offline: ${failed.map((f) => f.serverId).join(', ')}\n`);
+        }
+    }
     const agent = new Agent(mcpClient, llm, {
         workspaceRoot: workspace.workspaceRoot,
         launchCwd: workspace.launchCwd,
@@ -395,10 +401,11 @@ program
             type: 'http',
             url: answers.url,
             apiKey: answers.apiKey || undefined
-        });
+        }, undefined, answers.profileName);
         await mcpClient.close();
-        // Save to config
-        const config = loadConfig();
+        // Save to config — `loadOrInitConfig` lets first-run users build a
+        // fresh config.json instead of hitting the strict no-config error.
+        const config = loadOrInitConfig();
         config.servers[answers.profileName] = {
             type: 'http',
             url: answers.url,
@@ -419,7 +426,9 @@ program
     .command('config')
     .description('Interactively configure your LLM provider and MCP servers')
     .action(async () => {
-    const config = loadConfig();
+    // `loadOrInitConfig` because this command IS the first-run setup
+    // wizard — it must work even when no config.json exists yet.
+    const config = loadOrInitConfig();
     const menu = await inquirer.prompt([
         {
             type: 'list',

package/dist/memory/briefing.d.ts

@@ -1,4 +1,4 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 export interface BriefingInputs {
     mcpClient: McpClientWrapper;
     mcpTools: Array<{
@@ -10,6 +10,16 @@ export interface BriefingInputs {
     activeSkill?: string;
     /** Cap on injected briefing content per source — guards against runaway payloads eating the context window. */
     maxCharsPerSource?: number;
+    /**
+     * Set by the caller when a `goal-anchor` system message is already
+     * carrying the current objective. The briefing skips `memory_task_state`
+     * in that case to avoid double-injecting the "what we're doing right
+     * now" context — the goal-anchor is the authoritative owner. When
+     * there is no active goal (pre-goal exploration, after `/goal pause`,
+     * silent child agents) the task-state surface still fires so handover
+     * notes and prior blockers stay visible. Part of 0.3.6 item 9d.
+     */
+    hasActiveGoal?: boolean;
 }
 export interface RecalledRecord {
     recordId: string;

package/dist/memory/briefing.js

@@ -17,7 +17,7 @@ export async function buildMemoryBriefing(inputs) {
     if (toolNames.has('memory_working_context')) {
         tasks.push(callSafe('memory_working_context', { sessionKey, workspacePath: workspaceRoot }, mcpClient, maxChars));
     }
-    if (toolNames.has('memory_task_state')) {
+    if (toolNames.has('memory_task_state') && !inputs.hasActiveGoal) {
         tasks.push(callSafe('memory_task_state', { query }, mcpClient, maxChars));
     }
     const results = await Promise.all(tasks);
@@ -28,6 +28,16 @@ export async function buildMemoryBriefing(inputs) {
         if (!r.text)
             continue;
         sourcesQueried.push(r.source);
+        if (r.source === 'memory_working_context') {
+            const workingSection = renderWorkingMemorySection(r.text);
+            if (workingSection) {
+                sections.push(workingSection);
+                continue;
+            }
+            // Fall through to the opaque-dump branch when the payload didn't
+            // match the expected shape — that path runs redactText and keeps
+            // the secrets test honest.
+        }
         if (r.records && r.records.length > 0) {
             // Render structured cards instead of dumping the raw JSON. The previous
             // form emitted ~2-4KB of `recallExplanation`/`sparkedNodes`/etc. per
@@ -147,6 +157,64 @@ function prettyLabel(toolName) {
         default: return toolName;
     }
 }
+/**
+ * 0.3.6 item 2c — structurally surface working-memory steps in the
+ * briefing. Two slices:
+ *   - the recentSteps tail the MCP already injected (last 5–10 steps,
+ *     regardless of kind), which gives the model the latest tool
+ *     outputs in order; and
+ *   - up to 3 most-recent reasoning-kind steps from the full step log,
+ *     which keeps the "why" trail visible even after a chatty tool
+ *     burst has pushed reasoning off the tail.
+ *
+ * Returns null when the payload doesn't look like a working-context
+ * JSON blob — caller falls back to the opaque-dump branch so secrets
+ * still get redacted on unstructured text.
+ */
+function renderWorkingMemorySection(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const recentSteps = Array.isArray(parsed?.state?.injectedState?.recentSteps)
+        ? parsed.state.injectedState.recentSteps
+        : [];
+    const allSteps = Array.isArray(parsed?.steps) ? parsed.steps : recentSteps;
+    if (recentSteps.length === 0 && allSteps.length === 0)
+        return null;
+    const renderStep = (step) => {
+        const kind = step.kind ? `[${step.kind}] ` : '';
+        const title = (step.title ?? '').replace(/\s+/g, ' ').trim() || '(no title)';
+        const summary = (step.summary ?? '').replace(/\s+/g, ' ').trim();
+        const preview = summary.length > 200 ? summary.slice(0, 199) + '…' : summary;
+        return `- ${kind}${title}${preview ? ` — ${preview}` : ''}`;
+    };
+    const lines = [`### ${prettyLabel('memory_working_context')}`];
+    if (recentSteps.length > 0) {
+        lines.push('Recent steps:');
+        for (const step of recentSteps)
+            lines.push(renderStep(step));
+    }
+    // Surface up to 3 most-recent reasoning-kind steps that the recentSteps
+    // tail didn't already include. Cap on purpose — without it a turn that
+    // offloaded reasoning every batch would stuff the briefing with its own
+    // past commentary.
+    const recentNodeIds = new Set(recentSteps.map((s) => s.nodeId).filter(Boolean));
+    const reasoningTail = allSteps
+        .filter((s) => s.kind === 'reasoning' && (!s.nodeId || !recentNodeIds.has(s.nodeId)))
+        .slice(-3);
+    if (reasoningTail.length > 0) {
+        lines.push('', 'Recent reasoning (why-trail):');
+        for (const step of reasoningTail)
+            lines.push(renderStep(step));
+    }
+    return redactText(lines.join('\n'));
+}
 function dedupe(items) {
     return Array.from(new Set(items));
 }

package/dist/memory/consolidation.d.ts

@@ -1,4 +1,4 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 /**
  * Filesystem memory consolidation — the human-readable companion to the
  * cognitive memory database.