amicus 1.9.1 → 2.1.0

package/src/utils/cli-preflight.js

@@ -0,0 +1,43 @@
+/**
+ * @module cli-preflight
+ * Tiny shared preflight guards used by more than one CLI run handler
+ * (start/resume/continue/fanout), split out so each handler file can stay
+ * under the size gate without duplicating the same few lines.
+ */
+
+'use strict';
+
+const { failJson, ERROR_CODES } = require('./error-doc');
+const { validateTaskId } = require('./validators');
+
+/** Shared --json requires --no-ui gate. Exits (never returns) on violation. */
+function requireNoUiForJson(args, useJson) {
+  if (args.json && !args['no-ui']) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --json requires --no-ui' }));
+  }
+}
+
+/**
+ * Shared task-id presence + format check. Exits (never returns) on violation.
+ * @param {object} args - parsed CLI args (positional task id at args._[1])
+ * @param {boolean} useJson
+ * @param {string} commandLabel - e.g. 'resume', 'continue'
+ * @param {string} [usage] - appended to the missing-id message
+ * @returns {string} the validated task id
+ */
+function requireValidTaskId(args, useJson, commandLabel, usage) {
+  const taskId = args._[1];
+  if (!taskId) {
+    process.exit(failJson(useJson, {
+      code: ERROR_CODES.BAD_SESSION,
+      message: `Error: task_id is required for ${commandLabel}${usage ? `\n${usage}` : ''}`,
+    }));
+  }
+  const check = validateTaskId(taskId);
+  if (!check.valid) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
+  }
+  return taskId;
+}
+
+module.exports = { requireNoUiForJson, requireValidTaskId };

package/src/utils/config.js

@@ -9,15 +9,17 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { applyDirectApiFallback, autoRepairAlias } = require('./alias-resolver');
-const { getCompatEnv } = require('./env-compat');
 
 /** Default model alias map — derived from the curated-models single source (F5) */
 const { toDefaultAliases } = require('./curated-models');
 const DEFAULT_ALIASES = toDefaultAliases();
 
+/** Built-in council benches (B23) — consulted only when a name is absent from user config. */
+const { resolveBuiltinCouncil } = require('./council-presets');
+
 /** @returns {string} Config directory path */
 function getConfigDir() {
-  const override = getCompatEnv('CONFIG_DIR');
+  const override = process.env.AMICUS_CONFIG_DIR;
   if (override) {
     const resolved = path.resolve(override);
     if (resolved.includes('\0')) {
@@ -26,45 +28,7 @@ function getConfigDir() {
     return resolved;
   }
   const homeDir = process.env.HOME || process.env.USERPROFILE;
-  const amicusDir = path.join(homeDir, '.config', 'amicus');
-  // DEPRECATED(amicus-shim): fall back to the legacy ~/.config/sidecar dir if it
-  // exists and the new one does not, so pre-rebrand credentials keep working.
-  // Remove in a future revision — see docs/SHIMS.md.
-  if (!fs.existsSync(amicusDir)) {
-    const legacyDir = path.join(homeDir, '.config', 'sidecar');
-    if (fs.existsSync(legacyDir)) {
-      return legacyDir;
-    }
-  }
-  return amicusDir;
-}
-
-/**
- * One-time, non-destructive migration of the legacy ~/.config/sidecar config
- * directory onto the canonical ~/.config/amicus. Copies (does not move), so the
- * legacy dir is left intact as a backup. This collapses the two-dir split that
- * let getConfigDir() flip between them and orphan data: once ~/.config/amicus
- * exists it always wins. No-op when amicus already exists, when there is no
- * legacy dir, or when a CONFIG_DIR override is set. Best-effort — returns a
- * result object and never throws. Call once at startup, before any config read.
- *
- * @param {{home?: string}} [opts]
- * @returns {{migrated: boolean, from?: string, to?: string, reason?: string, error?: string}}
- */
-function migrateLegacyConfigDir(opts = {}) {
-  if (getCompatEnv('CONFIG_DIR')) { return { migrated: false, reason: 'override-set' }; }
-  const home = opts.home || process.env.HOME || process.env.USERPROFILE;
-  if (!home) { return { migrated: false, reason: 'no-home' }; }
-  const amicusDir = path.join(home, '.config', 'amicus');
-  const legacyDir = path.join(home, '.config', 'sidecar');
-  try {
-    if (fs.existsSync(amicusDir)) { return { migrated: false, reason: 'amicus-exists' }; }
-    if (!fs.existsSync(legacyDir)) { return { migrated: false, reason: 'no-legacy' }; }
-    fs.cpSync(legacyDir, amicusDir, { recursive: true });
-    return { migrated: true, from: legacyDir, to: amicusDir };
-  } catch (err) {
-    return { migrated: false, reason: 'error', error: err.message };
-  }
+  return path.join(homeDir, '.config', 'amicus');
 }
 
 /** @returns {string} Full path to config.json */
@@ -312,6 +276,24 @@ function getCouncil(name) {
   return getCouncils()[name] || null;
 }
 
+/**
+ * Look up a council's raw member list, checking user config FIRST and the
+ * built-in benches (free/budget/frontier — src/utils/council-presets.js)
+ * only when the name is absent from user config. User config always shadows
+ * a same-named built-in — this matches the pre-existing last-write-wins
+ * posture the wizard's `councils.free` seeding already relied on.
+ * @param {string} name
+ * @param {Array<{id:string}>} [catalog] needed only to resolve the dynamic 'free' bench
+ * @returns {{members:string[]|null, builtin:boolean}}
+ */
+function getCouncilWithSource(name, catalog = []) {
+  const userMembers = getCouncil(name);
+  if (userMembers) { return { members: userMembers, builtin: false }; }
+  const builtinMembers = resolveBuiltinCouncil(name, catalog);
+  if (builtinMembers) { return { members: builtinMembers, builtin: true }; }
+  return { members: null, builtin: false };
+}
+
 /**
  * Expand a saved council into a runnable members list, degrading gracefully.
  * Each member is resolved to its full model id (alias → id via effective
@@ -320,12 +302,17 @@ function getCouncil(name) {
  * warning rather than fail-fast-aborting the whole wave. The catalog check is
  * skipped when the catalog is empty (offline). Returns members RAW (alias or
  * id) — leg-time validation resolves them again.
+ *
+ * Resolution order: user config (`config.councils`) is checked first; when
+ * `name` is absent there, the built-in benches (`free`/`budget`/`frontier`)
+ * are consulted (src/utils/council-presets.js). A user-saved council always
+ * shadows a built-in of the same name.
  * @param {string} name
  * @param {Array<{id:string}>} [catalog]
  * @returns {{models:string[], dropped:string[]} | {error:string}}
  */
 function resolveCouncilMembers(name, catalog = []) {
-  const members = getCouncil(name);
+  const { members } = getCouncilWithSource(name, catalog);
   if (!members) {
     return { error: `Unknown council '${name}'. Run 'amicus setup' to create one.` };
   }
@@ -354,7 +341,6 @@ function resolveCouncilMembers(name, catalog = []) {
 
 module.exports = {
   getConfigDir,
-  migrateLegacyConfigDir,
   getConfigPath,
   loadConfig,
   saveConfig,
@@ -370,5 +356,6 @@ module.exports = {
   buildProviderModels,
   getCouncils,
   getCouncil,
+  getCouncilWithSource,
   resolveCouncilMembers,
 };

package/src/utils/council-presets.js

@@ -0,0 +1,87 @@
+/**
+ * Built-in council benches (B23).
+ *
+ * `resolveCouncilMembers` (src/utils/config.js) consults this table ONLY when
+ * the requested name is absent from user config (`config.councils`) — user
+ * config always shadows a built-in of the same name. This preserves today's
+ * behavior for the wizard-seeded `councils.free` (src/sidecar/setup.js
+ * seedFreeCouncil): once seeded, the user's `free` list wins over the
+ * built-in dynamic free bench below.
+ *
+ * Two shapes:
+ *   - 'free' is DYNAMIC: resolved at use time from the live catalog via
+ *     suggestFreeCouncil (one :free model per vendor), falling back to the
+ *     offline PINNED_FREE_MODELS when the catalog has no free rows. This
+ *     mirrors the wizard's own free-council derivation so the built-in and
+ *     the wizard-seeded version pick the same kind of members.
+ *   - 'budget' and 'frontier' are STATIC: three DEFAULT_ALIASES entries
+ *     (src/utils/curated-models.js) each, chosen by catalog pricing at
+ *     implementation time (see docs/CHANGELOG or the task report for the
+ *     pricing evidence). Alias-based so `amicus models --check` drift
+ *     tooling and normal alias resolution keep them healthy for free —
+ *     no raw model ids are hardcoded here.
+ */
+'use strict';
+
+const { suggestFreeCouncil, PINNED_FREE_MODELS } = require('./free-models');
+
+/**
+ * Budget bench: three cheapest DEFAULT_ALIASES entries, one per vendor
+ * family, verified against the cached catalog (~/.config/amicus/model-catalog.json)
+ * on 2026-07-02 (prices are $/token, prompt+completion):
+ *   minimax     openrouter/minimax/minimax-m2.7      $0.00000018 / $0.00000072
+ *   qwen-coder  openrouter/qwen/qwen3-coder-next     $0.00000011 / $0.0000008
+ *   deepseek    openrouter/deepseek/deepseek-v4-pro  $0.000000435 / $0.00000087
+ * These are the three lowest total (prompt+completion) prices in
+ * DEFAULT_ALIASES, and each is a distinct vendor family (MiniMax / Qwen /
+ * DeepSeek) — the qwen-flash entry (also cheap) was skipped to keep vendor
+ * diversity across the bench.
+ */
+const BUDGET_ALIASES = ['minimax', 'qwen-coder', 'deepseek'];
+
+/**
+ * Frontier bench: three premium-flagship DEFAULT_ALIASES entries, one per
+ * vendor family, verified against the same catalog snapshot:
+ *   gpt-pro     openrouter/openai/gpt-5.5-pro          $0.00003 / $0.00018
+ *   opus        openrouter/anthropic/claude-opus-4.8   $0.000005 / $0.000025
+ *   gemini-pro  openrouter/google/gemini-3.1-pro-preview  $0.000002 / $0.000012
+ * These are the three highest total (prompt+completion) prices in
+ * DEFAULT_ALIASES that are also each a distinct vendor family (OpenAI /
+ * Anthropic / Google) — `gpt` and `codex` (also OpenAI) and `claude`/`sonnet`
+ * (also Anthropic) were skipped as same-family duplicates of the pick above.
+ */
+const FRONTIER_ALIASES = ['gpt-pro', 'opus', 'gemini-pro'];
+
+/**
+ * @param {Array} catalog live model-catalog rows (for the dynamic free bench)
+ * @returns {string[]} council members (aliases or full ids), possibly empty
+ */
+function resolveFreeBench(catalog) {
+  const picks = suggestFreeCouncil(Array.isArray(catalog) ? catalog : []);
+  if (picks.length > 0) { return picks.map(p => p.id); }
+  return [...PINNED_FREE_MODELS];
+}
+
+/**
+ * @param {string} name
+ * @param {Array} [catalog] live model-catalog rows, needed only for 'free'
+ * @returns {string[]|null} resolved built-in members, or null if `name` is not a built-in
+ */
+function resolveBuiltinCouncil(name, catalog = []) {
+  if (name === 'free') { return resolveFreeBench(catalog); }
+  if (name === 'budget') { return [...BUDGET_ALIASES]; }
+  if (name === 'frontier') { return [...FRONTIER_ALIASES]; }
+  return null;
+}
+
+/** @returns {string[]} built-in bench names, in resolution-doc order */
+function listBuiltinCouncilNames() {
+  return ['free', 'budget', 'frontier'];
+}
+
+module.exports = {
+  BUDGET_ALIASES,
+  FRONTIER_ALIASES,
+  resolveBuiltinCouncil,
+  listBuiltinCouncilNames,
+};

package/src/utils/doctor-mcp-checks.js

@@ -0,0 +1,84 @@
+/**
+ * @module doctor-mcp-checks
+ * B14/Task 4.3: the two MCP-registration doctor checks ('mcp' and
+ * 'mcp-legacy'), split out of src/cli-handlers-doctor.js to keep that file
+ * under the 300-line size gate (mirrors how session-index-tmp-sweep.js holds
+ * the B15 sweep's evaluate* composer — src/cli-handlers-doctor.js just wraps
+ * these in guard() the same way).
+ *
+ * 'mcp' (evaluateMcpRegistration): PRIMARY signal is
+ * d.hasAmicusRegistration() — a RAW (unstripped) read of the same Claude
+ * Code sources discoverClaudeCodeMcps reads. discoverClaudeCodeMcps always
+ * strips every 'amicus'/'sidecar'-shaped entry as its own recursive-spawn
+ * guard (src/utils/mcp-self-identity.js), so testing `code.amicus` here
+ * would ALWAYS be false — that was the B14 false-negative. Cowork/Desktop
+ * discovery (d.discoverCoworkMcps) does not strip and stays a bonus signal.
+ *
+ * 'mcp-legacy' (evaluateLegacyMcpEntry): unchanged logic, moved verbatim.
+ */
+
+'use strict';
+
+const HINTS = require('./remediation-hints');
+
+/**
+ * @param {{hasAmicusRegistration: () => boolean, discoverCoworkMcps: () => object|null}} d
+ */
+function evaluateMcpRegistration(d) {
+  const id = 'mcp'; const name = 'MCP registration';
+  const inCode = !!d.hasAmicusRegistration();
+  const cowork = d.discoverCoworkMcps();
+  const inCowork = !!(cowork && cowork.amicus);
+  // Primary signal: Claude Code MCP registration. Cowork/Desktop is reported as bonus only.
+  if (!inCode) {
+    return { id, name, status: 'warn', message: 'not registered in Claude Code', hint: `${HINTS.reinstall}  (or install the amicus plugin)` };
+  }
+  const extra = inCowork ? ', Cowork/Desktop' : '';
+  return { id, name, status: 'ok', message: `registered: Claude Code${extra}`, hint: null };
+}
+
+/**
+ * Duplicate legacy 'sidecar' MCP registration (same server twice — doubles
+ * the client-visible tool list). Detection reads the raw config files via
+ * legacy-mcp-migration: mcp-discovery can't see it (it strips 'sidecar' as
+ * its own recursion guard). --fix removes only identical-in-effect twins.
+ * @param {{inspectLegacyMcpEntries: () => Array, fix?: boolean, migrateLegacyMcpEntries: () => Array}} d
+ */
+function evaluateLegacyMcpEntry(d) {
+  const id = 'mcp-legacy'; const name = 'Legacy sidecar MCP entry';
+  const entries = d.inspectLegacyMcpEntries() || [];
+  const dupes = entries.filter(e => e.status === 'removable');
+  const custom = entries.filter(e => e.status === 'customized');
+  // An unreadable config is neither "no problem" nor a duplicate we can act
+  // on — reporting it as ok/'none' would hide a config doctor (and --fix)
+  // could not actually inspect. Always surface it, even alongside dupes.
+  const unreadable = entries.filter(e => e.status === 'unreadable');
+  const unreadableNote = unreadable.length
+    ? `${unreadable.map(e => e.target).join(', ')} config unreadable — skipped`
+    : null;
+  if (dupes.length === 0) {
+    if (unreadableNote) {
+      const suffix = custom.length ? `; custom 'sidecar' entry in ${custom.map(e => e.target).join(', ')} — left alone` : '';
+      return { id, name, status: 'warn', message: `${unreadableNote}${suffix}`, hint: null };
+    }
+    const message = custom.length
+      ? `custom 'sidecar' entry in ${custom.map(e => e.target).join(', ')} — left alone`
+      : 'none';
+    return { id, name, status: 'ok', message, hint: null };
+  }
+  if (d.fix) {
+    const removed = (d.migrateLegacyMcpEntries() || []).filter(r => r.result === 'removed');
+    if (removed.length >= dupes.length) {
+      const message = `removed legacy entry from: ${removed.map(r => r.target).join(', ')}`;
+      return unreadableNote
+        ? { id, name, status: 'warn', message: `${message}; ${unreadableNote}`, hint: HINTS.removeLegacySidecar }
+        : { id, name, status: 'ok', message, hint: null };
+    }
+    const message = `removed ${removed.length}/${dupes.length} duplicate(s) — could not update every config`;
+    return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
+  }
+  const message = `duplicate 'sidecar' entry in ${dupes.map(e => e.target).join(', ')} — doubles the MCP tool list`;
+  return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
+}
+
+module.exports = { evaluateMcpRegistration, evaluateLegacyMcpEntry };

package/src/utils/env-loader.js

@@ -16,11 +16,10 @@ const { readAuthJsonKeys } = require('./auth-json');
  * Sources (in priority order):
  * 1. process.env - already set, never overwritten
  * 2. ~/.config/amicus/.env - user-configured via `amicus setup`
- *    (DEPRECATED(amicus-shim): falls back to ~/.config/sidecar/.env if the amicus .env absent)
  * 3. ~/.local/share/opencode/auth.json - OpenCode SDK fallback
  */
 function loadCredentials() {
-  // Step 1: Load from sidecar .env file
+  // Step 1: Load from amicus .env file
   const fileEntries = loadEnvEntries();
   for (const [, envVar] of Object.entries(PROVIDER_ENV_MAP)) {
     if (!process.env[envVar]) {

package/src/utils/fold-marker.js

@@ -0,0 +1,79 @@
+/**
+ * Fold marker construction/parsing helpers — shared by prompt-builder.js
+ * (instructs the model), headless.js (writes + detects), electron/fold.js
+ * (writes), and src/sidecar/resume.js (re-derives the nonce from a saved
+ * prompt on resume). Centralized here so the marker CONTRACT lives in one
+ * place instead of being duplicated string-literal by string-literal.
+ *
+ * #BL-7 residual: the marker used to be the static string `[SIDECAR_FOLD]`,
+ * so model output that genuinely ends with a bare marker (echoing these
+ * instructions, a prior sidecar summary, or scraped content) could force a
+ * premature fold. A per-run nonce closes that gap — only the exact nonce
+ * generated for THIS run completes THIS run.
+ */
+const crypto = require('crypto');
+
+/** The fixed, public prefix. Intentionally still `[SIDECAR_FOLD` as a
+ *  substring — anything that greps for the OLD literal string still finds
+ *  the new nonced marker; it just no longer matches an ANCHORED bare-bracket
+ *  string (`[SIDECAR_FOLD]`) because a real marker now always carries a
+ *  `:<nonce>` suffix before the closing bracket. */
+const FOLD_MARKER_PREFIX = 'SIDECAR_FOLD';
+
+/** Generate a fresh per-run nonce. 16 hex chars (8 random bytes) — comfortably
+ *  above the brief's 12+ hex char floor, cheap to embed in prompts. */
+function generateFoldNonce() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Build the full marker string for a given nonce: `[SIDECAR_FOLD:<nonce>]`.
+ * @param {string} nonce
+ * @returns {string}
+ */
+function buildFoldMarker(nonce) {
+  return `[${FOLD_MARKER_PREFIX}:${nonce}]`;
+}
+
+/** Escape a string for safe embedding inside a RegExp source. */
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build a RegExp that matches `buildFoldMarker(nonce)` as the FINAL
+ * non-empty line of a string (see headless.js findTrailingFoldMarker for the
+ * consuming semantics). Exported so headless.js doesn't hand-roll the same
+ * escaping logic.
+ * @param {string} nonce
+ * @returns {RegExp}
+ */
+function trailingFoldMarkerRegex(nonce) {
+  const escaped = escapeRegExp(buildFoldMarker(nonce));
+  return new RegExp(`^[^\\S\\r\\n]*${escaped}[^\\S\\r\\n]*$(?![\\s\\S]*\\S)`, 'm');
+}
+
+/**
+ * Recover the nonce embedded in a previously-built system prompt (resume.js:
+ * a resumed session re-sends the ORIGINAL prompt text — which already
+ * instructs the model with the nonce baked in at initial `start`/`continue`
+ * time — rather than building a fresh one via buildPrompts). Matches the
+ * FIRST occurrence of the marker anywhere in the text (the prompt's own
+ * instruction line), not a final-line match — this is prompt text, not
+ * model output.
+ * @param {string} text
+ * @returns {string|null} the nonce, or null if no marker is present
+ */
+function extractNonceFromText(text) {
+  if (!text) { return null; }
+  const m = new RegExp(`\\[${FOLD_MARKER_PREFIX}:([0-9a-f]+)\\]`).exec(text);
+  return m ? m[1] : null;
+}
+
+module.exports = {
+  FOLD_MARKER_PREFIX,
+  generateFoldNonce,
+  buildFoldMarker,
+  trailingFoldMarkerRegex,
+  extractNonceFromText,
+};

package/src/utils/idle-watchdog.js

@@ -9,16 +9,13 @@
  *
  * Timeout priority (highest to lowest):
  *   1. Per-mode env var (AMICUS_IDLE_TIMEOUT_HEADLESS, etc.) in minutes
- *      (legacy SIDECAR_IDLE_TIMEOUT_* still honored via env-compat shim)
- *   2. Blanket env var AMICUS_IDLE_TIMEOUT / SIDECAR_IDLE_TIMEOUT in minutes
+ *   2. Blanket env var AMICUS_IDLE_TIMEOUT in minutes
  *   3. Constructor option `timeout` in milliseconds
  *   4. Mode default (headless=15m, interactive=60m, server=30m)
  */
 
 'use strict';
 
-const { getCompatEnv } = require('./env-compat');
-
 /** @type {Object.<string, number>} Default timeouts per mode in milliseconds */
 const MODE_TIMEOUTS = {
   headless: 15 * 60 * 1000,
@@ -26,11 +23,11 @@ const MODE_TIMEOUTS = {
   server: 30 * 60 * 1000,
 };
 
-/** @type {Object.<string, string>} Per-mode env-compat suffixes */
+/** @type {Object.<string, string>} Per-mode env var names */
 const MODE_ENV_MAP = {
-  headless: 'IDLE_TIMEOUT_HEADLESS',
-  interactive: 'IDLE_TIMEOUT_INTERACTIVE',
-  server: 'IDLE_TIMEOUT_SERVER',
+  headless: 'AMICUS_IDLE_TIMEOUT_HEADLESS',
+  interactive: 'AMICUS_IDLE_TIMEOUT_INTERACTIVE',
+  server: 'AMICUS_IDLE_TIMEOUT_SERVER',
 };
 
 /**
@@ -41,16 +38,16 @@ const MODE_ENV_MAP = {
  * @returns {number} Effective timeout in ms, or Infinity if disabled
  */
 function resolveTimeout(mode, optionTimeout) {
-  const modeSuffix = MODE_ENV_MAP[mode];
-  if (modeSuffix !== undefined) {
-    const modeEnv = getCompatEnv(modeSuffix);
+  const modeEnvName = MODE_ENV_MAP[mode];
+  if (modeEnvName !== undefined) {
+    const modeEnv = process.env[modeEnvName];
     if (modeEnv !== undefined) {
       const mins = Number(modeEnv);
       return mins === 0 ? Infinity : mins * 60 * 1000;
     }
   }
 
-  const blanket = getCompatEnv('IDLE_TIMEOUT');
+  const blanket = process.env.AMICUS_IDLE_TIMEOUT;
   if (blanket !== undefined) {
     const mins = Number(blanket);
     return mins === 0 ? Infinity : mins * 60 * 1000;

package/src/utils/input-validators.js

@@ -124,4 +124,55 @@ function validateStartInputs(input) {
   return { valid: true, resolvedModel: resolved };
 }
 
-module.exports = { validateStartInputs, findSimilar };
+/**
+ * Levenshtein edit distance between two strings (insertions, deletions,
+ * substitutions, each cost 1). Hand-rolled — no runtime dependency added,
+ * since fast-levenshtein is only a dev-time transitive and runtime deps are
+ * locked for this project.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshteinDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) { return n; }
+  if (n === 0) { return m; }
+
+  // Single rolling row (O(min(m,n)) space) rather than a full m×n matrix —
+  // plenty for CLI command names, which are always short.
+  let prevRow = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const currRow = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      currRow[j] = Math.min(
+        prevRow[j] + 1,      // deletion
+        currRow[j - 1] + 1,  // insertion
+        prevRow[j - 1] + cost // substitution
+      );
+    }
+    prevRow = currRow;
+  }
+  return prevRow[n];
+}
+
+/**
+ * Suggest known commands close to an unrecognized one ("did you mean").
+ * @param {string} input - the unrecognized token the user typed
+ * @param {string[]} candidates - known command names
+ * @param {number} [maxDistance=2] - inclusive distance cap
+ * @param {number} [maxSuggestions=3]
+ * @returns {string[]} candidates within maxDistance, closest first, capped
+ */
+function suggestCommand(input, candidates, maxDistance = 2, maxSuggestions = 3) {
+  if (!input) { return []; }
+  return candidates
+    .map(c => ({ c, distance: levenshteinDistance(input.toLowerCase(), c.toLowerCase()) }))
+    .filter(({ distance }) => distance <= maxDistance)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, maxSuggestions)
+    .map(({ c }) => c);
+}
+
+module.exports = { validateStartInputs, findSimilar, levenshteinDistance, suggestCommand };

package/src/utils/lifecycle.js

@@ -12,7 +12,7 @@
 // when done (F3 #15). Deliberately EXCLUDED: `mcp` (long-lived server), and
 // `setup`/`update` (no OpenCode server to leak, and `setup` can be a long-lived
 // interactive Electron flow that must never be force-exited).
-const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor' /* local-only: no OpenCode server, no stray handles */]);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'status', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor', 'spend' /* local-only: no OpenCode server, no stray handles */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {