@axplusb/kepler 1.0.10 → 2.0.2

package/src/onboarding/preflight.mjs

@@ -0,0 +1,292 @@
+/**
+ * Preflight diagnostic — Mission Control (PRD-055 §9).
+ *
+ * Prints a non-blocking summary of the runtime environment before the REPL
+ * starts so the user can see what is and is not aligned:
+ *
+ *   🔭 Kepler v1.0.4 · initializing orbit
+ *
+ *     [✓] Auth token
+ *     [✓] OpenRouter key
+ *     [✓] Backend  http://127.0.0.1:8000
+ *     [✓] Git repository  main · clean
+ *     [⚠] Linter (ruff) not found → /install ruff to enable lint_check
+ *     [✓] Project map  142 files, Python + TypeScript
+ *
+ *   All systems aligned. What are we building today?
+ *
+ * Checks are non-blocking. A failure shows a one-line next-step hint.
+ *
+ * Exposed via `runPreflight()` (called from REPL startup) and `/preflight`
+ * (registered as a slash command).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import http from 'node:http';
+import https from 'node:https';
+import { URL } from 'node:url';
+import { paint } from '../ui/palette.mjs';
+import { icons } from '../ui/icons.mjs';
+import { term } from '../ui/term.mjs';
+
+const OK   = (s) => `${paint.state.success('[✓]')} ${s}`;
+const WARN = (s) => `${paint.state.warn('[⚠]')} ${s}`;
+const FAIL = (s) => `${paint.state.danger('[✗]')} ${s}`;
+
+// ── Individual checks (each returns { status, label, hint? }) ──────────
+
+async function checkAuthAndBackend(auth, { timeoutMs = 2500 } = {}) {
+  const creds = auth.loadCredentials();
+  const hasToken = !!creds.token;
+  const url = creds.backendUrl;
+
+  // No token: just probe whether the backend is reachable so we can hint
+  // /login when it makes sense.
+  if (!hasToken) {
+    const reachable = url ? await ping(url, timeoutMs).catch(() => false) : false;
+    return reachable
+      ? { status: 'warn', label: 'Not signed in · backend ready', hint: '/login to sign in' }
+      : { status: 'warn', label: 'Not signed in · backend offline', hint: '/login once the network is back' };
+  }
+
+  // Token present: real authenticated round-trip against /api/user/me.
+  // Three outcomes: valid (200), expired (401/403), unreachable (network).
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    let resp;
+    try {
+      resp = await fetch(`${url}/api/user/me`, {
+        headers: { 'Authorization': `Bearer ${creds.token}` },
+        signal: ctrl.signal,
+      });
+    } finally { clearTimeout(t); }
+
+    if (resp.ok) {
+      const user = await resp.json().catch(() => null);
+      const who = user?.github_username || user?.email || 'user';
+      return { status: 'ok', label: `Signed in as ${who} · connected` };
+    }
+    if (resp.status === 401 || resp.status === 403) {
+      return { status: 'warn', label: 'Token expired · connected', hint: '/login again to refresh' };
+    }
+    return { status: 'warn', label: `Backend returned ${resp.status}`, hint: 'try again shortly' };
+  } catch {
+    return { status: 'warn', label: 'Signed in · backend offline', hint: 'check network or try again shortly' };
+  }
+}
+
+function checkGit(cwd) {
+  if (!hasGitDir(cwd)) return { status: 'warn', label: 'Not a git repository', hint: '`git init` to enable diff / checkpoints' };
+  try {
+    const branch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', { cwd, encoding: 'utf-8' }).trim();
+    const status = execSync('git status --porcelain 2>/dev/null', { cwd, encoding: 'utf-8' });
+    const dirty = status.split('\n').filter(Boolean).length;
+    const summary = dirty > 0
+      ? `${branch} · ${paint.state.warn(`${dirty} dirty`)}`
+      : `${branch} · clean`;
+    return { status: 'ok', label: `Git repository  ${summary}` };
+  } catch {
+    return { status: 'warn', label: 'Git repository present but unreadable' };
+  }
+}
+
+function checkLinters(cwd) {
+  const present = [];
+  const missing = [];
+  for (const linter of LINTERS) {
+    if (which(linter.bin)) present.push(linter);
+    else if (projectUses(cwd, linter.kind)) missing.push(linter);
+  }
+  if (present.length === 0 && missing.length === 0) {
+    return { status: 'ok', label: 'Linters  none required' };
+  }
+  if (missing.length === 0) {
+    return { status: 'ok', label: `Linters  ${present.map(p => p.bin).join(', ')}` };
+  }
+  // Honest install command per linter. Falls back to "install via your
+  // package manager" when there is no clean one-liner (e.g. cargo).
+  const hint = missing.map(m => m.install
+    ? `${m.bin}: ${m.install}`
+    : `install ${m.bin} for ${m.kind} support`
+  ).join(' · ');
+  return { status: 'warn', label: `Linter (${missing.map(m => m.bin).join(', ')}) not found`, hint };
+}
+
+const LINTERS = [
+  { bin: 'ruff',    kind: 'python',     install: 'pip install ruff' },
+  { bin: 'eslint',  kind: 'javascript', install: 'npm i -g eslint' },
+  { bin: 'tsc',     kind: 'typescript', install: 'npm i -g typescript' },
+  // cargo ships with rustup; no clean one-liner — surface the warning
+  // without a misleading "/install" command.
+  { bin: 'cargo',   kind: 'rust',       install: null },
+];
+
+function projectUses(cwd, kind) {
+  try {
+    const files = fs.readdirSync(cwd);
+    switch (kind) {
+      case 'python':     return files.some(f => /\.py$/.test(f)) || files.includes('pyproject.toml') || files.includes('requirements.txt');
+      case 'javascript': return files.includes('package.json');
+      case 'typescript': return files.includes('tsconfig.json');
+      case 'rust':       return files.includes('Cargo.toml');
+      default:           return false;
+    }
+  } catch { return false; }
+}
+
+function checkProjectMap(cwd) {
+  try {
+    const counts = quickFileCount(cwd, { max: 5000 });
+    if (!counts.total) return { status: 'warn', label: 'Project map  no files indexed yet' };
+    const langs = topLanguages(counts.byExt, 2);
+    const langStr = langs.length ? langs.join(' + ') : 'mixed';
+    return { status: 'ok', label: `Project map  ${counts.total} files, ${langStr}` };
+  } catch {
+    return { status: 'warn', label: 'Project map  unreadable' };
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function shorten(s, n) {
+  const str = String(s || '');
+  return str.length <= n ? str : str.slice(0, n - 1) + '…';
+}
+
+function hasGitDir(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+function which(name) {
+  try {
+    execSync(`command -v ${name}`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return true;
+  } catch { return false; }
+}
+
+function ping(url, timeoutMs) {
+  return new Promise((resolve) => {
+    let u;
+    try { u = new URL(url); } catch { resolve(false); return; }
+    const lib = u.protocol === 'https:' ? https : http;
+    const req = lib.request({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname || '/',
+      method: 'GET',
+      timeout: timeoutMs,
+    }, (res) => {
+      // Any response means the host is reachable, even 404.
+      res.resume();
+      resolve(true);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { try { req.destroy(); } catch {} resolve(false); });
+    req.end();
+  });
+}
+
+const EXT_TO_LANG = {
+  '.py': 'Python', '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript',
+  '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.go': 'Go', '.rs': 'Rust',
+  '.java': 'Java', '.rb': 'Ruby', '.php': 'PHP', '.swift': 'Swift', '.kt': 'Kotlin',
+  '.c': 'C', '.cc': 'C++', '.cpp': 'C++', '.h': 'C/C++', '.hpp': 'C++',
+};
+
+function topLanguages(byExt, n) {
+  const ranked = Object.entries(byExt)
+    .map(([ext, count]) => [EXT_TO_LANG[ext], count])
+    .filter(([lang]) => lang)
+    .reduce((acc, [lang, count]) => { acc.set(lang, (acc.get(lang) || 0) + count); return acc; }, new Map());
+  return [...ranked.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([lang]) => lang);
+}
+
+function quickFileCount(cwd, { max = 5000 } = {}) {
+  // Shallow walk: skip node_modules, .git, dist, build, .venv, __pycache__.
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.venv', 'venv', '__pycache__', '.kepler', '.terraform']);
+  const byExt = {};
+  let total = 0;
+  const stack = [cwd];
+  while (stack.length && total < max) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.kepler') continue;
+      if (SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile()) {
+        total++;
+        const ext = path.extname(e.name).toLowerCase();
+        if (ext) byExt[ext] = (byExt[ext] || 0) + 1;
+        if (total >= max) break;
+      }
+    }
+  }
+  return { total, byExt };
+}
+
+// ── Renderer ────────────────────────────────────────────────────────────
+
+function formatRow(check) {
+  switch (check.status) {
+    case 'ok':   return `  ${OK(paint.text.primary(check.label))}`;
+    case 'warn': return `  ${WARN(paint.text.primary(check.label))}` +
+                        (check.hint ? `  ${paint.text.dim('→ ' + check.hint)}` : '');
+    case 'fail': return `  ${FAIL(paint.text.primary(check.label))}` +
+                        (check.hint ? `  ${paint.text.dim('→ ' + check.hint)}` : '');
+    default:     return `  ${paint.text.dim(check.label)}`;
+  }
+}
+
+/**
+ * Run the preflight diagnostic. Writes to stderr and resolves with the
+ * collected check results.
+ *
+ * @param {object} opts
+ * @param {object} opts.auth        — TarangAuth instance
+ * @param {string} opts.cwd         — working directory
+ * @param {string} opts.version     — package version string
+ * @param {boolean} [opts.silent]   — if true, do not write (useful for tests)
+ */
+export async function runPreflight({ auth, cwd, version, silent = false } = {}) {
+  const t = term();
+  const write = (s) => { if (!silent) process.stderr.write(s); };
+
+  const header = `${icons.search} ${paint.bold(paint.brand.primary('Kepler v' + (version || '?')))} ${paint.text.dim('· initializing orbit')}`;
+  write('\n' + header + '\n\n');
+
+  const checks = [];
+  checks.push(await checkAuthAndBackend(auth));
+  checks.push(checkGit(cwd));
+  checks.push(checkLinters(cwd));
+  checks.push(checkProjectMap(cwd));
+
+  for (const c of checks) write(formatRow(c) + '\n');
+
+  const fails = checks.filter(c => c.status === 'fail').length;
+  const warns = checks.filter(c => c.status === 'warn').length;
+  const tail = fails === 0 && warns === 0
+    ? paint.state.success('All systems aligned.')
+    : fails > 0
+        ? paint.state.danger(`${fails} blocker${fails === 1 ? '' : 's'}, ${warns} warning${warns === 1 ? '' : 's'} — see hints above.`)
+        : paint.state.warn(`${warns} warning${warns === 1 ? '' : 's'} — non-blocking.`);
+
+  write('\n  ' + tail + '\n\n');
+  return checks;
+}

package/src/state/orbit.mjs

@@ -0,0 +1,263 @@
+/**
+ * Orbit state machine — Mission Control (PRD-055 §5.2).
+ *
+ * The "orbit" is the current phase of the session. The status bar reads
+ * from this module; the REPL pushes events into it. It is intentionally a
+ * pure state machine — no I/O, no side effects, no globals. Each REPL
+ * creates one instance.
+ *
+ *   const orbit = createOrbit();
+ *   orbit.on('change', state => statusBar.render(state));
+ *   orbit.onEvent({ type: 'tool_call', data: { tool: 'edit_file' } });
+ *
+ * States (PRD §5.2):
+ *   IDLE        — waiting for user input
+ *   DISCOVERY   — first message until first plan or edit
+ *   PLANNING    — preflight plan running OR plan() sub-agent active
+ *   EXECUTION   — write/edit/shell tools firing
+ *   ALIGNMENT   — tests / validators running
+ *   AWAITING    — approval required
+ *   PAUSED      — user pressed `p`
+ *
+ * Transitions are derived from existing backend SSE events. We never
+ * teach the backend about orbits; the CLI infers them from tool activity.
+ */
+
+// Tool families used for orbit inference. Mirrors src/ui/icons.mjs but
+// scoped to the few orbits actually need.
+const PLANNING_TOOLS = new Set(['plan']);
+const EXECUTION_TOOLS = new Set(['edit_file', 'write_file', 'write_project', 'shell', 'delete_file']);
+const ALIGNMENT_TOOLS = new Set(['run_tests', 'validate_build', 'lint_check', 'validate_file', 'validate_structure', 'git_diff', 'git_status']);
+const RESEARCH_TOOLS  = new Set(['search_code', 'search_files', 'grep', 'read_file', 'read_files', 'list_files', 'analyze_code', 'get_project_overview', 'explore']);
+
+export const ORBITS = Object.freeze({
+  IDLE:      'IDLE',
+  DISCOVERY: 'DISCOVERY',
+  PLANNING:  'PLANNING',
+  EXECUTION: 'EXECUTION',
+  ALIGNMENT: 'ALIGNMENT',
+  AWAITING:  'AWAITING',
+  PAUSED:    'PAUSED',
+});
+
+/**
+ * @returns the snapshot consumed by the status bar.
+ */
+function snapshot(s) {
+  return {
+    orbit:           s.orbit,
+    task:            s.task || '',
+    turn:            s.turn,
+    maxTurn:         s.maxTurn,
+    cost:            s.cost,
+    activeTool:      s.activeTool || '',
+    subAgents:       s.subAgents,
+    paused:          s.paused,
+    awaitingTier:    s.awaitingTier || null,
+    awaitingTool:    s.awaitingTool || '',
+  };
+}
+
+export function createOrbit() {
+  const state = {
+    orbit:        ORBITS.IDLE,
+    task:         '',
+    turn:         0,
+    maxTurn:      0,
+    cost:         0,
+    activeTool:   '',
+    subAgents:    0,           // count of currently-active sub-agents
+    paused:       false,
+    awaitingTool: '',
+    awaitingTier: null,
+    _hasEdited:   false,       // for DISCOVERY → EXECUTION transition
+    _resumeOrbit: null,        // remembered orbit when paused
+  };
+
+  const listeners = new Set();
+
+  function emit() {
+    const snap = snapshot(state);
+    for (const fn of listeners) {
+      try { fn(snap); } catch {}
+    }
+  }
+
+  function setOrbit(next) {
+    if (state.paused && next !== ORBITS.PAUSED && next !== ORBITS.IDLE) {
+      // While paused, remember the orbit that would have applied but stay paused.
+      state._resumeOrbit = next;
+      return;
+    }
+    if (state.orbit === next) return;
+    state.orbit = next;
+    emit();
+  }
+
+  function inferOrbitFromTool(toolName) {
+    if (state.paused) return null;
+    if (state.subAgents > 0 && PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (EXECUTION_TOOLS.has(toolName)) {
+      state._hasEdited = true;
+      return ORBITS.EXECUTION;
+    }
+    if (ALIGNMENT_TOOLS.has(toolName)) return ORBITS.ALIGNMENT;
+    if (RESEARCH_TOOLS.has(toolName)) {
+      // Stay in DISCOVERY until first edit; afterwards research stays in
+      // current orbit (EXECUTION) so the status doesn't flicker back.
+      return state._hasEdited ? null : ORBITS.DISCOVERY;
+    }
+    return null;
+  }
+
+  return {
+    state: () => snapshot(state),
+
+    on(event, fn) {
+      if (event !== 'change') return () => {};
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+
+    // ── Inbound events from the REPL ──────────────────────────────────
+
+    onUserInput(text) {
+      // First user message of the session OR a new turn opens DISCOVERY.
+      state.turn++;
+      state.task = (text || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+      state._hasEdited = false;
+      state.activeTool = '';
+      setOrbit(ORBITS.DISCOVERY);
+    },
+
+    onMaxTurn(n) {
+      if (typeof n === 'number' && n > 0) {
+        state.maxTurn = n;
+        emit();
+      }
+    },
+
+    onTask(text) {
+      if (!text) return;
+      state.task = String(text).replace(/\s+/g, ' ').trim().slice(0, 80);
+      emit();
+    },
+
+    onCost(value) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        state.cost = value;
+        emit();
+      }
+    },
+
+    onToolCall(toolName) {
+      state.activeTool = toolName || '';
+      const next = inferOrbitFromTool(toolName);
+      if (next) setOrbit(next);
+      else emit();
+    },
+
+    onToolResult() {
+      state.activeTool = '';
+      emit();
+    },
+
+    onSubAgentStart() {
+      state.subAgents = Math.max(0, state.subAgents) + 1;
+      setOrbit(ORBITS.PLANNING);
+    },
+
+    onSubAgentEnd() {
+      state.subAgents = Math.max(0, state.subAgents - 1);
+      // Fall back to whatever the parent was doing — we don't track that
+      // precisely, so go to EXECUTION if an edit has happened, else
+      // DISCOVERY. The next tool_call event will refine.
+      if (state.subAgents === 0) {
+        setOrbit(state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      } else {
+        emit();
+      }
+    },
+
+    onApprovalRequired({ tool, tier } = {}) {
+      state.awaitingTool = tool || '';
+      state.awaitingTier = tier || null;
+      setOrbit(ORBITS.AWAITING);
+    },
+
+    onApprovalResolved() {
+      state.awaitingTool = '';
+      state.awaitingTier = null;
+      // Drop back to the inferred orbit for the active tool, or EXECUTION
+      // if we have an active tool but can't classify, or IDLE.
+      const inferred = inferOrbitFromTool(state.activeTool) || (state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      setOrbit(inferred);
+    },
+
+    onComplete({ cost } = {}) {
+      if (typeof cost === 'number') state.cost = cost;
+      state.activeTool = '';
+      setOrbit(ORBITS.IDLE);
+    },
+
+    onPause() {
+      if (state.paused) return;
+      state.paused = true;
+      state._resumeOrbit = state.orbit;
+      state.orbit = ORBITS.PAUSED;
+      emit();
+    },
+
+    onResume() {
+      if (!state.paused) return;
+      state.paused = false;
+      const resume = state._resumeOrbit || ORBITS.IDLE;
+      state._resumeOrbit = null;
+      state.orbit = resume;
+      emit();
+    },
+
+    /**
+     * Generic event router so the REPL can feed raw SSE events without a
+     * giant switch in this module. Returns true if the event was handled.
+     */
+    onEvent(event) {
+      if (!event || !event.type) return false;
+      const { type, data } = event;
+      switch (type) {
+        case 'tool_call':
+        case 'tool_request':
+          this.onToolCall(data?.tool || '');
+          return true;
+        case 'tool_result':
+        case 'tool_done':
+          this.onToolResult();
+          return true;
+        case 'sub_agent_start':
+          this.onSubAgentStart();
+          return true;
+        case 'sub_agent_complete':
+          this.onSubAgentEnd();
+          return true;
+        case 'approval_required':
+          this.onApprovalRequired({ tool: data?.tool, tier: data?.tier });
+          return true;
+        case 'approval_granted':
+        case 'approval_denied':
+          this.onApprovalResolved();
+          return true;
+        case 'complete': {
+          const usage = data?.usage || {};
+          this.onComplete({ cost: usage.total_cost_usd ?? usage.cost_usd });
+          return true;
+        }
+        case 'plan_created':
+          this.onTask(data?.title || data?.task || '');
+          return true;
+        default:
+          return false;
+      }
+    },
+  };
+}

package/src/state/verbosity.mjs

@@ -0,0 +1,99 @@
+/**
+ * Verbosity modes — Mission Control (PRD-055 §12).
+ *
+ *   quiet     Folded summary only. Sub-agent inner tools hidden.
+ *   default   Folded summary. Sub-agent header shown, inner tools folded.
+ *   verbose   Folded summary. Sub-agent inner tools shown.
+ *   surgical  Expanded tool details + raw model reasoning.
+ *
+ * Persisted to `~/.kepler/config.json` under the `verbosity` key so the
+ * choice survives across sessions.
+ *
+ *   import { getVerbosity, setVerbosity, showSubAgentTools, showReasoning } from './verbosity.mjs';
+ *
+ * No imports from the REPL — this module is pure state + filesystem.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const MODES = Object.freeze({
+  QUIET:    'quiet',
+  DEFAULT:  'default',
+  VERBOSE:  'verbose',
+  SURGICAL: 'surgical',
+});
+
+const VALID = new Set(Object.values(MODES));
+
+const CONFIG_DIR = process.env.KEPLER_HOME || path.join(os.homedir(), '.kepler');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+let _cached = null;
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
+  catch { return {}; }
+}
+
+function writeConfig(obj) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(obj, null, 2));
+  } catch { /* best effort */ }
+}
+
+/** Read the current mode (falls back to default). */
+export function getVerbosity() {
+  if (_cached) return _cached;
+  const v = readConfig().verbosity;
+  _cached = VALID.has(v) ? v : MODES.DEFAULT;
+  return _cached;
+}
+
+/** Update the persisted mode. Returns the new mode. */
+export function setVerbosity(mode) {
+  if (!VALID.has(mode)) throw new Error(`Unknown verbosity mode: ${mode}`);
+  const cfg = readConfig();
+  cfg.verbosity = mode;
+  writeConfig(cfg);
+  _cached = mode;
+  return mode;
+}
+
+/** Force-reload from disk (used by tests). */
+export function _resetCache() { _cached = null; }
+
+// ── Predicates — let other modules ask "should I render X?" ─────────────
+
+/** Should sub-agent inner tool cards be printed? */
+export function showSubAgentTools(mode = getVerbosity()) {
+  return mode === MODES.VERBOSE || mode === MODES.SURGICAL;
+}
+
+/** Should raw model reasoning be printed? */
+export function showReasoning(mode = getVerbosity()) {
+  return mode === MODES.SURGICAL;
+}
+
+/** Should tool cards default to expanded instead of folded? */
+export function defaultExpanded(mode = getVerbosity()) {
+  return mode === MODES.SURGICAL;
+}
+
+/** Should markdown be rendered? (only `surgical` shows raw, others render) */
+export function renderMarkdown(mode = getVerbosity()) {
+  return mode !== MODES.SURGICAL;
+}
+
+/** Per-mode label for /help and status display. */
+export function label(mode = getVerbosity()) {
+  switch (mode) {
+    case MODES.QUIET:    return 'quiet (compact)';
+    case MODES.DEFAULT:  return 'default';
+    case MODES.VERBOSE:  return 'verbose (sub-agent tools visible)';
+    case MODES.SURGICAL: return 'surgical (everything shown)';
+    default:             return String(mode || 'default');
+  }
+}