amicus 1.8.0 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,13 +1,12 @@
 {
   "name": "amicus",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "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"
   },
   "homepage": "https://bourbondog.github.io/amicus/",
   "repository": "https://github.com/BourbonDog/amicus",
-  "bugs": "https://github.com/BourbonDog/amicus/issues",
   "license": "MIT",
   "keywords": [
     "claude-code",

package/CHANGELOG.md

@@ -5,6 +5,154 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-07-03
+
+Engine pull-forwards, release-rail hardening, docs sync, and a new Council Review GitHub Action.
+
+### Added
+- **`/amicus:council` slash command and a `/amicus:sidecar <model> <prompt…>` argument surface.** `commands/council.md`
+  wraps the `second-opinion` skill end-to-end via `$ARGUMENTS`; `skills/sidecar/SKILL.md` gained an
+  `argument-hint` and a slash-invocation section binding `$1` (model alias, falling back to gemini for
+  non-model-looking input) and `$ARGUMENTS` (full prompt). **Slash commands are plugin-channel-only:**
+  `commands/` ships in the npm tarball (via `package.json`'s `files` array) but the npm/`install.sh`/
+  `install.ps1` postinstall flow never copies it into a Claude Code commands directory — only
+  `skills/sidecar` and `skills/second-opinion` are installed that way. npm/postinstall users do not get
+  `/amicus:council` or `/amicus:sidecar`; only plugin installs (`claude plugin install`) do. This is a
+  known, accepted gap, not a bug — carried forward from the 9.1 review as a note that must keep
+  reappearing in release-facing docs so it doesn't get silently "fixed" into a false claim.
+- **MCP Registry wiring.** `package.json` gained `mcpName: "io.github.BourbonDog/amicus"`; `server.json`
+  (repo root) describes the stdio launch (`npx amicus mcp`). `.github/workflows/publish.yml` now publishes
+  to `registry.modelcontextprotocol.io` via `mcp-publisher`, authenticated over the same GitHub OIDC token
+  used for npm Trusted Publishing — no registry secret required. This fires automatically on every `v*` tag
+  push, strictly after `npm publish` succeeds (npm-side ownership validation reads the published
+  `package.json`). See `docs/DISTRIBUTION.md` §3 for the full flow, the release-order dependency on the
+  Phase 4 tool-surface de-bloat, and the manual recovery path if the registry publish fails in CI.
+- **Marketplace submission runbook and preflight guard.** `docs/DISTRIBUTION.md` documents the
+  `claude-community` submission process (individual-author Console form route), the preflight checklist
+  (`claude plugin validate . --strict`, `claude --plugin-dir .` smoke test, `npm test`), and what the
+  Anthropic review pipeline is expected to check.
+- **Council Review GitHub Action (v1).** A new reusable, label-gated workflow (`.github/workflows/council-review.yml`)
+  runs an `amicus fanout` review wave (default cheap bench `deepseek,gemini,glm`, cost- and time-bounded) over a
+  pull request's diff and posts one sticky synthesis comment with the individual reviews collapsed underneath. v1 is
+  fanout-only — independent reviews plus a one-leg synthesis, no adjudicated verdict (that needs the skill-orchestrated
+  Stage-2 cross-review, which a code-only pipeline can't produce; deferred to v2). Fork-safe and no-checkout by
+  design: PR code is never checked out or executed, only its diff (capped, via `gh pr diff`) is read; the job soft-skips
+  with a notice when `OPENROUTER_API_KEY` is unavailable (e.g. a fork PR without repo secrets) rather than failing the
+  check; every use of PR-controlled text (title/body) reaches the shell only through `env:` indirection, never inlined
+  into a `run:` script. Untrusted model output is neutralized before it enters the PR comment — case-insensitive,
+  whitespace-tolerant rules strip anything that could forge the sticky-comment marker (and hijack the next run's
+  update), forge the "not an adjudicated verdict" footer disclosure, or break out of the comment's own `<details>`
+  wrapper — and the real footer is echoed last, after all model text, so its position can't be forged. The label
+  gate (`council-review`) is enforced with a string-safe comparison (`format('{0}', inputs.require_label) == 'false'`)
+  to avoid a loose-equality bug where GitHub coerces an empty `pull_request`-event input to falsy and would otherwise
+  bypass the gate on every same-repo PR. **Inert by default:** the workflow only runs once a repo both adds the
+  `OPENROUTER_API_KEY` Actions secret and applies the `council-review` label to a PR — installing it does nothing on
+  its own. Locked by `tests/scripts/council-review-workflow.test.js`.
+
+### Changed
+- **Every prose channel that returns another model's output is now wrapped in the
+  `<untrusted_sidecar_output>` fence** (`amicus_status`/`amicus_list` previews remain sanitized-and-truncated
+  instead, by design — `sanitizePreview()` in `src/sidecar/progress-fields.js` defangs fence/tag characters
+  and caps length so the full untrusted text is only ever reachable through the fenced `amicus_read` path),
+  extending the protection `amicus_read` summaries already had: MCP wave and conversation reads, CLI
+  `amicus read` summary/conversation/wave output, and the foreground summary echo after
+  `start`/`continue`/`resume`. This is visible in CLI output. JSON output (`--json`), metadata mode, and
+  on-disk artifacts (`wave.json`, `summary.md`, `conversation.jsonl`) are byte-identical to before — the
+  fence is applied only at output time, never at write time.
+- Internal: `interactive.js`'s Electron process helpers extracted to `src/sidecar/interactive-process.js`
+  (size-gate headroom; no behavior change).
+
+### Fixed
+- **`plugin.json`'s unrecognized `bugs` field removed.** `claude plugin validate . --strict` now passes
+  clean (exit 0); it previously reported an unknown-field warning that `--strict` promotes to an error.
+- **The Fold handoff is now documented operationally** (README + usage.md): the `[SIDECAR_FOLD]` stdout
+  block, where the summary lands (`summary.md`), and how the orchestrator reads it back (fenced, via
+  `amicus read`/`amicus_read`).
+- **README↔usage.md drift corrected against the binary:** `amicus fanout` documents `--council`
+  (mutually exclusive with `--models`, exactly one required) in both files; `amicus list --status`
+  documents the full 7-value set (`running, complete, error, timed-out, aborted, crashed, idle-timeout`)
+  — note the `--json` schema's distinct `timeout` vocabulary is deliberately unchanged; fanout
+  `--session-id` support documented; `amicus status` gained real human and `--json` output examples;
+  `start --setup` documented as NOT relaxing the `--prompt`/`--prompt-file` requirement (with the exact
+  error string users see).
+- **OpenRouter 402 recovery** added to the README troubleshooting table and docs/troubleshooting.md:
+  key save/validation never checks account balance, so the first council review / `start` / `fanout` call
+  can 402 (the `amicus council` subcommand itself is deterministic math and never calls a model) — recovery
+  via openrouter.ai/credits, `:free` models, and the non-blocking `amicus doctor` credit probe.
+- docs/DISTRIBUTION.md's stale `/v0.1/` registry API path synced to `/v0/`.
+- All of the above locked by `tests/docs-quick-sync.test.js` (17 pins).
+- **Closing the GUI window no longer loses the session summary.** Closing without folding previously
+  destroyed the window immediately — the session finalized as `complete` with a placeholder summary, and
+  closing during an in-flight fold discarded the summary about to land. The window close is now intercepted
+  by a close guard (`electron/close-guard.js`): a close with no fold auto-triggers the same fold flow
+  (overlay + summary + `[SIDECAR_FOLD]` handoff) and then closes; a close during an in-flight fold lets it
+  finish — regardless of whether the fold was close-initiated or started from the toolbar/shortcut — instead
+  of falling through and destroying the window mid-summary; a failed or timed-out fold still closes the
+  window (the user is never trapped). This relies on `electron/fold.js` exposing a finer-grained
+  `isFolding()`/`hasCompleted()` split (a fold is "in flight" from the moment `triggerFold` is entered until
+  its `[SIDECAR_FOLD]` stdout write actually succeeds) alongside the original `hasFolded()`, so the guard can
+  tell "still running" apart from "actually done" — and a fold that settles without completing (including a
+  synchronous throw from the post-write nudge-overlay update, which the old code's `.catch()` couldn't
+  observe) still safely falls back to closing the window rather than leaving it permanently stuck open.
+  External abort remains immediate and never waits on a fold.
+- **The MCP server no longer hardcodes `--client cowork`.** Under Claude Code — the primary caller — that
+  hardcode silently broke `includeContext:true` (empty context), parent-MCP discovery, and session-dir
+  resolution. The server now detects its caller from the MCP handshake's `clientInfo` (claude-code →
+  `code-local`; Claude Desktop/Cowork → `cowork`; unknown callers keep today's `cowork` behavior with a
+  one-time stderr notice) and threads the detected client through every spawn path and the in-process
+  shared-server path. A new `AMICUS_MCP_CLIENT` env var (set it in the MCP registration's `env` block)
+  explicitly overrides detection. One consequence: MCP-spawned GUI chat sessions under Claude Code now keep
+  the default SE-focused base prompt — `opencode-client.js`'s Cowork-specific general-purpose prompt swap
+  (`buildCoworkAgentPrompt()`) only fires when `options.client === 'cowork'`, which no longer matches a
+  Claude Code caller now that it's correctly tagged `code-local`.
+- **Release-workflow re-runs now recover a half-published release instead of dead-ending.** A `publish.yml`
+  re-run after a post-`npm publish` failure previously died on `EPUBLISHCONFLICT` before ever reaching the
+  step that failed. Now the npm publish is skipped (loudly) when `amicus@<version>` is already live (E404
+  means not-published and proceeds; any other `npm view` error fails loud rather than skipping), a
+  tag↔`package.json` lockstep check fails fast before anything publishes, the MCP Registry publish is
+  skipped when the version is already registered (pre-check tolerates transport-level failures and falls
+  through to publishing), `mcp-publisher login github-oidc` gained the same 5×20s retry the publish call
+  already had, and `gh release create` is guarded by an existence check. `docs/DISTRIBUTION.md` §3 now
+  documents re-run as the primary recovery path, with the manual path as fallback. Locked by
+  `tests/scripts/publish-workflow.test.js`.
+- **The `second-opinion` skill's frontmatter description no longer exceeds Claude Code's 1024-char cap.**
+  It was 1441 chars, so the router silently truncated the tail — which was the NOT-clause routing quick
+  single-model asks ("ask Gemini…", "what does DeepSeek think") to the `sidecar` skill. Rewritten to
+  988 chars with every trigger phrase and the NOT boundary intact (same fix pattern as the sidecar skill's
+  1.8.1 overhaul); locked by `tests/skill-second-opinion-docs.test.js`. Existing installs pick the fix up
+  when postinstall refreshes skill copies on the next upgrade.
+
+## [1.8.1] - 2026-07-02
+
+Docs & skills accuracy sprint from the Phase-8 whole-branch review — no engine changes. Every item fixed a claim
+that actively misdirected Claude or users, plus one headless completion-state bugfix.
+
+### Changed
+- **`report.html` is now the default final council artifact**, and an inline verdict summary in chat is
+  MANDATORY at Stage 5 of the second-opinion skill.
+- **The `sidecar` skill's frontmatter dropped the "second opinion from another model" trigger** — those requests
+  now route to the `second-opinion` skill instead.
+- **MODEL-NOTES seed updated** with durable lessons from council runs 4-7 (new Grok/Kimi/Mistral/Claude-in-council
+  sections; shipped/local split defined). Existing installs: the machine-local copy is installed only-if-missing —
+  merge/refresh manually by pointing at the shipped file.
+- **Council mechanics hardened:** mandatory no-tools preamble for judges and chair (plus scratch-cwd advice);
+  `--max-cost` / `--no-cost-gate` pass-through documented for repair and chair calls (the false solo-start
+  cost-gate exemption was removed); `--models` lists quoted in every example; current-date injection rule for
+  time-sensitive artifacts.
+
+### Fixed
+- **Plugin quick-start now states the truth:** plugin installs do not put `amicus` on `PATH`; use
+  `npx -y amicus@latest <cmd>`. Both skills gained an npx-fallback/transport rule.
+- **README/usage now document `doctor`, `key`, and `council`;** troubleshooting leads with `amicus doctor`; the
+  false "`amicus list` shows active servers" claim is replaced with real `netstat`/`lsof` guidance.
+- **Headless runs that finish via idle detection no longer write `status:"error"` / `reason:"Incomplete"` to
+  `metadata.json`.** The poll loop's two genuine idle-completion exits — the SDK-authoritative `session.status`
+  idle signal and the stable-poll activity heuristic (both gated on real output, F1 #16) — broke out of the loop
+  without setting `completed`, so `resolveTerminalState` fell through to error and poisoned `amicus_list` /
+  `amicus_status` / wave rollups for successful runs, while the stdout `--json` doc correctly said
+  `status:"complete"`. Both exits now mark the run completed, matching the fold-marker branch. Dead-server
+  classification is unchanged: the consecutive-poll-failure fast-exit (F4) and crash paths still report an error.
+
 ## [1.8.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -57,7 +57,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 
 ## Quick start
 
-**Install** — pick whichever fits; all deliver the same CLI, MCP server, and both skills:
+**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:
 
@@ -67,7 +67,7 @@ Claude is the orchestrator. The council and chat skills run *on top of* the engi
 /reload-plugins
 ```
 
-Claude Code registers the MCP server and both skills for you — nothing to configure. (The standalone Electron window is npm-only, and the first council/sidecar call downloads the OpenCode engine.)
+Claude Code registers the MCP server and both skills for you — nothing to configure. (The plugin does not put `amicus` on your PATH — CLI calls go through `npx -y amicus@latest <command>`; the standalone Electron window is npm-only; and the first council/sidecar call downloads the OpenCode engine.)
 
 **With the install script** — macOS, Linux, or Windows (needs [Node.js](https://nodejs.org) ≥ 18):
 
@@ -96,6 +96,8 @@ For the **npm** and **install-script** paths, a postinstall auto-configures ever
 
 ```bash
 amicus setup
+# plugin-only install (no CLI on PATH):
+npx -y amicus@latest setup
 ```
 
 This opens a graphical wizard:
@@ -113,7 +115,7 @@ This opens a graphical wizard:
 
 > *council review this*
 
-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 installed in the previous step is what teaches Claude to recognize this — if nothing happens, confirm it landed in `~/.claude/skills/second-opinion/`.)
+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:
 
@@ -224,6 +226,8 @@ When you don't need a full council — just one other model's take — fork a co
 
 **Headless (`--no-ui`):** the agent works autonomously and emits the fold summary when it finishes — ideal for bulk work like test generation or documentation. Pair with `--json` for a machine-readable run document.
 
+**How the fold handoff actually works.** A fold is a summary handoff, not a live handback — once you fold, the sidecar model's context is gone. Mechanically: clicking **FOLD** asks the model for a structured summary, then writes it to the Electron process's stdout as a `[SIDECAR_FOLD]`-tagged block; the amicus runner that spawned Electron captures that stdout and persists it as the session's `summary.md` (under the session directory, alongside `metadata.json` and `conversation.jsonl`). Nothing pushes the result back to you automatically — your orchestrating agent picks it up on request, via `amicus read <taskId>` (CLI) or the `amicus_read` MCP tool. Either path returns the summary wrapped in an `<untrusted_sidecar_output>` fence, since it's prose from another model entering your context and should be treated as data, not instructions.
+
 **Context sharing.** Your conversation history is passed automatically. Tune it:
 
 - `--context-turns <N>` — max conversation turns to include (default 50).
@@ -261,6 +265,9 @@ amicus update
 | `amicus read` | Output a session's summary / conversation / metadata. |
 | `amicus status <id>` | One-shot status for a session or fan-out wave (human or `--json`; `--wave <id>` alternative spelling). |
 | `amicus models` | List, search, refresh the catalog, or audit aliases. |
+| `amicus doctor` | Diagnose your setup — keys, default model, catalog, aliases, OpenCode binary, Electron, skills, MCP registration, OpenRouter credit (`--json`; `--fix` self-heals what it can). |
+| `amicus key` | Manage API keys non-interactively: `amicus key <provider> <key>` saves after live validation; `--remove`; bare `amicus key` lists providers. |
+| `amicus council` | Council math: `tally <input.json>` (deterministic tiers + ledger append), `stats` (reviewer reliability), `report <verdict.json> [--md\|--html]`. |
 | `amicus abort` | Abort a running session (or `--all`). |
 | `amicus setup` | Configure default model, API keys, and aliases. |
 | `amicus update` | Update to the latest version. |
@@ -296,7 +303,7 @@ The `am` alias is interchangeable with `amicus` everywhere.
 | `--fold-shortcut <key>` | Customize the fold keyboard shortcut. | `Cmd/Ctrl+Shift+F` |
 | `--opencode-port <port>` | Port override for the OpenCode server. | |
 | `--session-dir <path>` | Explicit session-data directory. | |
-| `--setup` | Force-open configuration before launching. | |
+| `--setup` | Force-open configuration before launching. Does **not** relax the `--prompt`/`--prompt-file` requirement — `start --setup` still fails fast with "Error: --prompt or --prompt-file is required" if neither is given. | |
 | `--no-validate-model` | Skip model-catalog validation before launch. | validation on |
 
 > Agents: **Chat** auto-approves reads and asks before writes/bash (interactive default); **Build** has full tool access (headless default); **Plan** is read-only analysis. `--agent Chat` is interactive-only and incompatible with `--no-ui`.
@@ -304,7 +311,7 @@ The `am` alias is interchangeable with `amicus` everywhere.
 ### `amicus fanout` — same prompt, many models
 
 ```bash
-amicus fanout --models gemini,deepseek,gpt --prompt "Review this design" --json
+amicus fanout --models "gemini,deepseek,gpt" --prompt "Review this design" --json
 ```
 
 Fanout runs one **headless wave**: every leg gets the **same** prompt (this is the shared-prompt model the council's review stages are built on). When all legs are terminal it prints **one** JSON wave document on stdout.
@@ -314,6 +321,7 @@ Fanout runs one **headless wave**: every leg gets the **same** prompt (this is t
 - `--prompt <text>` / `--prompt-file <path>` — the shared briefing. `--prompt-file` avoids the ~32 KB Windows argument cap and is mutually exclusive with `--prompt`.
 - `--wave-id <id>` — set the wave ID explicitly (leg IDs become `<id>-1..N`).
 - `--json` — emit the wave document.
+- `--session-id <id|current>` — session to pull shared context from (same as `start`; supported on `fanout` too).
 - Shared per-leg knobs: `--agent`, `--thinking`, `--timeout`, `--summary-length`, `--no-context`, the `--context-*` flags, the `--mcp*` flags, `--no-validate-model`, `--cwd`.
 - **Exit codes:** `0` all legs complete, `2` partial wave, `1` none complete / hard failure.
 
@@ -321,7 +329,8 @@ Fanout runs one **headless wave**: every leg gets the **same** prompt (this is t
 
 ```bash
 amicus list                          # current project
-amicus list --status running         # filter by status (running, complete)
+amicus list --status running         # filter by status: running, complete, error,
+                                      # timed-out, aborted, crashed, idle-timeout
 amicus list --all                    # all projects
 amicus list --json                   # machine-readable
 
@@ -344,6 +353,32 @@ amicus setup --api-keys              # open just the API-key window
 amicus setup --add-alias fast=openrouter/google/gemini-2.5-flash   # add/override one alias
 ```
 
+**`amicus status <id>` output.** Human-readable:
+
+```
+$ amicus status demo123
+Task:     demo123
+Status:   complete (terminal)
+Elapsed:  5m 0s
+Model:    google/gemini-2.5-flash
+```
+
+`--json`:
+
+```
+$ amicus status demo123 --json
+{
+  "taskId": "demo123",
+  "status": "complete",
+  "elapsed": "5m 0s",
+  "version": "1.9.0",
+  "model": "google/gemini-2.5-flash",
+  "phase": "terminal"
+}
+```
+
+A running session additionally reports `messages`, `lastActivity`/`latest`, and (if stalled) a `STALLED` line with recovery guidance in `--json`. A wave ID (`amicus status <waveId>` / `--wave <waveId>`) instead reports `legsComplete`/`legsTotal` and a per-leg breakdown.
+
 ---
 
 ## Models
@@ -429,6 +464,7 @@ claude mcp add-json amicus '{"command":"npx","args":["-y","amicus@latest","mcp"]
 | `AMICUS_CONFIG_DIR` | Override the config directory (keys, catalog, sessions). | `~/.config/amicus` |
 | `AMICUS_FANOUT_MAX_LEGS` | Cap the number of legs in a single fanout wave; non-positive values fall back to 10. | `10` |
 | `AMICUS_SHARED_SERVER` | When `1`, multiple MCP sessions share a single OpenCode Go process, eliminating cold-start latency. Set to `0` for per-process isolation or to diagnose a crash loop. | `1` |
+| `AMICUS_MCP_CLIENT` | Override the auto-detected MCP caller (`code-local`, `code-web`, or `cowork`). Amicus detects Claude Code vs. Claude Desktop/Cowork from the MCP `initialize` handshake; set this only if detection picks the wrong one. Note: `code-web` requires an explicit `--session-dir` and is not usable for MCP-spawned sessions. | auto-detected |
 
 **Headless poller tuning** (advanced — rarely needed)
 
@@ -505,6 +541,7 @@ Most Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.
 | `npm install -g amicus` fails with `EEXIST: … claude-sidecar` | The old upstream `claude-sidecar` package is still installed globally; npm won't overwrite another package's bin shims | `npm uninstall -g claude-sidecar`, then `npm install -g amicus`. Your config and sessions carry over (legacy paths are still read). |
 | Install fails partway, or `amicus doctor` reports the OpenCode binary "not found" | A **transient** error during the OpenCode engine's own postinstall (a spawn `ENOENT`, or an antivirus file-lock while it lays down its 11 per-platform binaries) can roll back the whole atomic install — retrying usually succeeds | Just re-run `npm install -g amicus`. If it still fails, clear the cache first: `npm cache clean --force && npm install -g amicus`. |
 | `401` / auth error | API key missing, or the model prefix doesn't match the key you have | Run `amicus setup`; make sure the prefix (`openrouter/…` vs `google/…` vs `openai/…` vs `anthropic/…`) matches the credentials you configured. |
+| `402` / "Payment Required" on first council review / `start` / `fanout` call | Your OpenRouter key is real but has no credit. Key save (`amicus key openrouter <key>` or the setup wizard's key step) only checks that the key **authenticates** — it doesn't check balance, so a zero-credit key saves cleanly and only fails later, on the first real model call. (The `amicus council` subcommand itself is deterministic math and never calls a model.) | Add credit at [openrouter.ai/credits](https://openrouter.ai/credits), **or** switch to a zero-cost council: `amicus setup` → option 2 (Free OpenRouter council) builds one from live `:free`-suffixed models and saves it as `councils.free` — then run `amicus fanout --council free …`. See "Free council (zero-cost)" under [The Council](#the-council) above. |
 | Session not found | No session matches the given ID | Run `amicus list`, or omit `--session-id` to use the most recent. |
 | No conversation history found | Project-path encoding | Check `~/.claude/projects/`; `/` and `_` in the project path are encoded as `-` in the directory name. |
 | Headless run never finishes | Task is bigger than the default timeout | Raise it: `--timeout 30`. |

package/commands/council.md

@@ -0,0 +1,22 @@
+---
+description: Run a structured multi-model LLM council review of the given material — wraps the second-opinion skill (independent reviews → anonymous cross-review → non-Claude chair verdict → accept/deny decisions).
+argument-hint: [material, path, or URL] [analysis request + criteria]
+disable-model-invocation: true
+---
+
+Run a full council review by invoking the `second-opinion` skill shipped in this
+plugin (listed as `amicus:second-opinion`). Do not synthesize a verdict yourself —
+the skill's chair model does that; you orchestrate.
+
+Treat everything the user typed after the command as the review request:
+
+$ARGUMENTS
+
+Interpret it as three inputs: the **material** (inline text, a file path, or a URL),
+the **analysis request**, and the **criteria**. If any of the three is missing or
+ambiguous, ask for it before launching any model (the skill's Stage 0 covers this —
+don't re-ask for what is already present).
+
+Then follow the second-opinion skill end to end: Stage 0 intake/prep and run-folder
+setup, council selection with a cost estimate and explicit user confirmation, the
+three review waves, `amicus council tally`, and the accept/deny decision pass.

package/electron/close-guard.js

@@ -0,0 +1,140 @@
+/**
+ * Close Guard — auto-fold on window close (backlog B01)
+ *
+ * `mainWindow.on('close', ...)` used to destroy the window immediately
+ * whenever no fold had run yet, silently discarding the session summary on
+ * the most common "I'm done, close the window" path (red X / Cmd|Ctrl+Q /
+ * window-all-closed). createCloseGuard() centralizes the decision so it can
+ * be unit-tested without booting Electron:
+ *
+ *  - No fold attempted yet: prevent the destroy, invoke the SAME triggerFold
+ *    closure (fold.js's own `folded` flag guards re-entrancy — this module
+ *    never constructs a second fold handler). triggerFold's existing success
+ *    path already closes the window itself; its failure path resets
+ *    folded=false.
+ *  - Fold already IN FLIGHT: prevent the destroy and let the in-flight fold
+ *    finish and close the window on its own — regardless of who started it
+ *    (a second user close during an auto-fold, or a close during a
+ *    toolbar/shortcut-initiated fold, must both be blocked; a single
+ *    `hasFolded()`-style flag that goes true at triggerFold ENTRY cannot
+ *    distinguish in-flight from done, so this relies on fold.js's finer
+ *    `isFolding()`/`hasCompleted()` split instead).
+ *  - Fold already COMPLETED (the `[SIDECAR_FOLD]` stdout write actually
+ *    succeeded): proceed exactly like the pre-existing behavior (no
+ *    interception).
+ *  - A close-initiated fold SETTLES WITHOUT COMPLETION — whether triggerFold
+ *    rejects, or its outer catch swallows the error and resolves (e.g. the
+ *    nudge-overlay executeJavaScript call throws synchronously on a
+ *    destroyed webContents; fold.js's trailing `.catch()` there only guards
+ *    promise rejection, not a sync throw) — fall back to the pre-existing
+ *    destroy path so the user is never trapped with a window that can no
+ *    longer be closed. A latch ensures the fallback destroy is not
+ *    re-intercepted by this same guard, and a second rapid close click while
+ *    a fold is in flight does not spawn another fold.
+ *
+ * This module is intentionally ignorant of external abort — `amicus abort` /
+ * MCP amicus_abort SIGTERMs the Electron child process directly
+ * (src/sidecar/interactive-abort.js killElectron), which is an OS-level kill
+ * of the whole process, not a call into any renderer 'close' handler. Node
+ * terminates immediately on SIGTERM unless the process itself installs a
+ * 'SIGTERM' listener; main.js installs none, so that teardown can never route
+ * through this guard.
+ */
+
+/**
+ * @param {object} deps
+ * @param {() => boolean} deps.hasFolded - fold.js's original entry-to-settle
+ *   flag (kept for API-compatibility with other hasFolded() consumers; not
+ *   used to gate the close decision here since it can't distinguish
+ *   in-flight from done).
+ * @param {() => boolean} [deps.isFolding] - Whether a fold is currently IN
+ *   FLIGHT (entered but not yet completed). Falls back to `hasFolded()` when
+ *   omitted, preserving the pre-fix (buggy) behavior for any caller that
+ *   hasn't upgraded — but main.js always passes fold.js's real isFolding().
+ * @param {() => boolean} [deps.hasCompleted] - Whether the fold's
+ *   `[SIDECAR_FOLD]` stdout write has actually succeeded. Falls back to
+ *   `hasFolded()` when omitted.
+ * @param {(mainWindow: object, contentView: object) => Promise<void>} deps.triggerFold
+ *   - The SAME fold.js closure used by the shortcut/toolbar/IPC paths.
+ * @returns {{ handleClose: (event: object, mainWindow: object, contentView: object) => void }}
+ */
+function createCloseGuard({ hasFolded, isFolding, hasCompleted, triggerFold }) {
+  const checkIsFolding = isFolding || hasFolded;
+  const checkHasCompleted = hasCompleted || hasFolded;
+
+  // Tracks whether THIS guard has already kicked off a close-initiated fold
+  // attempt (in flight or settled-but-not-yet-fallen-back). Separate from
+  // fold.js's own `folded` re-entrancy flag: this latch additionally prevents
+  // a second fold attempt or a preventDefault loop around the fallback
+  // destroy once the close-initiated fold has failed.
+  let closeFoldAttempted = false;
+  let fallbackFired = false;
+
+  function destroyIfPossible(mainWindow) {
+    if (fallbackFired) { return; }
+    fallbackFired = true;
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.destroy();
+    }
+  }
+
+  function handleClose(event, mainWindow, contentView) {
+    if (checkHasCompleted()) {
+      // Fold already completed — proceed exactly like the pre-existing
+      // behavior (no interception, no destroy call from the guard itself;
+      // Electron's default close-then-'closed' sequence runs normally).
+      return;
+    }
+
+    if (fallbackFired) {
+      // The close-initiated fold already failed/timed out and the fallback
+      // destroy has already fired (or is in flight). Do not re-intercept —
+      // let this close event proceed so an already-invoked destroy()
+      // re-entering 'close', or a straggling user click, cannot loop.
+      return;
+    }
+
+    // Not completed yet — either no fold has been attempted, or one is
+    // in flight (close-initiated or toolbar/shortcut-initiated). Either way
+    // the destroy must be prevented so an in-flight summary is never
+    // discarded out from under it.
+    event.preventDefault();
+
+    if (checkIsFolding() || closeFoldAttempted) {
+      // A fold is already in flight (from this guard's own close-initiated
+      // attempt, or from the toolbar/shortcut path) — do not spawn a second
+      // one. Let it finish; its own success path closes the window, and if
+      // it settles without completing, the .then() below falls back to
+      // destroy so the window never gets permanently stuck open.
+      return;
+    }
+    closeFoldAttempted = true;
+
+    Promise.resolve(triggerFold(mainWindow, contentView)).then(() => {
+      // triggerFold can RESOLVE without ever calling mainWindow.close() —
+      // its outer catch swallows failures (including a synchronous throw
+      // from the post-write nudge-overlay executeJavaScript call, which can
+      // land AFTER the stdout write already flipped completed=true) and
+      // returns normally instead of rejecting. fold.js's catch always resets
+      // its `folded` flag back to false in that path, and only in that path
+      // — the success path that actually reaches mainWindow.close() leaves
+      // `folded` true. So hasFolded() being false here is the reliable
+      // "settled without the window actually closing" signal, independent
+      // of hasCompleted() (the summary can be safely on stdout while the
+      // window itself never got closed). Skipping this check and trusting
+      // completion alone would leave the window with no further close
+      // handler able to fire — permanently open.
+      if (!hasFolded()) {
+        destroyIfPossible(mainWindow);
+      }
+    }, () => {
+      // Close-initiated fold rejected outright. Never trap the user: fall
+      // back to the original destroy path.
+      destroyIfPossible(mainWindow);
+    });
+  }
+
+  return { handleClose };
+}
+
+module.exports = { createCloseGuard };

package/electron/fold.js

@@ -19,14 +19,23 @@ const { tokenCss } = require('../src/design/tokens');
  * @param {string} state.sessionId - OpenCode session ID
  * @param {string} state.taskId - Sidecar task ID
  * @param {number} state.port - OpenCode server port
- * @returns {{ triggerFold: Function, hasFolded: Function }}
+ * @returns {{ triggerFold: Function, hasFolded: Function, isFolding: Function, hasCompleted: Function }}
  */
 function createFoldHandler(state) {
+  // `folded` is set synchronously at triggerFold ENTRY and covers both
+  // "in flight" and "done" — this is `hasFolded()`'s existing external
+  // contract (main.js wires it straight into createCloseGuard's `hasFolded`
+  // dep) and must not change. `completed` is the finer-grained signal: it
+  // only flips true AFTER the `[SIDECAR_FOLD]` stdout write actually
+  // succeeds, so callers that need to distinguish "still running" from
+  // "actually done" (close-guard.js) use isFolding()/hasCompleted() instead.
   let folded = false;
+  let completed = false;
 
   async function triggerFold(mainWindow, contentView) {
     if (folded) { return; }
     folded = true;
+    completed = false;
 
     // Show fold progress in toolbar and content overlay
     showFoldOverlay(mainWindow, contentView);
@@ -54,6 +63,7 @@ function createFoldHandler(state) {
       ].join('\n');
 
       process.stdout.write(output + '\n');
+      completed = true;
       logger.info('Fold completed', { taskId: state.taskId });
 
       // Show nudge overlay before closing
@@ -76,6 +86,17 @@ function createFoldHandler(state) {
       await new Promise(resolve => setTimeout(resolve, 2500));
     } catch (err) {
       logger.error('Fold failed', { error: err.message });
+      // Reset re-entrancy so a later close/shortcut/toolbar click can retry.
+      // NOTE: this can fire AFTER the `[SIDECAR_FOLD]` stdout write already
+      // succeeded (completed = true, set above) if the post-write nudge-overlay
+      // executeJavaScript call throws SYNCHRONOUSLY on a destroyed webContents
+      // (the trailing .catch() on that call only guards promise rejection, not
+      // a synchronous throw) — the summary is safely on stdout in that case,
+      // but the window was never closed by this run, so folded must still
+      // reset to let a fallback close proceed. completed is left as-is:
+      // close-guard.js checks it independently to decide whether a pending
+      // close can simply proceed (summary already landed) or must fall back
+      // to destroy (summary never made it out).
       folded = false;
       return;
     }
@@ -93,7 +114,23 @@ function createFoldHandler(state) {
     return folded;
   }
 
-  return { triggerFold, hasFolded };
+  // isFolding(): true only while a fold is IN FLIGHT (entered but not yet
+  // completed) — the signal close-guard.js needs to keep a close blocked
+  // regardless of who initiated the fold (close-initiated or
+  // toolbar/shortcut-initiated), since hasFolded() alone can't distinguish
+  // in-flight from done.
+  function isFolding() {
+    return folded && !completed;
+  }
+
+  // hasCompleted(): true once (and only once) the `[SIDECAR_FOLD]` stdout
+  // write has actually succeeded — the signal close-guard.js needs to know
+  // the summary is safely handed off and a close may proceed.
+  function hasCompleted() {
+    return completed;
+  }
+
+  return { triggerFold, hasFolded, isFolding, hasCompleted };
 }
 
 /**

package/electron/main.js

@@ -18,6 +18,7 @@ const { logger } = require('../src/utils/logger');
 const { getCompatEnv } = require('../src/utils/env-compat');
 const { buildToolbarHTML, TOOLBAR_H, getBrandName } = require('./toolbar');
 const { createFoldHandler } = require('./fold');
+const { createCloseGuard } = require('./close-guard');
 const { registerSetupHandlers } = require('./ipc-setup');
 const { computeWindowPosition } = require('./window-position');
 const { attachLoadFailsafe, buildLoadErrorHTML } = require('./load-failsafe');
@@ -90,6 +91,15 @@ const foldHandler = createFoldHandler({
   taskId: TASK_ID,
   port: OPENCODE_PORT
 });
+// Auto-fold on close (backlog B01): a user-initiated window close with no
+// fold yet run must not silently discard the session summary. See
+// close-guard.js for the full design (latch, fallback, abort isolation).
+const closeGuard = createCloseGuard({
+  hasFolded: foldHandler.hasFolded,
+  isFolding: foldHandler.isFolding,
+  hasCompleted: foldHandler.hasCompleted,
+  triggerFold: foldHandler.triggerFold,
+});
 
 // ============================================================================
 // Amicus Window (OpenCode + Toolbar)
@@ -284,8 +294,8 @@ function createAmicusWindow() {
     }, 500);
   }
 
-  mainWindow.on('close', () => {
-    if (!foldHandler.hasFolded() && mainWindow) { mainWindow.destroy(); }
+  mainWindow.on('close', (event) => {
+    closeGuard.handleClose(event, mainWindow, contentView);
   });
   mainWindow.on('closed', () => {
     mainWindow = null;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "amicus",
-  "version": "1.8.0",
+  "version": "1.9.0",
+  "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": [
     "claude",
@@ -40,6 +41,7 @@
     "src/",
     "electron/",
     "skills/",
+    "commands/",
     ".claude-plugin/",
     "CHANGELOG.md",
     "scripts/postinstall.js",