amicus 4.5.2 → 4.5.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.5.3] - 2026-08-01
+
+### Fixed
+
+- **Unknown CLI flags are rejected instead of silently absorbed.** `parseArgs` treated any
+  `--token` as a flag: an unrecognized one landed on the parsed args object, no handler read it,
+  and the command ran as though it were never typed. Found while smoke-testing v4.5.2 —
+  `amicus start -m deepseek --prompt "…" --headless` printed no error and exited 0, but `start`
+  has no `--headless`; the run silently took the **interactive** path, ignored `-m`, and left a
+  session running against the default model. A typo (`--modl`), a flag borrowed from another
+  command, or an invented one all behaved the same way, and an unknown flag followed by a
+  positional would swallow it as its value. Unknown flags now get the same treatment amicus
+  already gave an unknown *command*: name it, suggest the nearest real flag, point at `--help`,
+  exit 1. The known-flag set is **derived from the usage text** (the same source `getCommandNames()`
+  uses, for the same anti-rot reason) plus the boolean-flag list, plus a small explicitly-documented
+  allowlist of internal MCP→CLI passthroughs (`--task-id`, `--run-id`, `--council-name`,
+  `--cowork-process`) and undocumented-but-working flags (`--briefing`, `--mode`, `--quiet`).
+  A regression test asserts every `args.<flag>` any CLI handler reads is in the known set, so the
+  check can never silently start rejecting a flag that works.
+
+### Changed
+
+- **README Quick start is now four numbered steps**, with **Configure** promoted from a bold line
+  buried between two callouts to its own step and TOC entry. Installing without configuring is the
+  step people skip, and every council fails at the first model call when they do — so it now says
+  so plainly, notes that one OpenRouter key is enough to start, and ends with `amicus doctor` as
+  the confirmation that setup actually took.
+
 ## [4.5.2] - 2026-07-31
 
 ### Fixed

package/README.md

@@ -29,6 +29,10 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 - [The Council](#the-council)
 - [Ways to run the council](#ways-to-run-the-council)
 - [Quick start](#quick-start)
+  - [1. Install](#1-install)
+  - [**2. Configure — don't skip this**](#2-configure--dont-skip-this)
+  - [3. Your first council](#3-your-first-council)
+  - [4. Your first sidecar](#4-your-first-sidecar)
 - [Requirements & Dependencies](#requirements--dependencies)
 - [The parallel window](#the-parallel-window)
 - [Commands](#commands)
@@ -170,7 +174,9 @@ Any flag you also type on that second line overrides just that value — a pack
 >
 > **Convention used throughout this README:** plugin-channel users: prefix CLI examples with `npx -y amicus@latest` (skip the bare `amicus`/`am`). Individual code blocks are not duplicated per channel — this note is the one translation you need.
 
-**Install** — pick whichever fits. Every path delivers the MCP server and both skills; the `amicus`/`am` CLI lands on your PATH with the **npm and install-script paths** (the plugin path runs the CLI on demand via `npx -y amicus@latest <command>`):
+### 1. Install
+
+Pick whichever fits. Every path delivers the MCP server and both skills; the `amicus`/`am` CLI lands on your PATH with the **npm and install-script paths** (the plugin path runs the CLI on demand via `npx -y amicus@latest <command>`):
 
 **As a Claude Code plugin** — the most native path if you use Claude Code:
 
@@ -207,7 +213,15 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 
 > **Skipped the postinstall?** `--ignore-scripts` npm installs never run it, and the plugin channel skips it by design (Claude Code registers the plugin's MCP server and skills itself). Either way, run `amicus init` (plugin channel: `npx -y amicus@latest init`) any time to (re)register on demand — e.g. to also wire up Claude Desktop, which the plugin path doesn't touch. See [`amicus init`](./docs/usage.md#amicus-init).
 
-**Configure:**
+---
+
+### 2. Configure — don't skip this
+
+> ### ⚠️ Installing is not enough. Run this or nothing will work.
+>
+> Amicus has **no API keys of its own** — it drives *your* accounts at OpenRouter, Google,
+> OpenAI, Anthropic, or DeepSeek. Until you add at least one key, every council and every
+> sidecar fails at the first model call. **This is the step people skip.**
 
 ```bash
 amicus setup
@@ -215,6 +229,10 @@ amicus setup
 npx -y amicus@latest setup
 ```
 
+**One key is enough to start.** [OpenRouter](https://openrouter.ai/keys) is the usual choice —
+a single key reaches every model in the catalog, which is what makes a mixed-vendor council
+work without four separate accounts.
+
 This opens a graphical wizard:
 
 | Step | What it does |
@@ -226,7 +244,20 @@ This opens a graphical wizard:
 
 > **Headless environments:** if Electron can't open a window, the wizard falls back to a readline-based setup in the terminal.
 
-**Your first council** — no flags to learn. In Claude Code or Cowork, give Claude a document and say:
+**Confirm it took** — this is the fastest way to know you're actually ready:
+
+```bash
+amicus doctor
+```
+
+Green across the board (`0 error(s)`) means keys, catalog, engine, skills, and MCP registration
+are all in place. Anything red, `amicus doctor` tells you exactly what to run next.
+
+---
+
+### 3. Your first council
+
+No flags to learn. In Claude Code or Cowork, give Claude a document and say:
 
 > *council review this*
 
@@ -234,7 +265,9 @@ Plugin-channel users can also type **`/amicus:council`** directly instead of phr
 
 Claude prepares the material, recommends a bench of models, discloses the run shape and cost, and orchestrates the rest. You make the accept/deny calls at the end. (The `second-opinion` skill is what teaches Claude to recognize this — if nothing happens, run `amicus doctor` (or `npx -y amicus@latest doctor`). npm/install-script installs place the skill at `~/.claude/skills/second-opinion/`; plugin installs keep it inside the plugin itself — check `/plugin` in Claude Code to confirm amicus is enabled.)
 
-**Your first sidecar.** The sidecar is the lower-level path — you can invoke it by phrase through Claude too, but the CLI gives you the flags directly:
+### 4. Your first sidecar
+
+The sidecar is the lower-level path — you can invoke it by phrase through Claude too, but the CLI gives you the flags directly:
 
 ```bash
 amicus start --model gemini --prompt "Fact-check the auth approach Claude just proposed"
@@ -380,7 +413,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/bin/amicus.js

@@ -22,6 +22,7 @@ const { handleStart, handleFanout, handleRead } = require('../src/cli-handlers-r
 const { handleResume, handleContinue } = require('../src/cli-handlers-resume-continue');
 const { isOneShotCommand, armExitWatchdog } = require('../src/utils/lifecycle');
 const { suggestCommand } = require('../src/utils/input-validators');
+const { unknownFlags, getKnownFlags } = require('../src/utils/known-flags');
 const { logger } = require('../src/utils/logger');
 
 const VERSION = require('../package.json').version;
@@ -30,6 +31,28 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const command = args._[0];
 
+  // Reject unknown flags BEFORE anything can act on a half-understood command
+  // line. parseArgs accepts any `--token`, so an unrecognized one used to land
+  // on `args`, go unread, and let the command run as though it were never typed
+  // — `start … --headless` silently took the interactive path, ignored `--model`
+  // and left a session running. Same treatment as an unknown command: name it,
+  // suggest the nearest real flag, point at help, exit 1. See
+  // src/utils/known-flags.js for what counts as known and why.
+  const badFlags = unknownFlags(args);
+  if (badFlags.length > 0) {
+    for (const flag of badFlags) {
+      console.error(`Unknown option: --${flag}`);
+      const candidates = suggestCommand(flag, [...getKnownFlags()]);
+      if (candidates.length > 0) {
+        console.error(`Did you mean: ${candidates.map(c => `--${c}`).join(', ')}`);
+      }
+    }
+    console.error(command
+      ? `Run \`amicus ${command} --help\` to see valid options.`
+      : 'Run `amicus --help` to see valid options.');
+    process.exit(1);
+  }
+
   // Install crash handler for MCP-spawned processes (have --task-id)
   if (args['task-id'] && (command === 'start' || command === 'continue')) {
     const { installCrashHandler } = require('../src/sidecar/crash-handler');

package/docs/usage.md

@@ -443,7 +443,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [

package/src/cli.js

@@ -122,10 +122,12 @@ function parseArgs(argv) {
 }
 
 /**
- * Check if a flag is boolean (doesn't take a value)
+ * Flags that take no value. Module-level (not rebuilt per call) so
+ * `getBooleanFlags()` can hand the same list to src/utils/known-flags.js —
+ * which needs it to tell a real boolean flag from an unknown token, and must
+ * not keep a second copy that can rot out of sync with this one.
  */
-function isBooleanFlag(key) {
-   const booleanFlags = [
+const BOOLEAN_FLAGS = [
      'no-ui',
      'no-mcp',
      'no-context',
@@ -156,8 +158,21 @@ function isBooleanFlag(key) {
      'ui',                   // watch: open the Council Workspace window; v4.4 seam (v4.3 Task 11)
      'follow',               // fanout / council run: stream this run's own events to stderr (v4.3 Task 13)
      'fallback',             // fanout / council run: opt-in cheaper-model substitution (v4.3 Task 18, spec 6.2); --no-fallback negates via the generic no-* catch-all below
-   ];
-  return booleanFlags.includes(key);
+];
+
+/**
+ * Check if a flag is boolean (doesn't take a value)
+ */
+function isBooleanFlag(key) {
+  return BOOLEAN_FLAGS.includes(key);
+}
+
+/**
+ * The boolean-flag names, for the unknown-flag check.
+ * @returns {string[]} copy — callers must not mutate the source list
+ */
+function getBooleanFlags() {
+  return [...BOOLEAN_FLAGS];
 }
 
 /**
@@ -765,5 +780,6 @@ module.exports = {
   validateStartArgs,
   getUsage,
   getCommandNames,
+  getBooleanFlags,
   DEFAULTS
 };

package/src/utils/known-flags.js

@@ -0,0 +1,90 @@
+// src/utils/known-flags.js
+'use strict';
+
+/**
+ * @module utils/known-flags
+ * The set of `--flags` amicus accepts, and the check that rejects the rest.
+ *
+ * WHY THIS EXISTS. `parseArgs` (src/cli.js) treats ANY `--token` as a flag: an
+ * unrecognized one lands on the parsed object, no handler reads it, and the
+ * command proceeds as if it were never typed. Found in the field while smoke-
+ * testing v4.5.2 — `amicus start -m deepseek --prompt "…" --headless` printed no
+ * error and exited 0, but `start` has no `--headless`. The run silently took the
+ * INTERACTIVE path, ignored `-m`, and left a session running against the default
+ * model. A typo (`--modl`), a flag borrowed from another command, or an invented
+ * one all behave the same way, and an unknown flag followed by a positional
+ * SWALLOWS it as its value.
+ *
+ * amicus already handles an unknown COMMAND correctly — error, "Did you mean",
+ * usage, exit 1. This gives flags the same treatment.
+ *
+ * DERIVED, NOT HAND-MAINTAINED. The bulk of the set is scraped from the usage
+ * text, which is the same source `getCommandNames()` uses and for the same
+ * stated reason: a second hand-maintained list would rot out of sync with the
+ * first. Only flags that are deliberately absent from usage are listed here, and
+ * each says why.
+ */
+
+/**
+ * Real flags that appear in NO usage block. Rejecting any of these would break
+ * working callers, so they are enumerated deliberately rather than derived.
+ *
+ * ⚠️ The first four are spawned by the MCP server onto its own CLI children
+ * (src/mcp-server.js, src/mcp-council-run.js). They are not user-facing and are
+ * intentionally undocumented — but they are on the argv of every MCP-launched
+ * run, so rejecting them would break the entire MCP surface.
+ */
+const INTERNAL_FLAGS = new Set([
+  'task-id',         // MCP → `start`/`continue`: pins the child's task id
+  'run-id',          // MCP → `council run`: pins the child's run id
+  'council-name',    // MCP → `council run`: preset name for ledger attribution
+  'cowork-process',  // MCP → `start`: Cowork process handle for context capture
+
+  // User-facing but undocumented, and read by real handlers today. Listed so the
+  // rejection is a bug fix and not a silent removal of working behaviour; if any
+  // of these should be dropped, that is a separate, deliberate change.
+  'briefing',        // src/cli-handlers-resume-continue.js — alias for --prompt
+  'mode',            // src/cli-handlers-run.js — legacy alias for --agent
+  'quiet',           // src/cli-handlers.js — suppresses the interactive prompt
+  'help',            // handled before dispatch; never reaches a usage block body
+]);
+
+/**
+ * Every flag amicus accepts: usage-derived ∪ boolean flags ∪ INTERNAL_FLAGS.
+ *
+ * Computed on each call rather than cached at module load, because `getUsage()`
+ * is itself composed at call time and a cached copy would pin whatever the first
+ * caller happened to see.
+ *
+ * @returns {Set<string>} kebab-case flag names, without the leading `--`
+ */
+function getKnownFlags() {
+  // Required lazily: src/cli.js is the module that will consume this one, and a
+  // top-level require here would close a cycle.
+  const { getUsage, getBooleanFlags } = require('../cli');
+  const known = new Set(INTERNAL_FLAGS);
+  for (const m of getUsage().matchAll(/--([a-z][a-z0-9-]*)/gi)) {
+    known.add(m[1].toLowerCase());
+  }
+  for (const f of getBooleanFlags()) { known.add(f); }
+  return known;
+}
+
+/**
+ * The unknown flags present on a parsed-argv object, in the order they were
+ * typed.
+ *
+ * Reads `__explicit` — the set parseArgs fills with every key it saw on the
+ * command line — so defaults (which are merged in from DEFAULTS and were never
+ * typed) are correctly ignored.
+ *
+ * @param {object} parsed result of parseArgs()
+ * @returns {string[]} kebab-case flag names, without the leading `--`
+ */
+function unknownFlags(parsed) {
+  if (!parsed || !parsed.__explicit) { return []; }
+  const known = getKnownFlags();
+  return [...parsed.__explicit].filter(f => !known.has(String(f).toLowerCase()));
+}
+
+module.exports = { getKnownFlags, unknownFlags, INTERNAL_FLAGS };