@kinqs/brainrouter-cli 0.3.5 → 0.3.6

package/dist/cli/repl.js

@@ -2,17 +2,20 @@ import readline from 'node:readline';
 import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
-import ora from 'ora';
+import { spinner } from './spinner.js';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { expandMentions } from '../memory/mentions.js';
-import { addGoalTokens, buildBudgetSteeringMessage, goalHasBudgetLeft, goalIsOnFinalBudgetTurn, readGoal, tickGoalIteration, usageLimitGoal } from '../state/goalStore.js';
+import { addGoalTokens, buildGoalContinuationPrompt, formatBudget, goalHasBudgetLeft, readGoal, tickGoalIteration, usageLimitGoal } from '../state/goalStore.js';
 import { readPreferences } from '../state/preferencesStore.js';
 import { execSync } from 'node:child_process';
 import { listSessions } from '../orchestration/orchestrator.js';
-import { setActiveReadline } from './cliPrompt.js';
+import { isPickerActive, setActiveReadline } from './cliPrompt.js';
+import { resolveTheme } from './theme.js';
+import { buildBannerInputs, renderBanner } from './banner.js';
+import { isKnownSegment, renderSegments } from './statusline.js';
 // Category dispatch — extracted slash-command handlers. Each module exports
 // a tryHandleX(ctx) that returns true iff it matched the command. Walked
 // in order; first match wins, no match falls through to the legacy switch.
@@ -23,6 +26,7 @@ import { tryHandleObsCommand } from './commands/obs.js';
 import { tryHandleOrchestrationCommand } from './commands/orchestration.js';
 import { tryHandleSessionCommand } from './commands/session.js';
 import { tryHandleGuardCommand } from './commands/guard.js';
+import { tryHandleMcpCommand } from './commands/mcp.js';
 const execPromise = promisify(exec);
 // Setup marked terminal rendering
 marked.use(markedTerminal({
@@ -33,36 +37,53 @@ marked.use(markedTerminal({
  * the readline completer. Keep alphabetically grouped roughly by surface area.
  */
 const SLASH_COMMANDS = [
-    '/help', '/status', '/workspace', '/tools', '/skills', '/plan', '/transcript',
+    '/help', '/status', '/workspace', '/where', '/tools', '/skills', '/plan', '/transcript',
     '/doctor', '/config', '/diff', '/commit', '/clear', '/compact', '/exit', '/quit',
     '/roles', '/agents', '/agent', '/spawn', '/wait',
-    '/spec', '/feature-dev', '/review', '/implement-plan', '/skill', '/workflows', '/approve',
+    '/spec', '/feature-dev', '/grill-me', '/review', '/implement-plan', '/skill', '/workflow', '/workflows', '/approve',
     '/memory', '/recall', '/briefing', '/scenes', '/working', '/forget',
     '/init', '/sessions', '/resume', '/model', '/mcp',
     '/goal', '/copy', '/fork', '/rename', '/permissions', '/hooks', '/hookify', '/loop',
-    '/continue', '/auto-review', '/vim', '/statusline',
+    '/continue', '/auto-review', '/vim', '/statusline', '/quiet',
     '/handover', '/explain', '/trace', '/failed', '/verify', '/audit',
     '/export', '/import', '/persona', '/skill-hints', '/diagnostics',
-    '/tokens', '/watch', '/yolo', '/sandbox', '/kill',
+    '/tokens', '/watch', '/yolo', '/mode', '/review-policy', '/sandbox', '/kill',
     // workflow & ergonomics commands
-    '/theme', '/title', '/personality', '/new', '/side', '/btw', '/raw',
+    '/theme', '/title', '/personality', '/effort', '/new', '/side', '/btw', '/raw',
     '/feedback', '/rollout', '/ps', '/stop', '/logout', '/apps', '/plugins',
     '/experimental', '/memories', '/debug-config', '/mention', '/keymap', '/ide',
 ];
 export function startREPL(agent, mcpClient, config, workspace) {
-    console.log(chalk.bold.hex('#CC9166')('\n🧠 BRAINROUTER TERMINAL AGENT CLIENT v0.3.5'));
-    console.log(chalk.gray('Midnight Ledger / Obsidian Surface theme active.'));
-    console.log(chalk.gray(`Workspace root: ${workspace?.workspaceRoot || process.cwd()}`));
-    // Surface offline mode prominently — easy to miss the warning that scrolled
-    // by during startup, and the user needs to know memory tools won't fire.
+    const theme = resolveTheme(agent.workspaceRoot);
+    const banner = renderBanner(buildBannerInputs(config, agent, mcpClient), theme);
+    console.log('\n' + banner);
+    // Offline-mode advisory stays as a separate line below the box so the
+    // colored warning isn't easy to miss when scanning past banner chrome.
+    // Carries the remediation hint that used to live as a duplicate pre-banner
+    // warning in the chat command's catch block.
     if (!mcpClient.isConnected()) {
-        console.log(chalk.yellow('⚠️  OFFLINE MODE — MCP server unreachable. Local tools only; memory recall / skills disabled.'));
+        console.log(theme.warning('  ⚠️  OFFLINE MODE — MCP server unreachable. Memory recall, skills, and capture are disabled.'));
+        console.log(theme.muted('       Local tools (file edits, shell, web fetch, spawn_agent) still work.'));
+        console.log(theme.muted('       Start the MCP server and restart the CLI to restore full functionality.'));
     }
-    console.log(chalk.gray('Type ') + chalk.cyan('/help') + chalk.gray(' for commands, or start typing your prompt.\n'));
+    console.log(theme.muted('  Type ') + theme.info('/help') +
+        theme.muted(' for commands · ') + theme.info('/where') +
+        theme.muted(' for current state · just start typing your prompt.\n'));
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
-        prompt: chalk.hex('#CC9166')('brainrouter> '),
+        // Explicit `terminal: true` instead of relying on the auto-detect from
+        // `input.isTTY`. The auto-detect returns `undefined` in some shells /
+        // terminal multiplexers (tmux on certain platforms, VS Code's integrated
+        // terminal with specific settings, ssh -t pipelines), and a falsy value
+        // means readline falls back to a non-TTY interface — no keypress events,
+        // no raw mode, Backspace echoes as `^?` instead of erasing.
+        terminal: true,
+        // Initial prompt uses the resolved theme's primary accent so light/mono
+        // users get a readable prompt even on the first draw. refreshPromptForMode
+        // re-renders immediately after wiring up the access-mode accent, so this
+        // initial value mostly governs the millisecond before that runs.
+        prompt: theme.primary('brainrouter> '),
         // Tab-completion: complete slash commands when the line begins with "/"
         // and complete workspace file paths when the user is mid-`@mention`.
         completer: (line) => {
@@ -79,6 +100,20 @@ export function startREPL(agent, mcpClient, config, workspace) {
             return [[], line];
         },
     });
+    // Belt-and-suspenders: force-engage raw-mode keypress handling on stdin.
+    // readline.createInterface does this internally for a TTY input, but its
+    // auto-init is unreliable across the terminal zoo (tmux, screen, VS Code
+    // integrated terminal, certain SSH setups) — when it doesn't engage, the
+    // symptom is Backspace echoing `^?` and arrow keys echoing `^[[A` instead
+    // of doing what they're supposed to do. Calling these here is a no-op when
+    // readline already did them, and a fix in the cases where it didn't.
+    if (process.stdin.isTTY) {
+        try {
+            readline.emitKeypressEvents(process.stdin);
+            process.stdin.setRawMode?.(true);
+        }
+        catch { /* not a real TTY after all */ }
+    }
     // GitHub PR detection cache. `gh pr view` takes ~300ms and prompts often
     // refresh many times per turn; cache the result for 30s. Returns either
     // a string like "#42" or null when there's no PR / gh not installed.
@@ -109,48 +144,31 @@ export function startREPL(agent, mcpClient, config, workspace) {
     };
     // Reflect the current access mode and any configured statusline segments
     // in the prompt. Configurable via /statusline; default just shows the mode.
+    // Segment expansion lives in ./statusline.ts so the segment vocabulary is
+    // one source of truth for both /statusline and the prompt renderer.
     const renderStatusline = () => {
         const prefs = readPreferences(agent.workspaceRoot);
-        const segments = prefs.statusline.split(',').map((s) => s.trim()).filter(Boolean);
-        const out = [];
-        for (const seg of segments) {
-            if (seg === 'mode')
-                out.push(agent.getAccessMode());
-            else if (seg === 'model')
-                out.push(agent.getModel());
-            else if (seg === 'tokens') {
-                const u = agent.lastTurnUsage;
-                if (u.calls > 0)
-                    out.push(`${u.promptTokens}↑${u.completionTokens}↓`);
-            }
-            else if (seg === 'session') {
-                const k = agent.sessionKey;
-                out.push(k.length > 22 ? `${k.slice(0, 22)}…` : k);
-            }
-            else if (seg === 'branch' || seg === 'dirty') {
-                try {
-                    const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: agent.workspaceRoot, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-                    const dirty = execSync('git status --porcelain', { cwd: agent.workspaceRoot, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() !== '';
-                    if (seg === 'branch')
-                        out.push(branch);
-                    else if (seg === 'dirty' && dirty)
-                        out.push('*');
-                }
-                catch { /* not a git repo */ }
-            }
-            else if (seg === 'pr') {
-                // Detect open GitHub PR for the current branch — 30s cache so the
-                // prompt refresh is cheap (re-shells out only on a stale window).
-                const pr = detectGitHubPR(agent.workspaceRoot);
-                if (pr)
-                    out.push(pr);
-            }
-        }
-        return out.filter(Boolean).join(' · ');
+        const requested = prefs.statusline.split(',').map((s) => s.trim()).filter(Boolean);
+        const segments = requested.filter(isKnownSegment);
+        return renderSegments(segments, {
+            workspaceRoot: agent.workspaceRoot,
+            sessionKey: agent.sessionKey,
+            accessMode: agent.getAccessMode(),
+            model: agent.getModel(),
+            lastTurnUsage: agent.lastTurnUsage,
+            prDetector: () => detectGitHubPR(agent.workspaceRoot),
+        }).join(' · ');
     };
     const refreshPromptForMode = () => {
         const mode = agent.getAccessMode();
-        const accent = mode === 'shell' ? chalk.red : mode === 'write' ? chalk.hex('#CC9166') : chalk.green;
+        // Mode-to-token mapping reads as semantic intent rather than raw color:
+        //   read  → success  (least dangerous; matches the ✓ established for "ok")
+        //   write → primary  (brand accent; the default writable mode)
+        //   shell → danger   (escalated capability; same color as failed tools)
+        // Theme tokens mean BRAINROUTER_THEME=light|mono actually affects the
+        // prompt — the surface the user stares at most. Previously hard-coded
+        // chalk.hex('#CC9166')/red/green ignored the user's theme entirely.
+        const accent = mode === 'shell' ? theme.danger : mode === 'write' ? theme.primary : theme.success;
         const line = renderStatusline();
         rl.setPrompt(accent(`brainrouter[${line}]> `));
         // The terminal title shares the same trigger conditions as the prompt:
@@ -213,6 +231,20 @@ export function startREPL(agent, mcpClient, config, workspace) {
         }
         catch { /* terminal doesn't support OSC titles */ }
     };
+    // Quiet mode: hides recall tables, briefing dumps, tool-completion previews.
+    // Env var (`BRAINROUTER_QUIET`, set by --quiet flag) wins for the session;
+    // /quiet writes through to preferences AND mirrors into the env so toggling
+    // back-and-forth keeps a single source of truth at read time.
+    const isQuiet = () => {
+        if (process.env.BRAINROUTER_QUIET === '1')
+            return true;
+        try {
+            return readPreferences(agent.workspaceRoot).quiet === true;
+        }
+        catch {
+            return false;
+        }
+    };
     refreshPromptForMode();
     refreshTerminalTitle();
     // Vim mode: readline supports editorMode 'vi' via setRawMode + tty.
@@ -227,13 +259,19 @@ export function startREPL(agent, mcpClient, config, workspace) {
     }
     // Shift+Tab cycles the access mode.
     // Order: read → write → shell → read …
-    if (process.stdin.isTTY) {
-        try {
-            process.stdin.setRawMode?.(false);
-        }
-        catch { /* noop */ }
-    }
+    // NOTE: a previous version called `setRawMode(false)` here, claiming it
+    // was needed for keypress events. The opposite is true — readline enables
+    // raw mode automatically for a TTY input, and disabling it breaks BOTH
+    // (a) keypress event delivery for shift+tab (which depend on raw bytes)
+    // and (b) Backspace handling at the prompt (readline expects to receive
+    // the raw 0x7F itself; in cooked mode the terminal's line discipline
+    // owns it and readline's internal buffer drifts out of sync). Leave the
+    // default in place.
     process.stdin.on('keypress', (_str, key) => {
+        // The ask_user_choice picker owns stdin while it's on screen; yield to
+        // it or shift+tab would cycle the access mode mid-picker.
+        if (isPickerActive())
+            return;
         if (key && key.name === 'tab' && key.shift) {
             const cycle = ['read', 'write', 'shell'];
             const current = agent.getAccessMode();
@@ -252,43 +290,44 @@ export function startREPL(agent, mcpClient, config, workspace) {
     rl.prompt();
     let isProcessing = false;
     // (pendingContinuation declared earlier alongside the title refresh helpers.)
-    /**
-     * Prompt the agent receives for iterations 2..N of an active goal —
-     * fired automatically by the post-turn loop after each completed turn.
-     * Orients the model around the active objective, forces an evidence
-     * audit, and refuses prose-only "I will continue" answers.
-     *
-     * Distinct from `buildGoalKickoffPrompt` (in `commands/_helpers.ts`),
-     * which is the FIRST-turn prompt fired by `/goal <text>` and `/goal resume`.
-     */
-    const buildGoalContinuationPrompt = (goal, lastPrompt, lastAnswer) => {
-        const iter = goal.budget.iterationsUsed + 1;
-        const remaining = Math.max(0, goal.budget.maxIterations - iter);
-        return [
-            `[GOAL CONTINUATION — iteration ${iter}/${goal.budget.maxIterations}, ${remaining} remaining]`,
-            '',
-            `Your active goal is: ${goal.text}`,
-            '',
-            `Last user message: ${lastPrompt || '(none)'}`,
-            `Your previous response (truncated): ${lastAnswer.slice(0, 600)}${lastAnswer.length > 600 ? '…' : ''}`,
-            '',
-            '## What to do this turn',
-            '1. **Audit the evidence in this thread** against the goal\'s outcome. Look at files you wrote, tests you ran, tools that returned ok=true.',
-            '2. **Decide one of three:**',
-            '   - If the outcome is met with concrete evidence (file paths, test names, command outputs), **write the user-visible answer / analysis / summary as prose AND THEN call `goal_complete` with a short 1–2 sentence proof — in the SAME response.** The proof is audit metadata; the prose is what the user reads. Skipping the prose means the user sees a placeholder.',
-            '   - If no defensible path forward remains without user input or missing materials, **write the user-visible explanation as prose AND THEN call `goal_blocked` with a reason + needed input.**',
-            '   - Otherwise (mid-goal), take the **next concrete tool action** (read a file, write code, spawn a worker child, run a verifier). Do NOT respond with prose like "I will now do X" — that\'s a no-op and the CLI will stop the continuation. Anti-spin applies to mid-goal turns; the final goal-completing turn requires prose.',
-            '3. Use update_plan to track progress if you haven\'t already.',
-            '',
-            'Reminder: budget is finite. Pick the highest-leverage action that moves the goal forward.',
-        ].join('\n');
+    // Idle help hint: one-time per session. 30s after the prompt appears (and
+    // while neither a turn nor a pending continuation is running), print a
+    // single discoverability nudge so first-time users find /help and /where.
+    // Dismissed permanently as soon as it fires or the user starts typing.
+    // safePrintAbovePrompt is defined further down — the actual call only
+    // happens via setTimeout (30s after declaration), so by firing time
+    // safePrintAbovePrompt has been bound, no TDZ in practice.
+    let idleHintFired = false;
+    let idleHintTimer;
+    const clearIdleHint = () => {
+        if (idleHintTimer) {
+            clearTimeout(idleHintTimer);
+            idleHintTimer = undefined;
+        }
+    };
+    const armIdleHint = () => {
+        if (idleHintFired || !process.stdout.isTTY)
+            return;
+        clearIdleHint();
+        idleHintTimer = setTimeout(() => {
+            if (idleHintFired || isProcessing || pendingContinuation)
+                return;
+            idleHintFired = true;
+            safePrintAbovePrompt(chalk.gray('  Tip: press ') + chalk.cyan('?') + chalk.gray(' or ') +
+                chalk.cyan('/help') + chalk.gray(' for commands, ') + chalk.cyan('/where') +
+                chalk.gray(' for current state.'));
+        }, 30_000);
+        if (typeof idleHintTimer.unref === 'function') {
+            // unref so a fully-idle CLI can still exit cleanly on Ctrl-C / SIGTERM.
+            idleHintTimer.unref();
+        }
     };
     /**
      * Print a line of output while the readline prompt is showing without
      * clobbering whatever the user is mid-typing. Used by child-agent callbacks
      * that fire AFTER the parent's runTurn returned — the agent's tool events
      * keep streaming for a while because children run detached, and naive
-     * console.log + spinner.start() would steal the input row.
+     * console.log + turnSpinner.start() would steal the input row.
      */
     const safePrintAbovePrompt = (msg) => {
         if (!process.stdout.isTTY) {
@@ -306,6 +345,9 @@ export function startREPL(agent, mcpClient, config, workspace) {
             rl.prompt(true);
         }
     };
+    // Now that safePrintAbovePrompt is bound, arm the idle hint for the first
+    // time. Subsequent arming happens after each prompt redraw in runAgentTurn.
+    armIdleHint();
     /** Run a turn programmatically (used by `/continue` and the line handler). */
     const runAgentTurn = async (rawInput) => {
         if (isProcessing) {
@@ -315,11 +357,11 @@ export function startREPL(agent, mcpClient, config, workspace) {
         isProcessing = true;
         rl.pause();
         const { expanded, mentions } = expandMentions(rawInput, agent.workspaceRoot);
-        if (mentions.length > 0) {
+        if (mentions.length > 0 && !isQuiet()) {
             console.log(chalk.gray(`📎  Attached ${mentions.length} file${mentions.length === 1 ? '' : 's'}: ${mentions.map((m) => m.token).join(', ')}`));
         }
         const startedAt = Date.now();
-        const spinner = ora(chalk.gray('Agent starting...')).start();
+        const turnSpinner = spinner(chalk.gray('Agent starting...')).start();
         // Once the parent's runTurn returns, child agents may still emit tool
         // events asynchronously. After this flag flips, we MUST NOT touch the
         // spinner (which is already .succeeded) — restarting it would steal the
@@ -331,12 +373,17 @@ export function startREPL(agent, mcpClient, config, workspace) {
             const elapsed = Math.floor((Date.now() - startedAt) / 1000);
             const u = agent.lastTurnUsage;
             const tokens = u.calls > 0 ? `  ${u.promptTokens.toLocaleString()}↑ ${u.completionTokens.toLocaleString()}↓` : '';
-            spinner.text = chalk.gray(`${status}  ${elapsed}s${tokens}`);
+            turnSpinner.text = chalk.gray(`${status}  ${elapsed}s${tokens}`);
         };
         try {
             const answer = await agent.runTurn(expanded, {
                 onStatusUpdate: tickStatus,
                 onToolStart: (name, args) => {
+                    // Quiet mode: skip tool-start chrome entirely. The spinner already
+                    // reflects "something is happening" and the final prose tells the
+                    // story. Errors still surface via onToolEnd's failure branch.
+                    if (isQuiet())
+                        return;
                     // Render spawn_agent / spawn_agents specially — a one-liner
                     // ("Ran agent <role> — <one-line task>") so a fan-out of 5
                     // children produces 5 clean lines instead of 5 JSON dumps. The
@@ -363,10 +410,17 @@ export function startREPL(agent, mcpClient, config, workspace) {
                         safePrintAbovePrompt(line);
                         return;
                     }
-                    spinner.stop();
+                    turnSpinner.stop();
                     console.log(line);
                 },
                 onToolEnd: (name, result) => {
+                    // Quiet mode: only print on failure. Successes are invisible — the
+                    // prose answer or downstream tool calls speak for themselves.
+                    if (isQuiet() && result.success) {
+                        tickStatus('Thinking');
+                        turnSpinner.start();
+                        return;
+                    }
                     const line = result.success
                         ? chalk.green('✓  Tool ') + chalk.cyan(name) + chalk.green(' completed: ') + chalk.gray(result.summary)
                         : chalk.red('❌  Tool ') + chalk.cyan(name) + chalk.red(' failed: ') + chalk.yellow(result.summary);
@@ -374,8 +428,10 @@ export function startREPL(agent, mcpClient, config, workspace) {
                     // sees the actual result (directory listing, grep matches, glob
                     // paths) even when the LLM later replies with only a stub like
                     // "I have listed the directory." Capped to a handful of lines in
-                    // getToolPreview itself.
-                    const previewBlock = result.preview
+                    // getToolPreview itself. Quiet mode drops the preview even on
+                    // failure — the summary tells the user what broke; the preview is
+                    // for diagnosing why and isn't worth the screen real-estate.
+                    const previewBlock = result.preview && !isQuiet()
                         ? '\n' + result.preview.split('\n').map((l) => chalk.gray('    ' + l)).join('\n')
                         : '';
                     const composed = line + previewBlock;
@@ -385,14 +441,14 @@ export function startREPL(agent, mcpClient, config, workspace) {
                     }
                     console.log(composed);
                     tickStatus('Thinking');
-                    spinner.start();
+                    turnSpinner.start();
                 },
                 onPlanUpdate: (items, explanation) => {
                     if (parentDone) {
                         safePrintAbovePrompt(chalk.gray(`📋  Plan updated (${items.length} item${items.length === 1 ? '' : 's'})`));
                         return;
                     }
-                    spinner.stop();
+                    turnSpinner.stop();
                     console.log(chalk.gray('📋  Plan updated:'));
                     if (explanation)
                         console.log(chalk.gray(`    ${explanation}`));
@@ -404,7 +460,7 @@ export function startREPL(agent, mcpClient, config, workspace) {
                         console.log(`    ${mark} ${text}`);
                     }
                     tickStatus('Thinking');
-                    spinner.start();
+                    turnSpinner.start();
                 },
                 onChildComplete: (event) => {
                     const head = event.status === 'completed'
@@ -418,12 +474,16 @@ export function startREPL(agent, mcpClient, config, workspace) {
                         safePrintAbovePrompt(line);
                         return;
                     }
-                    spinner.stop();
+                    turnSpinner.stop();
                     console.log(line);
                     tickStatus('Thinking');
-                    spinner.start();
+                    turnSpinner.start();
                 },
                 onMemoryEvent: (event) => {
+                    // Quiet mode: silence briefing/capture/citation chatter. Keep
+                    // contradictions audible — those are warnings the user should see.
+                    if (isQuiet() && event.kind !== 'contradiction')
+                        return;
                     let line;
                     if (event.kind === 'briefing') {
                         const src = event.sources.length > 0 ? event.sources.join(', ') : '(none)';
@@ -473,10 +533,10 @@ export function startREPL(agent, mcpClient, config, workspace) {
                         safePrintAbovePrompt(line);
                         return;
                     }
-                    spinner.stop();
+                    turnSpinner.stop();
                     console.log(line);
                     tickStatus('Thinking');
-                    spinner.start();
+                    turnSpinner.start();
                 },
             });
             const elapsed = Math.floor((Date.now() - startedAt) / 1000);
@@ -485,7 +545,7 @@ export function startREPL(agent, mcpClient, config, workspace) {
                 ? chalk.gray(` · ${u.promptTokens.toLocaleString()} in / ${u.completionTokens.toLocaleString()} out across ${u.calls} call${u.calls === 1 ? '' : 's'}`)
                 : '';
             parentDone = true;
-            spinner.succeed(chalk.green(`Done!${chalk.gray(` ${elapsed}s`)}${tokenSummary}`));
+            turnSpinner.succeed(chalk.green(`Done!${chalk.gray(` ${elapsed}s`)}${tokenSummary}`));
             const prefsForRender = readPreferences(agent.workspaceRoot);
             const rendered = prefsForRender.rawScrollback ? answer : marked.parse(answer);
             console.log('\n' + rendered + '\n');
@@ -497,16 +557,21 @@ export function startREPL(agent, mcpClient, config, workspace) {
         }
         catch (err) {
             parentDone = true;
-            spinner.fail(chalk.red('Execution failed'));
+            turnSpinner.fail(chalk.red('Execution failed'));
             console.error(chalk.red(`\nError: ${err.message}\n`));
         }
         finally {
             isProcessing = false;
             // Clear any active skill latched by /skill / /feature-dev / /spec /
-            // /review / /implement-plan so subsequent plain prompts don't keep
-            // spiking the same skill. The skill memetic potential still decays
-            // server-side on its own half-life; this just stops attribution.
+            // /review / /implement-plan / /grill-me so subsequent plain prompts
+            // don't keep spiking the same skill. The skill memetic potential
+            // still decays server-side on its own half-life; this just stops
+            // attribution. Also refresh the system prompt so skill-conditional
+            // overlays (e.g. grill-me's CLARIFY block) disappear from
+            // chatHistory[0] before the user's next prompt — otherwise the
+            // model would see "do not make file edits" carrying over.
             agent.activeSkill = undefined;
+            agent.refreshSystemPrompt();
             // Auto-continuation logic. Rules:
             //   - the goal must be active (not paused / complete / blocked / usage_limited)
             //   - the turn made at least one tool call (prose-only turns are anti-spin)
@@ -553,7 +618,7 @@ export function startREPL(agent, mcpClient, config, workspace) {
             else if (goalAfter && goalAfter.status === 'active' && !goalHasBudgetLeft(goalAfter)) {
                 // Iteration cap reached — transition to usage_limited so the user
                 // gets a consistent resumable state regardless of which cap tripped.
-                const reason = `Iteration budget exhausted (${goalAfter.budget.iterationsUsed}/${goalAfter.budget.maxIterations}).`;
+                const reason = `Iteration budget exhausted (${goalAfter.budget.iterationsUsed}/${formatBudget(goalAfter.budget.maxIterations)}).`;
                 const limited = usageLimitGoal(agent.workspaceRoot, agent.sessionKey, reason);
                 console.log(chalk.yellow(`\n⏸  ${reason} Extend with /goal budget <n> and /goal resume, mark /goal complete, or /goal clear.\n`));
                 if (limited)
@@ -563,30 +628,30 @@ export function startREPL(agent, mcpClient, config, workspace) {
                 console.log(chalk.gray(`(goal continuation suppressed: last turn made no tool calls — anti-spin)\n`));
             }
             rl.resume();
+            // NOTE: do NOT call setRawMode(true) here. readline's rl.resume()
+            // already calls input._setRawMode(true) internally for terminal
+            // interfaces. A redundant external setRawMode(true) DOES re-engage
+            // raw mode (it's idempotent for the mode itself) BUT it also resets
+            // `this.readableFlowing = null` on the stream as a side effect
+            // (lib/tty.js). After that, the stream is in "auto" flowing state
+            // and keystrokes don't reach readline — user sees a live prompt
+            // they can't type into. Trust the internal call.
             refreshPromptForMode(); // pick up token-meter / branch updates
             rl.prompt();
+            // Re-arm the idle hint after each completed turn — a user who walks
+            // away after a turn ends still gets one nudge if they hadn't seen it.
+            armIdleHint();
             if (shouldContinue && goalAfter) {
                 pendingContinuation = true;
                 const next = goalAfter.budget.iterationsUsed + 1;
-                // Pre-tick steering: if the NEXT turn would be the final one inside
-                // the budget, inject a wrap-up directive so the model lands soft
-                // instead of being cut off mid-thought.
-                //
-                // CRITICAL: also drop any stale steering when the next turn is NOT
-                // final. Without this, a previously-injected "wrap up gracefully"
-                // message would persist after the user extended the budget via
-                // /goal budget or /goal tokens, telling the model "this is your
-                // last turn" for every subsequent turn. The removal is idempotent
-                // — if no steering was set, this is a no-op.
-                const finalBudgetTurn = goalIsOnFinalBudgetTurn(goalAfter);
-                if (finalBudgetTurn) {
-                    agent.replaceTaggedSystemMessage('goal-budget-steering', buildBudgetSteeringMessage(goalAfter));
-                    console.log(chalk.gray(`(final budget turn — wrap-up steering injected)`));
-                }
-                else {
-                    agent.removeTaggedSystemMessage('goal-budget-steering');
-                }
-                console.log(chalk.gray(`(goal continuation queued — iteration ${next}/${goalAfter.budget.maxIterations}; type anything to cancel)`));
+                // Pre-9d this branch installed a separate `goal-budget-steering`
+                // tagged system message when the next turn was the final one
+                // inside the budget. 9d folded the wrap-up directive into the
+                // goal-anchor itself — `formatGoalBlock` now auto-detects the
+                // final-budget-turn state and prepends the directive — so the
+                // tagged-message bookkeeping disappears entirely. The anchor is
+                // re-rendered at the top of every runTurn (`agent.ts:677-686`).
+                console.log(chalk.gray(`(goal continuation queued — iteration ${next}/${formatBudget(goalAfter.budget.maxIterations)}; type anything to cancel)`));
                 const followUp = buildGoalContinuationPrompt(goalAfter, agent.lastUserPrompt, agent.lastAnswer);
                 setImmediate(() => {
                     if (!pendingContinuation || isProcessing)
@@ -599,6 +664,10 @@ export function startREPL(agent, mcpClient, config, workspace) {
         }
     };
     rl.on('line', async (line) => {
+        // User typed anything → drop the pending idle-hint timer regardless of
+        // whether the input itself is meaningful. Empty enter still counts as
+        // engagement; we don't want to nag a user who's clearly at the keyboard.
+        clearIdleHint();
         // User typed: any pending goal continuation is cancelled.
         if (pendingContinuation) {
             pendingContinuation = false;
@@ -609,6 +678,13 @@ export function startREPL(agent, mcpClient, config, workspace) {
             rl.prompt();
             return;
         }
+        // Treat a bare "?" as /help — the idle-hint tip advertises it, so make
+        // it actually work. Anything beyond "?" (a real prompt) falls through.
+        if (input === '?') {
+            renderHelp();
+            rl.prompt();
+            return;
+        }
         if (input.startsWith('/')) {
             // Split on any whitespace, not a literal space. Without this, a slash
             // command followed by a tab (autocomplete completion that wasn't
@@ -664,6 +740,7 @@ const HELP_CATEGORIES = [
         entries: [
             { cmd: '/status', desc: 'Connection status, LLM config, DB stats' },
             { cmd: '/workspace', desc: 'Active workspace and session identity' },
+            { cmd: '/where', desc: 'Single-screen view of workspace, workflow, goal, plan, recall, children' },
             { cmd: '/doctor', desc: 'Config, connection, memory extraction health' },
             { cmd: '/config', desc: 'View active configuration profile' },
             { cmd: '/clear', desc: 'Clear chat history for the active session' },
@@ -708,13 +785,17 @@ const HELP_CATEGORIES = [
         entries: [
             { cmd: '/spec <title>', desc: 'Produce spec.md (spec-driven-skill)' },
             { cmd: '/feature-dev <feat>', desc: 'Multi-agent feature dev with spec + tasks' },
+            { cmd: '/grill-me [--force] <task>', desc: 'Clarify 2–5 questions before implementing (CLARIFY mode)' },
             { cmd: '/review [scope]', desc: 'Multi-agent code review → review.md' },
             { cmd: '/implement-plan', desc: 'Execute next plan item; append walkthrough' },
             { cmd: '/approve [slug]', desc: 'Approve workflow + kick off implementation' },
             { cmd: '/workflows', desc: 'List durable workflow folders' },
+            { cmd: '/workflow switch <slug>', desc: 'Refocus on an existing workflow (migrates any session goal into the target)' },
+            { cmd: '/workflow pause', desc: 'Pause the current workflow\'s goal' },
+            { cmd: '/workflow resume <slug>', desc: 'Switch to <slug> AND resume its goal in one shot' },
             { cmd: '/skill <name> [input]', desc: 'Run any catalogued skill' },
             { cmd: '/skills', desc: 'List installed BrainRouter skills' },
-            { cmd: '/plan', desc: 'Show the durable CLI task plan' },
+            { cmd: '/plan  /plan clear', desc: 'Show the durable CLI task plan; clear it (drops stale items)' },
             { cmd: '/tools', desc: 'List local + MCP tools available to the agent' },
             { cmd: '/goal [text|clear|complete|pause|resume|budget <n>]', desc: 'Sticky goal' },
             { cmd: '/continue', desc: 'Resume after a loop-limit abort' },
@@ -743,7 +824,9 @@ const HELP_CATEGORIES = [
         title: 'Guardrails & Permissions',
         entries: [
             { cmd: '/permissions [read|write|shell]', desc: 'View or set agent access mode' },
-            { cmd: '/yolo [on|off]', desc: 'Auto-approve run_command' },
+            { cmd: '/mode [planning|fast]', desc: 'Session execution stance (planning asks, fast skips per-call y/N for safe commands)' },
+            { cmd: '/review-policy [request|proceed]', desc: 'How the agent treats multi-file approval gates' },
+            { cmd: '/yolo [on|off]', desc: 'Alias for `/mode fast` + `/review-policy proceed`' },
             { cmd: '/sandbox [status|add-read|add-write|remove|clear]', desc: 'Sandbox grants' },
             { cmd: '/hooks [list|add|remove|enable|disable]', desc: 'Lifecycle shell hooks' },
             { cmd: '/hookify [list|create|enable|disable|remove]', desc: 'Markdown rule guards' },
@@ -768,15 +851,17 @@ const HELP_CATEGORIES = [
         entries: [
             { cmd: '/theme [auto|light|dark|mono]', desc: 'Markdown output theme' },
             { cmd: '/title <segments>', desc: 'Terminal title (model,session,branch,mode)' },
-            { cmd: '/statusline <segments>', desc: 'Prompt (mode,branch,dirty,model,tokens,session,pr)' },
+            { cmd: '/statusline <segments>', desc: 'Prompt (mode,exec,effort,branch,dirty,model,tokens,session,pr,workflow,goal,plan)' },
             { cmd: '/personality <style>', desc: 'concise | standard | detailed | pair-programmer' },
+            { cmd: '/effort [low|medium|high]', desc: 'Reasoning depth: low=terse, medium=default, high=step-by-step (env: BRAINROUTER_EFFORT)' },
             { cmd: '/raw [on|off]', desc: 'Toggle raw scrollback' },
+            { cmd: '/quiet [on|off]', desc: 'Hide recall tables, previews, briefings (model prose only)' },
             { cmd: '/vim', desc: 'Toggle vi-mode for the composer' },
             { cmd: '/keymap [json]', desc: 'Show built-in bindings and set overrides' },
             { cmd: '/copy', desc: 'Copy last assistant response to clipboard' },
             { cmd: '/mention [partial]', desc: 'Suggest files for @ mentions' },
             { cmd: '/model <name>', desc: 'Switch the LLM model in-session' },
-            { cmd: '/mcp', desc: 'Show the active MCP server and tool namespaces' },
+            { cmd: '/mcp [list|reconnect|tools]', desc: 'MCP profiles, identity tags, online/offline status, reconnect, tool namespaces' },
             { cmd: '/ide', desc: 'Show detected IDE host' },
             { cmd: '/apps  /plugins', desc: 'List workspace skills and plugin folders' },
             { cmd: '/feedback [message]', desc: 'Append feedback entry' },
@@ -848,6 +933,8 @@ async function handleSlashCommand(command, args, agent, mcpClient, config, rl, c
         return;
     if (await tryHandleGuardCommand(cmdCtx))
         return;
+    if (await tryHandleMcpCommand(cmdCtx))
+        return;
     // All commands extracted to category files above. Anything that reaches
     // here didn't match any handler.
     console.log(chalk.red(`\nUnknown slash command: ${command}. Type /help for assistance.\n`));