amicus 1.1.0 → 1.2.0

package/src/sidecar/fanout.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const path = require('path');
 const { logger } = require('../utils/logger');
 const { runLeg } = require('./fanout-leg');
+const { ERROR_CODES } = require('../utils/error-doc');
 
 /** Default max legs per wave (env-overridable). */
 const DEFAULT_MAX_LEGS = 10;
@@ -48,38 +49,39 @@ function deriveLegIds(waveId, count) {
 async function validateFanoutModels(modelsArg, opts = {}) {
   const raw = parseModelsList(modelsArg);
   if (raw.length === 0) {
-    return { error: 'Error: --models requires a comma-separated list (e.g. gemini,gpt,deepseek)' };
+    return { error: 'Error: --models requires a comma-separated list (e.g. gemini,gpt,deepseek)', code: 'BAD_ARGS' };
   }
   // Invalid or non-positive AMICUS_FANOUT_MAX_LEGS (0, negative, garbage) falls back to the default.
   const envCap = Number(process.env.AMICUS_FANOUT_MAX_LEGS);
   const maxLegs = (Number.isInteger(envCap) && envCap > 0) ? envCap : DEFAULT_MAX_LEGS;
   if (raw.length > maxLegs) {
-    return { error: `Error: --models exceeds the fan-out cap of ${maxLegs} legs (set AMICUS_FANOUT_MAX_LEGS to raise)` };
+    return { error: `Error: --models exceeds the fan-out cap of ${maxLegs} legs (set AMICUS_FANOUT_MAX_LEGS to raise)`, code: 'BAD_ARGS' };
   }
 
   const { tryResolveModel } = require('../utils/config');
   const { validateApiKey } = require('../utils/validators');
   const { validateAgainstCatalog } = require('../utils/model-validator');
+  const { lookupPricing } = require('../utils/pricing');
   const legs = [];
   for (const modelInput of raw) {
     const resolved = tryResolveModel(modelInput);
     if (resolved.error) {
-      return { error: `Error: model '${modelInput}': ${resolved.error}` };
+      return { error: `Error: model '${modelInput}': ${resolved.error}`, code: 'BAD_MODEL' };
     }
     let model = resolved.model;
     const keyCheck = validateApiKey(model);
     if (!keyCheck.valid) {
-      return { error: keyCheck.error };
+      return { error: keyCheck.error, code: 'MISSING_KEY' };
     }
     if (!opts.noValidateModel) {
       const alias = modelInput.includes('/') ? undefined : modelInput;
       try {
         model = await validateAgainstCatalog(model, alias);
       } catch (err) {
-        return { error: err.message };
+        return { error: err.message, code: 'BAD_MODEL' };
       }
     }
-    legs.push({ modelInput, model });
+    legs.push({ modelInput, model, pricing: lookupPricing(model) });
   }
   return { legs };
 }
@@ -131,11 +133,36 @@ async function runFanout(options) {
     return { wave: doc, exitCode: 1 };
   };
 
+  const failPre = (code, message, hint) => {
+    if (!options.quiet) {
+      if (options.json) {
+        const { buildErrorDoc } = require('../utils/error-doc');
+        console.log(JSON.stringify(buildErrorDoc({ code, message, hint }), null, 2));
+      } else {
+        console.error(hint ? `${message}\n${hint}` : message);
+      }
+    }
+    return { wave: null, errorDoc: { code, message }, exitCode: 1 };
+  };
+
   // 1. Fail-fast validation
   const validated = await validateFanoutModels(options.models, { noValidateModel: options.noValidateModel });
-  if (validated.error) { return errorWave(options.waveId, validated.error); }
+  if (validated.error) { return failPre(validated.code || 'BAD_ARGS', validated.error); }
   const legs = validated.legs;
 
+  // 1b. Budget gate (pre-creation; refuse before spending)
+  if (!options.noCostGate) {
+    const { checkBudget, formatBudgetError } = require('./budget');
+    const { loadConfig } = require('../utils/config');
+    const cfg = loadConfig() || {};
+    const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
+    const promptChars = (options.promptMeta && options.promptMeta.chars) || (options.prompt ? options.prompt.length : 0);
+    const budget = checkBudget(legs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
+    if (!budget.ok) {
+      return failPre(ERROR_CODES.BUDGET_EXCEEDED, 'Error: budget gate refused the wave', formatBudgetError(budget));
+    }
+  }
+
   // 2. Wave record
   const waveId = options.waveId || generateTaskId();
   const legIds = deriveLegIds(waveId, legs.length);

package/src/sidecar/interactive-mirror.js

@@ -0,0 +1,66 @@
+// src/sidecar/interactive-mirror.js
+'use strict';
+
+const path = require('path');
+const { createMirrorState, mirrorMessages, logMessage } = require('./conversation-mirror');
+const { writeProgress } = require('./progress');
+const { sumPerMessageUsage } = require('../utils/pricing');
+const { logger } = require('../utils/logger');
+
+/**
+ * Poll the OpenCode session and mirror it to conversation.jsonl + progress.json
+ * live, exactly like headless. Best-effort and non-blocking — a poll/write error
+ * never throws into the GUI session.
+ *
+ * @param {object} opts
+ * @param {() => Promise<Array>} opts.getMessages
+ * @param {string} opts.sessionDir
+ * @param {number} [opts.intervalMs=2000]
+ * @param {() => void} [opts.onActivity]
+ * @param {() => string} [opts.now]
+ * @returns {{ stop: () => Promise<{usage: object|null}> }}
+ */
+function startInteractiveMirror({ getMessages, sessionDir, intervalMs = 2000, onActivity, now }) {
+  const state = createMirrorState();
+  const conversationPath = path.join(sessionDir, 'conversation.jsonl');
+  let timer = null;
+  let stopped = false;
+
+  async function pollOnce() {
+    try {
+      const messages = await getMessages();
+      const mr = mirrorMessages(messages, state, { now });
+      mr.appendLines.forEach(line => logMessage(conversationPath, line));
+      mr.progressUpdates.forEach(p => writeProgress(sessionDir, p.stage, p.extra));
+      if (mr.appendLines.length > 0 && onActivity) { onActivity(); }
+    } catch (err) {
+      logger.debug('Interactive mirror poll failed (best-effort)', { error: err.message });
+    }
+  }
+
+  const schedule = () => {
+    if (stopped) { return; }
+    timer = setTimeout(tick, intervalMs);
+    if (timer.unref) { timer.unref(); }
+  };
+  async function tick() {
+    if (stopped) { return; }
+    await pollOnce();
+    schedule();
+  }
+  schedule();
+
+  return {
+    async stop() {
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+      await pollOnce(); // final flush
+      try { writeProgress(sessionDir, 'complete'); } catch { /* best-effort */ }
+      let usage = null;
+      try { usage = sumPerMessageUsage(state.usageByMsg); } catch { /* best-effort */ }
+      return { usage };
+    },
+  };
+}
+
+module.exports = { startInteractiveMirror };

package/src/sidecar/interactive.js

@@ -7,10 +7,12 @@ const path = require('path');
 const { spawn } = require('child_process');
 
 const { startOpenCodeServer } = require('./session-utils');
-const { createSession, sendPromptAsync } = require('../opencode-client');
+const { createSession, sendPromptAsync, getMessages } = require('../opencode-client');
 const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { logger } = require('../utils/logger');
 const { getCompatEnv } = require('../utils/env-compat');
+const { startInteractiveMirror } = require('./interactive-mirror');
+const { getSessionDir } = require('../session-manager');
 
 /** Get the Electron binary path via require('electron').
  *  Works in all install contexts (global, local, npx hoisted).
@@ -151,15 +153,35 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
 
   const serverPort = new URL(server.url).port;
 
-  // Start idle watchdog for interactive mode (60-min default timeout)
+  // Start idle watchdog for interactive mode (60-min default timeout).
+  // The real teardown handler is installed BEFORE start() (closes the startup
+  // race) and references a closure that is assigned once Electron spawns.
   const { IdleWatchdog } = require('../utils/idle-watchdog');
+  const { createActivityPoller, killIfAlive } = require('../utils/activity-poller');
+  const { getSessionStatus } = require('../opencode-client');
+  let electronProcess = null;
   const watchdog = new IdleWatchdog({
     mode: 'interactive',
     onTimeout: () => {
       logger.info('Interactive idle timeout - shutting down', { taskId });
+      killIfAlive(electronProcess);
     },
   }).start();
 
+  // Keep the idle clock from killing an actively-working session: poll OpenCode
+  // session status and touch the watchdog on any non-idle (busy/retry) state.
+  const activityPoller = createActivityPoller({
+    getStatus: () => getSessionStatus(ocClient, sessionId),
+    onActivity: () => watchdog.touch(),
+  });
+
+  const sessionDir = getSessionDir(project, taskId);
+  const mirror = startInteractiveMirror({
+    getMessages: () => getMessages(ocClient, sessionId),
+    sessionDir,
+    onActivity: () => watchdog.touch(),
+  });
+
   return new Promise((resolve, _reject) => {
     const electronPath = getElectronPath();
     const mainPath = path.join(__dirname, '..', '..', 'electron', 'main.js');
@@ -170,40 +192,32 @@ async function runInteractive(model, systemPrompt, userMessage, taskId, project,
       taskId, model, project, nodeModulesBin, existingPath,
       { agent, isResume, conversation, mcp, client }
     );
-
-    // Pass OpenCode server info to Electron
     env.AMICUS_OPENCODE_PORT = serverPort;
     env.AMICUS_SESSION_ID = sessionId;
 
     const debugPort = getCompatEnv('DEBUG_PORT') || '9222';
     logger.debug('Launching Electron', { taskId, model, debugPort, serverPort, sessionId });
 
-    const electronProcess = spawn(electronPath, [
+    electronProcess = spawn(electronPath, [
       `--remote-debugging-port=${debugPort}`,
       mainPath
     ], { cwd: project, env, stdio: ['ignore', 'pipe', 'pipe'] });
 
-    // Touch watchdog on Electron stdout activity
-    electronProcess.stdout.on('data', () => {
-      watchdog.touch();
-    });
-
-    // Update watchdog onTimeout now that electronProcess is available
-    watchdog.onTimeout = () => {
-      logger.info('Interactive idle timeout - shutting down', { taskId });
-      if (!electronProcess.killed) {
-        electronProcess.kill('SIGTERM');
-      }
-    };
+    // Belt-and-suspenders: also touch on raw Electron stdout activity.
+    electronProcess.stdout.on('data', () => { watchdog.touch(); });
 
-    // Clean up server when Electron exits
-    const originalResolve = resolve;
-    handleElectronProcess(electronProcess, taskId, (result) => {
+    // Clean up server + timers when Electron exits.
+    handleElectronProcess(electronProcess, taskId, async (result) => {
       watchdog.cancel();
+      activityPoller.stop();
+      try {
+        const { usage } = await mirror.stop();
+        if (usage) { result.usage = usage; }
+      } catch (err) { logger.debug('mirror stop failed', { error: err.message }); }
       server.close();
       logger.debug('OpenCode server closed after Electron exit');
       result.opencodeSessionId = sessionId;
-      originalResolve(result);
+      resolve(result);
     });
   });
 }

package/src/sidecar/models.js

@@ -1,7 +1,7 @@
 /**
  * `amicus models` (F5) — list/search the catalog, refresh it, audit aliases.
  *
- *   amicus models                  list (curated aliases marked)
+ *   amicus models                  list (effective aliases marked)
  *   amicus models --search <q>     substring filter over id+name
  *   amicus models --refresh        force-refresh the cache
  *   amicus models --check          stale-alias audit (exit = stale count, max 100)
@@ -20,11 +20,12 @@ const { pickCurrent } = require('../utils/quick-picks');
 
 const CHECK_EXIT_CAP = 100;
 
-/** '0.000003' per token → '3.00' per Mtok; '—' when unknown */
+/** '0.000003' per token → '3.00' per Mtok; '—' when unknown or variable (-1) */
 function perMtok(perToken) {
   if (perToken === null || perToken === undefined) { return '—'; }
   const n = Number(perToken);
-  return Number.isNaN(n) ? '—' : (n * 1e6).toFixed(2);
+  if (Number.isNaN(n) || n < 0) { return '—'; }
+  return (n * 1e6).toFixed(2);
 }
 
 function fmtRow(m, aliasesById) {
@@ -36,11 +37,11 @@ function fmtRow(m, aliasesById) {
   return `${aliasCol}${m.id}\n    ${m.name}  ctx ${ctx}  $/Mtok in ${pIn} out ${pOut}`;
 }
 
-/** alias marks: id → comma-joined alias names (defaults only — the curated view) */
+/** alias marks: id → comma-joined alias names (effective user aliases) */
 function aliasMarks() {
-  const { getDefaultAliases } = require('../utils/config');
+  const { getEffectiveAliases } = require('../utils/config');
   const map = new Map();
-  for (const [alias, model] of Object.entries(getDefaultAliases())) {
+  for (const [alias, model] of Object.entries(getEffectiveAliases())) {
     map.set(model, map.has(model) ? `${map.get(model)},${alias}` : alias);
   }
   return map;
@@ -59,10 +60,10 @@ async function runList(args) {
     return 0;
   }
   const marks = aliasMarks();
-  // Curated (alias-marked) rows first, then the rest.
-  const curated = filtered.filter(m => marks.has(m.id));
+  // Effective aliases (alias-marked) rows first, then the rest.
+  const marked = filtered.filter(m => marks.has(m.id));
   const rest = filtered.filter(m => !marks.has(m.id));
-  for (const m of [...curated, ...rest]) {
+  for (const m of [...marked, ...rest]) {
     process.stdout.write(fmtRow(m, marks) + '\n');
   }
   const when = fetchedAt ? new Date(fetchedAt).toISOString() : 'never';

package/src/sidecar/session-finalize.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Map a runHeadless result to the canonical terminal status + process exit code.
+ * Single source of truth so start.js, the signal handler, and the idle backstop
+ * never disagree. Error wins over all other flags; signal callers pass the signal
+ * name for the 130/143 convention.
+ *
+ * @param {{completed?:boolean,timedOut?:boolean,aborted?:boolean,error?:any}|null} result
+ * @param {string} [signal] - 'SIGINT' | 'SIGTERM' | 'SIGBREAK' for signal aborts
+ * @returns {{status:'complete'|'error'|'timed-out'|'aborted', exitCode:number}}
+ */
+function resolveTerminalState(result, signal) {
+  if (!result || result.error) { return { status: 'error', exitCode: 1 }; }
+  if (result.aborted) {
+    const exitCode = signal === 'SIGINT' ? 130
+      : (signal === 'SIGTERM' || signal === 'SIGBREAK') ? 143
+      : 2;
+    return { status: 'aborted', exitCode };
+  }
+  if (result.timedOut) { return { status: 'timed-out', exitCode: 2 }; }
+  if (result.completed) { return { status: 'complete', exitCode: 0 }; }
+  return { status: 'error', exitCode: 1 };
+}
+
+module.exports = { resolveTerminalState };

package/src/sidecar/session-utils.js

@@ -90,12 +90,12 @@ function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
   // Save summary
   fs.writeFileSync(SessionPaths.summaryFile(sessionDir), summary, { mode: 0o600 });
 
-  // Update metadata to complete
-  metadata.status = 'complete';
+  // Update metadata to the resolved terminal status (default complete).
+  metadata.status = opts.status || 'complete';
   metadata.completedAt = new Date().toISOString();
   fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
 
-  logger.info('Session complete', { taskId: metadata.taskId });
+  logger.info('Session finalized', { taskId: metadata.taskId, status: metadata.status });
 }
 
 /** Output summary to stdout with standard formatting */
@@ -122,9 +122,9 @@ function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
     if (sessionDir) {
       const { readProgress } = require('./progress');
       const progress = readProgress(sessionDir);
-      process.stderr.write(`[sidecar] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
+      process.stderr.write(`[amicus] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
     } else {
-      process.stderr.write(`[sidecar] still running... ${ts} elapsed\n`);
+      process.stderr.write(`[amicus] still running... ${ts} elapsed\n`);
     }
   }, interval);
 

package/src/sidecar/setup.js

@@ -168,7 +168,7 @@ async function runReadlineSetup() {
 
   try {
     console.log('');
-    console.log('=== Sidecar Setup Wizard ===');
+    console.log('=== Amicus Setup Wizard ===');
     console.log('');
 
     const keys = detectApiKeys();
@@ -181,7 +181,7 @@ async function runReadlineSetup() {
       console.log(`API keys detected: ${foundKeys.join(', ')}`);
     } else {
       console.log('No API keys detected.');
-      console.log('Set OPENROUTER_API_KEY to get started, or run: sidecar setup');
+      console.log('Set OPENROUTER_API_KEY to get started, or run: amicus setup');
     }
     console.log('');
 

package/src/sidecar/start.js

@@ -218,15 +218,26 @@ async function startSidecar(options) {
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
   }
 
-  // Mark error results as 'error' instead of 'complete'
-  if (result && result.error) {
+  // Map the run result to a definitive terminal status + exit code (single source of truth).
+  const { resolveTerminalState } = require('./session-finalize');
+  const terminal = resolveTerminalState(result);
+  if (terminal.status === 'error') {
     meta.status = 'error';
-    meta.reason = result.error;
+    meta.reason = (result && result.error) ? String(result.error) : 'Incomplete';
     meta.completedAt = new Date().toISOString();
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
-    logger.error('Session completed with error', { taskId, error: result.error });
+    logger.error('Session completed with error', { taskId, error: meta.reason });
   } else {
-    finalizeSession(sessDir, summary, effectiveProject, meta, { quietStdout: json });
+    // complete / timed-out / aborted: persist the (possibly partial) summary with the correct status.
+    finalizeSession(sessDir, summary, effectiveProject, meta, { quietStdout: json, status: terminal.status });
+  }
+
+  const { resolveUsage } = require('../utils/pricing');
+  const runUsage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
+  if (runUsage) {
+    const m = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    m.usage = runUsage;
+    fs.writeFileSync(metaPath, JSON.stringify(m, null, 2), { mode: 0o600 });
   }
 
   if (json) {
@@ -234,10 +245,12 @@ async function startSidecar(options) {
     const finalMeta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
     const doc = buildRunResult({
       taskId, metadata: finalMeta, result, summary,
-      modelInput, sessionDir: sessDir,
+      modelInput, sessionDir: sessDir, usage: runUsage,
     });
     console.log(JSON.stringify(doc, null, 2));
   }
+
+  return terminal.exitCode;
 }
 
 module.exports = {

package/src/utils/activity-poller.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Poll an async status source on an interval and fire onActivity() on any non-idle state.
+ * Best-effort: getStatus errors are swallowed and polling continues. Timers are unref'd
+ * so the poller never keeps the process alive.
+ *
+ * @param {object} opts
+ * @param {() => Promise<{type?:string}>} opts.getStatus
+ * @param {() => void} opts.onActivity
+ * @param {number} [opts.intervalMs=30000]
+ * @returns {{ stop: () => void }}
+ */
+function createActivityPoller({ getStatus, onActivity, intervalMs = 30000 }) {
+  let timer = null;
+  let stopped = false;
+
+  const schedule = () => {
+    if (stopped) { return; }
+    timer = setTimeout(tick, intervalMs);
+    if (timer.unref) { timer.unref(); }
+  };
+
+  async function tick() {
+    if (stopped) { return; }
+    try {
+      const status = await getStatus();
+      if (status && status.type && status.type !== 'idle') { onActivity(); }
+    } catch { /* best-effort */ }
+    schedule();
+  }
+
+  schedule();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) { clearTimeout(timer); timer = null; }
+    },
+  };
+}
+
+/** SIGTERM a child process if it exists and isn't already killed. */
+function killIfAlive(child) {
+  if (child && !child.killed) { child.kill('SIGTERM'); }
+}
+
+module.exports = { createActivityPoller, killIfAlive };

package/src/utils/alias-resolver.js

@@ -67,7 +67,7 @@ function autoRepairAlias(alias, config, defaultAliases, saveConfig) {
   }
   throw new Error(
     `Alias '${alias}' is configured but has no model value. ` +
-    `Fix with: sidecar setup --add-alias ${alias}=provider/model`
+    `Fix with: amicus setup --add-alias ${alias}=provider/model`
   );
 }
 

package/src/utils/config.js

@@ -93,7 +93,7 @@ function getDefaultAliases() {
  * Resolution order:
  * 1. If modelArg contains '/' -> return as-is (full model string)
  * 2. If modelArg is a key in config.aliases -> return resolved string
- * 3. If modelArg is unknown alias -> throw Error mentioning 'sidecar setup'
+ * 3. If modelArg is unknown alias -> throw Error mentioning 'amicus setup'
  * 4. If modelArg is undefined and config.default exists -> resolve that alias
  * 5. If no default -> throw Error
  *
@@ -124,14 +124,14 @@ function resolveModel(modelArg) {
 
     // Unknown alias
     throw new Error(
-      `Unknown model alias '${modelArg}'. Run 'sidecar setup' to configure aliases.`
+      `Unknown model alias '${modelArg}'. Run 'amicus setup' to configure aliases.`
     );
   }
 
   // modelArg is undefined - use default
   if (!config || !config.default) {
     throw new Error(
-      'No model specified and no default configured. Run \'sidecar setup\' to set a default model.'
+      'No model specified and no default configured. Run \'amicus setup\' to set a default model.'
     );
   }
 
@@ -153,7 +153,7 @@ function resolveModel(modelArg) {
 
   // Default alias not found anywhere
   throw new Error(
-    `Default alias '${defaultValue}' not found in aliases. Run 'sidecar setup' to fix configuration.`
+    `Default alias '${defaultValue}' not found in aliases. Run 'amicus setup' to fix configuration.`
   );
 }
 

package/src/utils/error-doc.js

@@ -0,0 +1,55 @@
+// src/utils/error-doc.js
+'use strict';
+
+/**
+ * @module error-doc
+ * Structured error envelope for the `--json` contract (WS-2 #6). Every
+ * pre-flight failure under --json writes one of these to STDOUT (with a stable
+ * code) so an automation caller doing JSON.parse(stdout) gets a typed result
+ * instead of an empty string. Non-JSON callers keep human text on stderr.
+ */
+
+const { SCHEMA_VERSION } = require('./result-schema');
+
+/** Frozen — adding a code later is additive; renaming/removing is breaking. */
+const ERROR_CODES = Object.freeze({
+  BAD_ARGS: 'BAD_ARGS',             // bad/empty flag, mutually-exclusive flags, bad numeric/enum value
+  MISSING_PROMPT: 'MISSING_PROMPT', // no/empty --prompt or --prompt-file
+  BAD_MODEL: 'BAD_MODEL',           // bad model format, not on provider, not in catalog
+  MISSING_KEY: 'MISSING_KEY',       // provider API key absent
+  BAD_SESSION: 'BAD_SESSION',       // task id missing / invalid / not found
+  BUDGET_EXCEEDED: 'BUDGET_EXCEEDED', // the WS-2 #10 spend gate
+  INTERNAL: 'INTERNAL',             // unexpected pre-flight throw
+});
+
+/**
+ * @param {{code: string, message: string, hint?: string, command?: string}} opts
+ * @returns {object} error document
+ */
+function buildErrorDoc({ code, message, hint = null, command = null }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'error',
+    ok: false,
+    error: { code, message, hint: hint || null, command: command || null },
+  };
+}
+
+/**
+ * Emit a pre-flight failure: JSON envelope to stdout when useJson, else the
+ * human message to stderr. Returns the exit code (always 1) so callers can
+ * `process.exit(failJson(...))`.
+ * @param {boolean} useJson
+ * @param {{code: string, message: string, hint?: string, command?: string}} opts
+ * @returns {number}
+ */
+function failJson(useJson, { code, message, hint = null, command = null }) {
+  if (useJson) {
+    process.stdout.write(JSON.stringify(buildErrorDoc({ code, message, hint, command }), null, 2) + '\n');
+  } else {
+    process.stderr.write(message + '\n');
+  }
+  return 1;
+}
+
+module.exports = { ERROR_CODES, buildErrorDoc, failJson };

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', 'read', 'abort', 'fanout', 'models', 'key' /* local-only: no OpenCode server, no stray handles */]);
+const ONE_SHOT_COMMANDS = new Set(['start', 'continue', 'resume', 'list', 'read', 'abort', 'fanout', 'models', 'key', 'council', 'doctor' /* local-only: no OpenCode server, no stray handles */]);
 
 /** @param {string} command @returns {boolean} */
 function isOneShotCommand(command) {

package/src/utils/model-catalog.js

@@ -100,4 +100,4 @@ async function getCatalogInfo(opts = {}) {
   return { models, fetchedAt: cache ? cache.fetchedAt : null };
 }
 
-module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, CATALOG_SCHEMA_VERSION };
+module.exports = { getCatalog, refreshCatalog, catalogPath, getCatalogInfo, readCache, CATALOG_SCHEMA_VERSION };