amicus 1.7.7 → 1.8.1

package/skills/sidecar/SKILL.md

@@ -1,39 +1,37 @@
 ---
 name: sidecar
 description: >
-  Spawn conversations with other LLMs (Gemini, GPT, ChatGPT, Codex, o3, DeepSeek, Qwen,
-  Grok, Mistral, etc.) and fold results back into your context. TRIGGER when: user asks to
-  talk to, chat with, use, call, or spawn another LLM or model; user mentions Gemini, GPT,
-  ChatGPT, Codex, o3, DeepSeek, Claude (as a sidecar target), Qwen, Grok, Mistral, or any
-  non-current model by name; user asks to get a second opinion from another model; user
-  wants parallel exploration with a different model; user says "sidecar", "fork", or "fold".
-  CRITICAL RULES: (1) ALWAYS launch amicus CLI commands with Bash tool's
-  run_in_background: true. Never run amicus start/resume/continue in the foreground.
-  (2) The fold summary returns on stdout when the user clicks Fold in the GUI or the
-  headless agent finishes. Use TaskOutput to read it when the background task completes.
-  (3) For long or multi-line briefings, write them to a temp file and pass
-  --prompt-file <path> (mutually exclusive with --prompt; avoids shell-quoting hazards
-  and argument-size caps). (4) NEVER use o3 or o3-pro unless the user explicitly asks for it by
-  name. These models are extremely expensive ($10-60+ per request). If the user asks for
-  o3, warn them about the cost before proceeding. Default to gemini for most tasks.
-  (5) When the user asks to query MULTIPLE LLMs simultaneously (e.g., "ask Gemini AND
-  ChatGPT", "compare Gemini vs GPT"), ALWAYS use --no-ui (headless) for all of them
-  unless the user explicitly requests interactive. Opening multiple Electron windows at
-  once is disruptive. Launch them all in parallel with run_in_background: true.
-  (6) When the SAME prompt should go to N models, use `amicus fanout --models a,b,c
-  --prompt-file <path> --json` (one headless wave, one JSON result) instead of N
-  separate start calls. Different prompts per model → separate parallel
-  `amicus start --no-ui` calls.
-  (7) For a SINGLE-model sidecar, DEFAULT to interactive — omit --no-ui so the
-  Electron UI opens and the user can watch, converse, and click Fold. Use --no-ui
-  for a single model only when the user asks for headless/autonomous, or for
-  unattended bulk automation. Interactive launches still use run_in_background: true.
+  Spawn a conversation with another LLM (Gemini, GPT, ChatGPT, Codex, o3, DeepSeek,
+  Qwen, Grok, Mistral, or Claude as a target) and fold the results back into your
+  context. TRIGGER when: the user asks to talk to, chat with, call, use, or spawn
+  another LLM or model; names any non-current model; wants parallel exploration or
+  a quick take from a different model; or says "sidecar", "fork", or "fold". This
+  is NOT the skill for structured multi-model review of provided material — requests
+  like "second opinion", "council review", or red-team/stress-test against criteria
+  belong to the second-opinion skill. Before running any amicus command, read the
+  Operating Rules section at the top of this document: background launches,
+  --prompt-file briefings, interactive vs headless defaults, fanout for same-prompt
+  multi-model runs, the o3/o3-pro cost warning, and the npx fallback when amicus is
+  not on PATH.
 ---
 
 # Amicus: Multi-Model Sidecar Tool
 
 Spawn parallel conversations with different LLMs (Gemini, GPT, ChatGPT, Codex, o3, etc.) and fold results back into your context.
 
+## Operating Rules
+
+These rules are mandatory for every amicus invocation in this skill:
+
+1. **ALWAYS launch amicus CLI commands with the Bash tool's `run_in_background: true`.** Never run `amicus start/resume/continue` in the foreground.
+2. **The fold summary returns on stdout** when the user clicks Fold in the GUI or the headless agent finishes. Use TaskOutput to read it when the background task completes.
+3. **For long or multi-line briefings, write them to a temp file and pass `--prompt-file <path>`** (mutually exclusive with `--prompt`; avoids shell-quoting hazards and argument-size caps).
+4. **NEVER use o3 or o3-pro unless the user explicitly asks for it by name.** These models are extremely expensive (\$10-60+ per request). If the user asks for o3, warn them about the cost before proceeding. Default to gemini for most tasks. The CLI enforces this in code: a built-in budget gate refuses any model above a per-$/Mtok threshold (o3-pro class) before launch unless you pass `--no-cost-gate`; `--max-cost <$>` sets a soft estimated-total ceiling. When a run is refused with `BUDGET_EXCEEDED`, relay the gate's message — don't silently retry with the flag.
+5. **When the user asks to query MULTIPLE LLMs simultaneously** (e.g., "ask Gemini AND ChatGPT", "compare Gemini vs GPT"), ALWAYS use `--no-ui` (headless) for all of them unless the user explicitly requests interactive. Opening multiple Electron windows at once is disruptive. Launch them all in parallel with `run_in_background: true`.
+6. **When the SAME prompt should go to N models, use `amicus fanout --models "a,b,c" --prompt-file <path> --json`** (one headless wave, one JSON result) instead of N separate start calls. Different prompts per model → separate parallel `amicus start --no-ui` calls.
+7. **For a SINGLE-model sidecar, DEFAULT to interactive** — omit `--no-ui` so the Electron UI opens and the user can watch, converse, and click Fold. Use `--no-ui` for a single model only when the user asks for headless/autonomous, or for unattended bulk automation. Interactive launches still use `run_in_background: true`.
+8. **If `amicus` is not on PATH** (typical for plugin-only installs), run every command in this skill as `npx -y amicus@latest <args>` (e.g. `npx -y amicus@latest start --model gemini --prompt "..."`), or use the MCP tools (`amicus_start`, `amicus_status`, `amicus_read`, …) instead. Do not conclude the tool is broken because `amicus` is not found.
+
 ## Installation
 
 ```bash
@@ -204,11 +202,11 @@ amicus start \
 ```
 
 **Required:**
-- `--model`: The model to use (see Models below)
-- `--prompt`: Detailed task description you generate
+- `--prompt` (or `--prompt-file`): Detailed task description you generate
 
 **Recommended:**
-- `--session`: Your Claude Code session ID for accurate context passing
+- `--model`: The model to use (see Models below). Omit it to use your configured default (`amicus setup`); the CLI errors only when neither an explicit model nor a configured default exists.
+- `--session-id`: Your Claude Code session ID for accurate context passing
 
 **Optional:**
 - `--no-ui`: Run autonomously without GUI (for bulk tasks)
@@ -257,7 +255,7 @@ The CLI validates all inputs **before** launching the sidecar. Invalid inputs fa
 
 | Input | Validation | Error Message |
 |-------|------------|---------------|
-| `--model` | Must be present, format: `provider/model` | `Error: --model is required` or `Error: --model must be in format provider/model` |
+| `--model` | Optional — falls back to the config default. An explicit value must resolve to a known alias or `provider/model` | `Error: Unknown model alias '<x>' …` or `No model specified and no default configured. Run 'amicus setup' to set a default model.` |
 | `--prompt` | Must be present and non-empty | `Error: --prompt is required` or `Error: --prompt cannot be empty or whitespace-only` |
 | `--cwd` | If provided, directory must exist | `Error: --cwd path does not exist: <path>` |
 | `--session-id` | If explicit ID provided (not 'current'), must exist | `Error: --session-id '<id>' not found. Use 'amicus list' to see available sessions or omit --session-id for most recent.` |
@@ -283,7 +281,7 @@ If you receive a validation error, fix the input and retry:
 
 ```bash
 # Error: --session-id 'abc123' not found
-# Fix: Use 'current' or omit --session
+# Fix: Use 'current' or omit --session-id
 amicus start --model gemini --prompt "Task" --session-id current
 
 # Error: --agent cannot be empty
@@ -303,7 +301,7 @@ amicus start --model gemini --prompt "Task"
 ### Fan Out One Prompt to N Models
 
 ```bash
-amicus fanout --models gemini,gpt,deepseek --prompt-file ./briefing.md --json
+amicus fanout --models "gemini,gpt,deepseek" --prompt-file ./briefing.md --json
 ```
 
 Runs the same prompt on every listed model in parallel (one shared engine server, headless),
@@ -404,7 +402,7 @@ amicus abort --all         # stop every running session in this project
 
 ### Model Selection
 
-Use short aliases (run `amicus guide` to see all available aliases and their current model IDs):
+Use short aliases (run `amicus models` to see the live catalog, and `amicus models --check` to audit your aliases):
 - `--model gemini` -- Google Gemini (fast, large context)
 - `--model opus` -- Claude Opus (deep analysis)
 - `--model gpt` -- OpenAI GPT
@@ -454,13 +452,13 @@ ls -lt ~/.claude/projects/-Users-john-myproject/*.jsonl | head -5
 The most recently modified file is likely your current session. Extract the UUID from the filename.
 
 **Session ID behavior:**
-- **Omit `--session`** or use `--session-id current`: Uses the most recently modified session file (less reliable if multiple sessions are active)
+- **Omit `--session-id`** or pass `--session-id current`: Uses the most recently modified session file (less reliable if multiple sessions are active)
 - **Explicit session ID** (`--session-id abc123-def456`): Must exist or the command fails immediately with: `Error: --session-id 'abc123-def456' not found`
 
 **If you get a session not found error:**
 1. List available sessions: `amicus list`
 2. Use one of the listed session IDs, OR
-3. Omit `--session` to use the most recent session
+3. Omit `--session-id` to use the most recent session
 
 ---
 
@@ -849,7 +847,7 @@ Find the correct encoded path for your project. Remember that `/`, `\`, and `_`
 
 ### "Multiple active sessions detected"
 
-You have multiple Claude Code windows. Pass `--session` explicitly:
+You have multiple Claude Code windows. Pass `--session-id` explicitly:
 ```bash
 ls -lt ~/.claude/projects/[your-path]/*.jsonl | head -3
 # Pick the correct session UUID
@@ -912,7 +910,7 @@ amicus start --model gemini --prompt "Debug the auth issue in TokenManager.ts"
 
 The explicit session ID doesn't exist. Either:
 1. Use `amicus list` to find valid session IDs
-2. Omit `--session` to use the most recent session
+2. Omit `--session-id` to use the most recent session
 3. Use `--session-id current` for automatic resolution
 
 ```bash

package/src/cli-handlers-doctor.js

@@ -41,6 +41,8 @@ function realDeps() {
     fix: false,
     discoverClaudeCodeMcps: () => require('./utils/mcp-discovery').discoverClaudeCodeMcps(),
     discoverCoworkMcps: () => require('./utils/mcp-discovery').discoverCoworkMcps(),
+    inspectLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').inspectAllLegacySidecarEntries(),
+    migrateLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').migrateLegacySidecar(),
     skillInstalled: () => {
       const dir = path.join(os.homedir(), '.claude', 'skills');
       return fs.existsSync(path.join(dir, 'sidecar', 'SKILL.md'))
@@ -181,6 +183,47 @@ async function runDoctorChecks(depsOverride = {}) {
     return { id: 'mcp', name: 'MCP registration', 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.
+  checks.push(guard('mcp-legacy', 'Legacy sidecar MCP entry', () => {
+    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 };
+  }));
+
   // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
   checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
     const values = d.readApiKeyValues() || {};

package/src/cli-handlers-status.js

@@ -0,0 +1,76 @@
+/**
+ * `amicus status <task_id>` — one-shot human/JSON status for a session or wave.
+ * Reads the SAME sources as the MCP amicus_status handler by calling it
+ * directly (requiring mcp-server does NOT start the server; the MCP SDK is
+ * only loaded inside startMcpServer()). Zero duplicated status logic — this
+ * inherits crash detection, wave leg rollup, and P6-3 enrichment for free.
+ */
+
+'use strict';
+
+const { validateTaskId } = require('./utils/validators');
+
+/** Render a key-value block for a single-session status payload. */
+function formatRunHuman(d) {
+  const lines = [
+    `Task:     ${d.taskId}`,
+    `Status:   ${d.status}${d.phase ? ` (${d.phase})` : ''}`,
+    `Elapsed:  ${d.elapsed}`,
+  ];
+  if (d.model) { lines.push(`Model:    ${d.model}`); }
+  if (d.mode) { lines.push(`Mode:     ${d.mode}`); }
+  if (d.messageCount !== undefined) { lines.push(`Messages: ${d.messageCount}`); }
+  if (d.lastActivity) { lines.push(`Activity: ${d.lastActivity}`); }
+  if (d.latestPreview) { lines.push(`Latest:   ${d.latestPreview}`); }
+  else if (d.latest) { lines.push(`Latest:   ${d.latest}`); }
+  if (d.stalled) { lines.push(`STALLED:  no activity for ${d.stalledForSeconds}s (see --json for recovery)`); }
+  if (d.reason) { lines.push(`Reason:   ${d.reason}`); }
+  return lines.join('\n');
+}
+
+/** Render a wave payload: header + one line per leg. */
+function formatWaveHumanStatus(d) {
+  const head = `Wave ${d.taskId}: ${d.status} — ${d.legsComplete}/${d.legsTotal} legs done (${d.elapsed})`;
+  const legLines = (d.legs || []).map((l) => {
+    const label = String(l.model || l.taskId || '').padEnd(28);
+    const st = String(l.status || 'unknown').padEnd(10);
+    const msgs = l.messages !== undefined ? `${l.messages} msg` : '';
+    const latest = l.latestPreview || l.latestActivity || '';
+    const flag = l.stalled ? ' ⏳stalled' : '';
+    return `  ${label} ${st} ${msgs} | ${latest}${flag}`;
+  });
+  return [head, ...legLines].join('\n');
+}
+
+/**
+ * Handle 'amicus status'. Exit code 0 = status retrieved (any run state, even
+ * a failed/crashed run — the QUERY succeeded); 1 = missing/invalid/unknown id.
+ * @param {object} args parsed CLI args
+ * @returns {Promise<number>}
+ */
+async function handleStatus(args) {
+  const taskId = args.wave || args._[1];
+  if (!taskId || taskId === true) {
+    process.stderr.write('Error: task_id is required for status\n');
+    process.stderr.write('Usage: amicus status <task_id> [--json]   (or: amicus status --wave <wave_id>)\n');
+    return 1;
+  }
+  const check = validateTaskId(String(taskId));
+  if (!check.valid) { process.stderr.write(`${check.error}\n`); return 1; }
+
+  const project = args.cwd || process.cwd();
+  const { handlers } = require('./mcp-server');
+  const result = await handlers.amicus_status({ taskId: String(taskId) }, project);
+  const text = result.content[0].text;
+  if (result.isError) { process.stderr.write(`${text}\n`); return 1; }
+
+  let data;
+  try { data = JSON.parse(text); } catch { process.stdout.write(`${text}\n`); return 0; }
+  delete data.next_poll; // MCP-agent polling guidance, not CLI output
+
+  if (args.json) { process.stdout.write(`${JSON.stringify(data, null, 2)}\n`); return 0; }
+  process.stdout.write(`${data.type === 'wave' ? formatWaveHumanStatus(data) : formatRunHuman(data)}\n`);
+  return 0;
+}
+
+module.exports = { handleStatus, formatRunHuman, formatWaveHumanStatus };

package/src/cli-handlers.js

@@ -123,6 +123,16 @@ async function handleAbort(args) {
     console.error(`Session ${taskId} has malformed metadata`);
     process.exit(1);
   }
+  // Guard against a completed/terminal session: without this, metadata.pid
+  // still holds a value forever and `amicus abort <completed-task>` would
+  // wait the grace window then TerminateProcess whatever unrelated process
+  // now owns that (possibly recycled) pid. Mirrors MCP's amicus_abort guard
+  // (src/mcp-server.js) — same wording, no re-mark, no kill.
+  if (meta.status !== 'running') {
+    console.log(`Session ${taskId} is not running (status: ${meta.status}).`);
+    return;
+  }
+
   const { markAborted } = require('./utils/session-abort');
 
   // F4: aborting a wave aborts every still-running leg too.
@@ -147,6 +157,28 @@ async function handleAbort(args) {
 
   markAborted(sessionDir, 'manual abort');
   console.log(`Session ${taskId} marked as aborted.`);
+
+  // Phase 3: fallback direct-kill for a session that does not honor the
+  // marker. Headless loops poll the marker every ~2s and the interactive
+  // abort watch does too, so the normal outcome is a graceful exit during
+  // the grace window; only a wedged/legacy process gets SIGTERM. The wait is
+  // awaited on purpose — bin/amicus.js arms its force-exit watchdog only
+  // after this handler returns.
+  if (meta.pid) {
+    const { waitThenKill, abortGraceMs } = require('./utils/abort-coordinator');
+    const graceSec = Math.ceil(abortGraceMs() / 1000);
+    console.log(`Waiting up to ${graceSec}s for the session process (pid ${meta.pid}) to exit gracefully...`);
+    const { killed, exited } = await waitThenKill(meta.pid);
+    if (killed.length > 0) {
+      console.log(`Process ${meta.pid} did not exit in time — sent SIGTERM (a hard kill on Windows).`);
+    } else if (exited.length > 0) {
+      console.log('Process exited cleanly.');
+    } else {
+      // 3.1 contract: an EPERM-unkillable pid lands in NEITHER array —
+      // it is still alive and we could not signal it. Say so honestly.
+      console.log(`Process ${meta.pid} is still running — could not signal it (insufficient permission). It may require manual termination.`);
+    }
+  }
 }
 
 /**

package/src/cli.js

@@ -330,6 +330,7 @@ Commands:
   start       Launch a new amicus session
   fanout      Run N models on the same prompt in parallel (headless)
   list        Show previous sessions
+  status      One-shot status for a session or wave (--json)
   resume      Reopen a previous session
   continue    New session building on previous
   read        Output session summary/conversation
@@ -416,6 +417,13 @@ Options for 'list':
   --status <filter>            Filter by status (running, complete)
   --all                        Show all projects
   --json                       Output as JSON
+`,
+  status: `
+Options for 'status':
+  <task_id>                    Required. Session or wave ID (positional)
+  --wave <wave_id>             Alternative to the positional ID for waves
+  --json                       Machine-readable output
+  --cwd <path>                 Project directory (default: cwd)
 `,
   abort: `
 Options for 'abort':

package/src/headless.js

@@ -463,6 +463,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             const s = (statusData && statusData.type) ? statusData : (statusData && statusData[sessionId]);
             if (s && s.type === 'idle') {
               logger.debug('Session reported idle by SDK — completing', { sessionId });
+              completed = true;
               break;
             }
           } catch (statusErr) {
@@ -493,6 +494,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
             const threshold = assistantFinished ? stableFinishedPolls : stableIdlePolls;
             if (stablePolls >= threshold) {
               logger.debug('Session appears complete (idle)', { stablePolls, assistantFinished });
+              completed = true;
               break;
             }
           } else {