amicus 1.0.0 → 1.2.0

package/src/sidecar/setup.js

@@ -13,15 +13,6 @@ const readline = require('readline');
 const { loadConfig, saveConfig, getDefaultAliases, getConfigDir } = require('../utils/config');
 const { logger } = require('../utils/logger');
 
-const { getCuratedModels } = require('../utils/curated-models');
-/**
- * Model choices presented during readline setup — derived from curated-models (F5).
- * @type {Array<{number: number, alias: string, label: string}>}
- */
-const MODEL_CHOICES = getCuratedModels().map((c, i) => ({
-  number: i + 1, alias: c.alias, label: `${c.label} (${c.blurb})`
-}));
-
 /**
  * Add a model alias to the existing config (or create config if none exists)
  * @param {string} name - Alias name
@@ -68,7 +59,7 @@ function createDefaultConfig(defaultModel) {
 
 /**
  * Detect available API keys from .env file and process.env
- * @returns {{openrouter: boolean, google: boolean, openai: boolean, anthropic: boolean}}
+ * @returns {{openrouter: boolean, google: boolean, openai: boolean, anthropic: boolean, deepseek: boolean}}
  */
 function detectApiKeys() {
   const { readApiKeys } = require('../utils/api-key-store');
@@ -90,21 +81,28 @@ function askQuestion(rl, prompt) {
 }
 
 /**
- * Resolve user input to a model alias name
- * @param {string} input - User input (number 1-5 or alias name)
- * @returns {string|null} Resolved alias name, or null if invalid
+ * Resolve readline input against the live picks.
+ * @returns {{alias?: string, modelId?: string, noUpgrade?: boolean}|null}
+ *   alias  → numbered/named quick pick (upgrades that alias unless noUpgrade)
+ *   modelId → free-form full model id (default only, no alias writes)
  */
-function resolveChoice(input) {
+function resolveChoice(input, picks, catalog) {
   const num = parseInt(input, 10);
-  if (num >= 1 && num <= MODEL_CHOICES.length) {
-    return MODEL_CHOICES[num - 1].alias;
+  if (num >= 1 && num <= picks.length) {
+    return { alias: picks[num - 1].alias };
   }
-
-  const defaults = getDefaultAliases();
-  if (defaults[input] !== undefined) {
-    return input;
+  if (input.includes('/')) {
+    const known = (catalog || []).some(m => m && m.id === input);
+    if (!known) {
+      console.log(`Warning: '${input}' not found in the model catalog (offline or new model) — using it anyway.`); // eslint-disable-line no-console
+    }
+    return { modelId: input };
+  }
+  const cfg = loadConfig();
+  const aliases = { ...getDefaultAliases(), ...((cfg && cfg.aliases) || {}) };
+  if (aliases[input] !== undefined) {
+    return { alias: input, noUpgrade: true };
   }
-
   return null;
 }
 
@@ -159,8 +157,8 @@ async function seedCatalog(print) {
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Default model selection
- * 3. Config file creation
+ * 2. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 3. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -170,7 +168,7 @@ async function runReadlineSetup() {
 
   try {
     console.log('');
-    console.log('=== Sidecar Setup Wizard ===');
+    console.log('=== Amicus Setup Wizard ===');
     console.log('');
 
     const keys = detectApiKeys();
@@ -183,38 +181,54 @@ 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('');
 
+    const { getCatalog } = require('../utils/model-catalog');
+    const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
+    let catalog = [];
+    try { catalog = await getCatalog(); } catch (_err) { /* offline: pinned */ }
+    const picks = resolveQuickPicks(catalog);
+
     console.log('Choose your default model:');
     console.log('');
-    for (const choice of MODEL_CHOICES) {
-      console.log(`  ${choice.number}) ${choice.alias} - ${choice.label}`);
-    }
+    picks.forEach((p, i) => {
+      const badge = p.source === 'fallback' ? ' [offline list]' : '';
+      console.log(`  ${i + 1}) ${p.alias} - ${p.label} (${p.blurb}) → ${p.routes.openrouter}${badge}`);
+    });
     console.log('');
 
-    const answer = await askQuestion(rl, 'Pick a default (1-5 or alias name): ');
-    const chosen = resolveChoice(answer);
+    const answer = await askQuestion(rl,
+      `Pick a default (1-${picks.length}, alias name, or any full model id): `);
+    const chosen = resolveChoice(answer, picks, catalog);
 
     if (!chosen) {
-      console.log(`Invalid choice: "${answer}". Using "gemini" as default.`);
-      const cfg = createDefaultConfig('gemini');
-      await seedCatalog();
-      const aliasCount = Object.keys(cfg.aliases).length;
-      console.log('');
-      console.log(`Config created with ${aliasCount} aliases.`);
-      console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
+      console.log(`Invalid choice: "${answer}". Keeping configuration unchanged.`);
       return;
     }
 
-    const cfg = createDefaultConfig(chosen);
+    // Read-modify-write — never rebuild the alias table (no-clobber rule).
+    const cfg = loadConfig() || { aliases: toLiveSeedAliases(catalog) };
+    if (!cfg.aliases) { cfg.aliases = {}; }
+    if (chosen.alias) {
+      cfg.default = chosen.alias;
+      const pick = picks.find(p => p.alias === chosen.alias);
+      if (pick && !chosen.noUpgrade) {
+        cfg.aliases[chosen.alias] = pick.routes.openrouter || Object.values(pick.routes)[0];
+      } else if (cfg.aliases[chosen.alias] === undefined) {
+        const fallback = getDefaultAliases()[chosen.alias];
+        if (fallback !== undefined) { cfg.aliases[chosen.alias] = fallback; }
+      }
+    } else {
+      cfg.default = chosen.modelId;
+    }
+    saveConfig(cfg);
     await seedCatalog();
-    const aliasCount = Object.keys(cfg.aliases).length;
 
     console.log('');
-    console.log(`Default model set to: ${chosen}`);
-    console.log(`Config created with ${aliasCount} aliases.`);
+    console.log(`Default model set to: ${cfg.default}`);
+    console.log(`Config saved (${Object.keys(cfg.aliases).length} aliases).`);
     console.log(`Config path: ${path.join(getConfigDir(), 'config.json')}`);
   } finally {
     rl.close();
@@ -276,5 +290,4 @@ module.exports = {
   runReadlineSetup,
   runApiKeySetup,
   seedCatalog,
-  MODEL_CHOICES,
 };

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/curated-models.js

@@ -1,77 +1,120 @@
-/**
- * Curated Models — THE single source of truth for default model lists.
- *
- * Three consumers derive from this module (F5 anti-drift):
- *   - src/utils/config.js DEFAULT_ALIASES   (toDefaultAliases)
- *   - electron/setup-ui-model.js MODEL_CHOICES (getCuratedModels)
- *   - src/sidecar/setup.js MODEL_CHOICES      (getCuratedModels)
- * Never hand-edit a model id anywhere else. `amicus models --check`
- * audits every route here against the live catalog.
+/** Family definitions + pinned fallbacks for the wizard model picker (v2). */
+/*
+ * Families are MATCH RULES over the live catalog, not pinned truths:
+ * src/utils/quick-picks.js resolves each family to the current catalog
+ * flagship at setup time. The pinned `fallback` ids are used only when
+ * the catalog cannot resolve a route (offline / unkeyed provider) and to
+ * derive the static DEFAULT_ALIASES (runtime alias resolution must never
+ * wait on the network). `amicus models --check` audits every pinned route
+ * here against the live catalog AND warns when a fallback falls behind
+ * the live resolution.
  */
 
 'use strict';
 
 /**
- * Card entries (shown as wizard quick picks). `routes` maps provider →
- * full model id; the openrouter route doubles as the default alias target.
- * Direct (non-openrouter) route ids MUST be verified against the provider
- * whenever they change.
+ * Wizard quick-pick families. `idPattern` matches the model segment after
+ * `<vendorPath>/` (openrouter ns) or `<provider>/` (direct ns).
+ * `directProviders` lists direct namespaces the quick-picks resolver may
+ * resolve live from the catalog. A per-provider `fallback` entry is
+ * OPTIONAL: when absent and the catalog cannot resolve that namespace,
+ * the direct route is omitted (no pinned guess is better than a wrong one).
+ * `gpt`'s pattern intentionally matches any plain numeric flagship id
+ * (gpt-5.5, gpt-6) and excludes suffixed variants (-pro/-mini/-codex).
+ * Pinned ids verified against the live catalog 2026-06-11.
  */
-const CARDS = [
-  { alias: 'gemini', label: 'Gemini 3.1 Flash Lite', blurb: 'fast, large context',
-    routes: { openrouter: 'openrouter/google/gemini-3.1-flash-lite-preview',
-              google: 'google/gemini-3.1-flash-lite-preview' } },
-  { alias: 'gemini-pro', label: 'Gemini 3.1 Pro', blurb: 'advanced reasoning',
-    routes: { openrouter: 'openrouter/google/gemini-3.1-pro-preview',
-              google: 'google/gemini-3.1-pro-preview' } },
-  { alias: 'gpt', label: 'GPT-5.4', blurb: 'strong coding',
-    routes: { openrouter: 'openrouter/openai/gpt-5.4',
-              openai: 'openai/gpt-5.4' } },
-  { alias: 'opus', label: 'Claude Opus 4.6', blurb: 'deep analysis',
-    routes: { openrouter: 'openrouter/anthropic/claude-opus-4.6',
-              anthropic: 'anthropic/claude-opus-4-6' } },
-  { alias: 'deepseek', label: 'DeepSeek v3.2', blurb: 'open-source',
-    routes: { openrouter: 'openrouter/deepseek/deepseek-v3.2' } },
+const FAMILIES = [
+  { alias: 'gemini', label: 'Gemini Flash-class', blurb: 'fast, large context',
+    vendorPath: 'google',
+    idPattern: /^gemini-[\d.]+-flash(-preview|-exp|-latest)?$/,
+    directProviders: ['google'],
+    fallback: { openrouter: 'openrouter/google/gemini-3.5-flash',
+                google: 'google/gemini-3.5-flash' } },
+  { alias: 'gemini-pro', label: 'Gemini Pro-class', blurb: 'advanced reasoning',
+    vendorPath: 'google',
+    idPattern: /^gemini-[\d.]+-pro(-preview|-exp|-latest)?$/,
+    directProviders: ['google'],
+    fallback: { openrouter: 'openrouter/google/gemini-3.1-pro-preview' } },
+  { alias: 'gpt', label: 'GPT flagship', blurb: 'strong coding',
+    vendorPath: 'openai',
+    idPattern: /^gpt-[\d.]+$/,
+    directProviders: ['openai'],
+    fallback: { openrouter: 'openrouter/openai/gpt-5.5' } },
+  { alias: 'opus', label: 'Claude Opus-class', blurb: 'deep analysis',
+    vendorPath: 'anthropic',
+    idPattern: /^claude-opus-[\d.-]+$/,
+    directProviders: ['anthropic'],
+    fallback: { openrouter: 'openrouter/anthropic/claude-opus-4.8',
+                anthropic: 'anthropic/claude-opus-4-6' } },
+  { alias: 'deepseek', label: 'DeepSeek flagship', blurb: 'open-source',
+    vendorPath: 'deepseek',
+    idPattern: /^deepseek-v[\d.]+(-pro)?$/,
+    directProviders: ['deepseek'],
+    fallback: { openrouter: 'openrouter/deepseek/deepseek-v4-pro',
+                deepseek: 'deepseek/deepseek-chat' } },
 ];
 
-/** Alias-only entries (no wizard card); openrouter route only. */
+/**
+ * Alias-only entries (no wizard quick pick); openrouter route only.
+ * Refreshed against the live catalog 2026-06-11.
+ */
 const CARDLESS = [
-  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.4-pro' } },
+  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.5-pro' } },
   // codex: newest codex-specific model on OpenRouter (verified 2026-06-09).
   { alias: 'codex', routes: { openrouter: 'openrouter/openai/gpt-5.3-codex' } },
   { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
   { alias: 'sonnet', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
   { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5' } },
-  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.5-397b-a17b' } },
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.7-max' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
-  { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.5-flash-02-23' } },
-  { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-large-2512' } },
+  { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
+  { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },
   { alias: 'devstral', routes: { openrouter: 'openrouter/mistralai/devstral-2512' } },
-  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5' } },
-  { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.5' } },
+  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5.1' } },
+  { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.7' } },
   { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },
-  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.5' } },
-  { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-mini' } },
+  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.6' } },
+  { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-lite' } },
 ];
 
-/** @returns {Array<{alias,label,blurb,routes}>} card entries (wizard quick picks) */
-function getCuratedModels() {
-  return CARDS.map(c => ({ ...c, routes: { ...c.routes } }));
+/**
+ * @returns {Array} shallow-spread copies of the family definitions;
+ * `idPattern` is intentionally a shared RegExp reference — safe because
+ * none use the g/y flags (no lastIndex state) and callers treat it read-only.
+ */
+function getFamilies() {
+  return FAMILIES.map(f => ({
+    ...f,
+    directProviders: [...f.directProviders],
+    fallback: { ...f.fallback },
+  }));
 }
 
-/** @returns {Object<string,string>} alias → preferred route (openrouter first) */
+/**
+ * @returns {Object<string,string>} alias → pinned route (openrouter first). STATIC — runtime-safe.
+ */
 function toDefaultAliases() {
   const out = {};
-  for (const e of [...CARDS, ...CARDLESS]) {
+  for (const f of FAMILIES) {
+    out[f.alias] = f.fallback.openrouter || Object.values(f.fallback)[0];
+  }
+  for (const e of CARDLESS) {
     out[e.alias] = e.routes.openrouter || Object.values(e.routes)[0];
   }
   return out;
 }
 
-/** @returns {Array<{alias,provider,model}>} every route of every entry, flattened */
+/**
+ * @returns {Array<{alias,provider,model}>} every pinned route, flattened (for the alias audit).
+ */
 function listCuratedRoutes() {
   const out = [];
-  for (const e of [...CARDS, ...CARDLESS]) {
+  for (const f of FAMILIES) {
+    for (const [provider, model] of Object.entries(f.fallback)) {
+      out.push({ alias: f.alias, provider, model });
+    }
+  }
+  for (const e of CARDLESS) {
     for (const [provider, model] of Object.entries(e.routes)) {
       out.push({ alias: e.alias, provider, model });
     }
@@ -79,4 +122,4 @@ function listCuratedRoutes() {
   return out;
 }
 
-module.exports = { getCuratedModels, toDefaultAliases, listCuratedRoutes };
+module.exports = { getFamilies, toDefaultAliases, listCuratedRoutes };

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']);
+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 };

package/src/utils/model-fetcher.js

@@ -20,7 +20,8 @@ const PROVIDER_FAMILY_NAMES = {
   openrouter: 'OpenRouter',
   google: 'Google',
   openai: 'OpenAI',
-  anthropic: 'Anthropic'
+  anthropic: 'Anthropic',
+  deepseek: 'DeepSeek'
 };
 
 /** Provider API configs for fetching model lists */
@@ -68,6 +69,19 @@ const PROVIDER_FETCH_CONFIG = {
         pricing: null
       }));
     }
+  },
+  deepseek: {
+    url: 'https://api.deepseek.com/models',
+    authHeader: (key) => ({ 'Authorization': `Bearer ${key}` }),
+    normalize: (body) => {
+      const data = JSON.parse(body);
+      return (data.data || []).map(m => ({
+        id: `deepseek/${m.id}`,
+        name: m.id,
+        contextLength: null,
+        pricing: null
+      }));
+    }
   }
 };
 
@@ -75,7 +89,7 @@ const FETCH_TIMEOUT_MS = 5000;
 
 /**
  * Fetch models from a single provider API
- * @param {string} provider - Provider name (openrouter, google, openai, anthropic)
+ * @param {string} provider - Provider name (openrouter, google, openai, anthropic, deepseek)
  * @param {string} key - API key
  * @returns {Promise<Array<{id: string, name: string, contextLength: number|null, pricing: {prompt: string|null, completion: string|null}|null}>>} Normalized model list
  */