amicus 1.5.0 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.5.0",
+  "version": "1.6.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/",

package/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to Amicus are documented here. Format follows
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-30
+
+Install resilience and council-failure correctness — the first two blocks of the post-1.5 backlog program.
+
+### Added
+- **Per-subcommand help.** `amicus <command> --help` now prints only that command's options instead of
+  the full global usage; bare `amicus --help` is unchanged.
+- **Zero-credit OpenRouter key warning at setup.** Setup now does a non-blocking `GET /api/v1/key`
+  check and warns when a key is free-tier or has no remaining credit, so a credit-less key is flagged
+  up front instead of 402-ing on the first paid model call.
+- **`amicus doctor` engine-recovery guidance.** The opencode-engine check now explains the
+  transient install-rollback failure mode and gives copy-paste recovery steps.
+- **Postinstall verifies the Electron binary.** When the optional Electron download/extract fails (or
+  AV quarantines the binary), the install now prints a clear non-fatal notice that headless runs and
+  the council still work — instead of silently leaving a broken GUI to discover later.
+- **CI tarball guard.** A new `check:tarball` step asserts every lifecycle-referenced script actually
+  ships in the published package, so a future packaging change can't silently drop it.
+- **README "Requirements & Dependencies" section** consolidating Node, git, OpenRouter credits, API-key
+  env vars, the optional Electron GUI, the bundled opencode engine, and OS support.
+
+### Fixed
+- **Council / headless runs no longer report success when every model call fails.** On the shared-server
+  MCP path, a run whose calls all errored (e.g. an OpenRouter 402) was finalized as `complete` with a
+  0-byte summary, so `amicus_status` showed success and the error was lost. Non-2xx/402 responses are
+  now detected at the OpenCode client boundary even when no assistant message is emitted, the
+  shared-server finalize routes through the same terminal-state classifier as the CLI, and a failed run
+  can never silently default to `complete`; `amicus_read` surfaces the failure reason.
+- **`amicus_status` elapsed time** is now bounded by the run's completed/aborted/crashed timestamp
+  instead of wall-clock-since-start, so a finished run reports its real duration.
+- **`amicus_setup` (MCP)** no longer claims an Electron window appeared when Electron is unavailable —
+  it pre-flights and returns an honest error directing you to the headless terminal wizard.
+- **Clearer "session not found"** — the message now names the resolved project so you know to pass the
+  original `project`.
+- **Non-fatal postinstall.** An internal skill-copy / MCP-registration failure no longer exits non-zero
+  and rolls back the entire global install; it warns and continues.
+- **`github:` install on Windows now runs identically to the registry install.** Removed the
+  consumer-facing `prepare` lifecycle that triggered npm's clone→prepare→nested-install→cached-pack
+  path (the rollback source); git hooks are still configured for contributors via `postinstall`.
+
+## [1.5.1] - 2026-06-29
+
+A headless-reliability fix for reasoning-heavy models.
+
+### Fixed
+- **Gemini (and other reasoning-only models) no longer hang headless with "No Output."** On the
+  direct-Google provider path, Gemini 3.x returns its answer as a `reasoning` part with no separate
+  `text` part. The conversation mirror only accumulated `text` parts, so it captured zero output, the
+  headless completion gates (which key on `output.length > 0`) never fired, and the run burned the full
+  timeout — while still billing input/thinking tokens. The mirror now accumulates reasoning into a
+  dedicated buffer and promotes it to the output **only when a finished assistant message produced no
+  visible text**, so models that emit both a reasoning part and a text part are unaffected (their
+  thinking never pollutes the answer). Fixes `--model gemini` / `gemini-pro` and any direct `google/*`
+  alias in headless `start`, `fanout`, and council runs.
+
 ## [1.5.0] - 2026-06-29
 
 A visual refresh plus a council-reliability fix and a config-dir consolidation.

package/README.md

@@ -23,6 +23,7 @@ Hand Claude a plan, a design, a diff, an architecture decision, a manuscript —
 
 - [What is Amicus](#what-is-amicus)
 - [Quick start](#quick-start)
+- [Requirements & Dependencies](#requirements--dependencies)
 - [The Council](#the-council)
 - [The parallel window](#the-parallel-window)
 - [Commands](#commands)
@@ -67,16 +68,6 @@ The postinstall step auto-configures everything — no manual registration:
 - Registers the **MCP server** in Claude Code and in Claude Desktop / Cowork, so the Amicus tools appear natively.
 - Installs **both skills** into `~/.claude/skills/` — `second-opinion` (the council) and `sidecar` (the chat skill).
 
-## Prerequisites & what it costs you
-
-Before your first run:
-
-- **Node.js ≥ 18** — `node --version` to check.
-- **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
-- **At least one paid model API key** — OpenRouter (covers the most models) or a direct Google / OpenAI / Anthropic / DeepSeek key. Add one with `amicus setup` or `amicus key <provider> <key>`.
-
-**What a run costs.** A sidecar is a single model call. A full council is typically **~5–8 paid model calls** (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with `--no-cost-gate`. You pay your providers directly for the tokens; Amicus itself is free and open-source.
-
 **Configure:**
 
 ```bash
@@ -110,18 +101,55 @@ A window opens alongside your editor with Gemini ready, pre-loaded with your con
 
 ### Install from GitHub
 
-The npm package is the primary path. To install straight from the repo instead (the postinstall runs identically — same MCP registration, same two skills):
+The npm package is the primary path. To install straight from the repo instead — the postinstall runs **identically** (same MCP registration, same two skills) — you just need `git` on your `PATH`:
 
 ```bash
 npm install -g github:BourbonDog/amicus
 ```
 
+See [Requirements & Dependencies](#requirements--dependencies) for the full prerequisite list.
+
 ### Contributor setup
 
 Cloning to develop Amicus? See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, git-hook wiring, and test commands.
 
 ---
 
+## Requirements & Dependencies
+
+Everything you need before your first run, and what's optional.
+
+**Runtime**
+
+- **Node.js ≥ 18** — `node --version` to check. This is the only hard runtime prerequisite.
+- **An active Claude Code or Cowork session** — Amicus is orchestrated by Claude; it is not a standalone chatbot.
+
+**Install path & the git toolchain**
+
+- **From the npm registry (recommended):** `npm install -g amicus`. No build toolchain required — the package ships prebuilt.
+- **From GitHub:** `npm install -g github:BourbonDog/amicus` runs **identically** — same MCP registration, same two skills, same postinstall. The one extra requirement is a working **git** on your `PATH`, since npm clones the repo to install it (`git --version` to check).
+
+**Model API keys** — at least one is required
+
+- **OpenRouter** covers the most models with one key, or use a **direct Google / OpenAI / Anthropic / DeepSeek** key. Add one with `amicus setup` or `amicus key <provider> <key>`; keys live in `~/.config/amicus/.env`. The supported env vars are `OPENROUTER_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` (the legacy `GEMINI_API_KEY` is still accepted), `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `DEEPSEEK_API_KEY`.
+- ⚠️ **OpenRouter keys need purchased credits.** A brand-new, zero-credit key *passes* setup's live validation but then fails at runtime with a **402** on the first real call. Buy a small amount of credit before you run a council.
+
+**Electron — optional (GUI only)**
+
+- Electron is an **optional** dependency. It powers the graphical setup wizard and the parallel sidecar window. **Headless runs and the full council work without it** — if Electron is absent or can't open a window, `amicus setup` falls back to a readline wizard and sidecars run headless. `amicus doctor` reports Electron's presence accurately and never treats its absence as fatal.
+
+**The OpenCode engine**
+
+- The bundled **`opencode-ai`** engine (the conversation runtime) installs automatically as a normal dependency — you don't install it separately. Its own postinstall lays down ~11 per-platform binaries; a **transient** failure there (a spawn `ENOENT`, or an antivirus file-lock) can roll back the atomic install. If install fails partway or `amicus doctor` reports the OpenCode binary "not found", just **re-run** `npm install -g amicus` (clear the cache first if it persists: `npm cache clean --force`).
+
+**OS support**
+
+- **Windows 11, macOS, and Linux** are all supported; Amicus is first-class on **Windows** (developed and tested there, no WSL required). See the [Windows](#windows) section for platform specifics.
+
+**What a run costs.** A sidecar is a single model call. A full council is typically **~5–8 paid model calls** (e.g. 3 reviewers across 2 fan-out waves + 1 chair). Amicus shows an estimate before each council and enforces a built-in budget gate that refuses ultra-expensive models (o3-pro class) unless you opt in with `--no-cost-gate`. You pay your providers directly for the tokens; Amicus itself is free and open-source.
+
+---
+
 ## The Council
 
 **Why multi-model.** Any single model — including the one running your session — has consistent blind spots. Route the *same* material through models from *different* families and the disagreements surface: missed issues, overstated confidence, claims one model alone would have waved through. The council is the structured version of that idea.
@@ -442,6 +470,7 @@ Most Claude-adjacent tooling assumes macOS/Linux; Amicus doesn't.
 |---------|--------------|-----|
 | "council review this" does nothing | The `second-opinion` skill isn't installed | Check `~/.claude/skills/second-opinion/SKILL.md` exists; re-run `npm install -g amicus` (postinstall installs both skills) |
 | `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. |
 | 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. |

package/bin/amicus.js

@@ -75,9 +75,10 @@ async function main() {
     process.exit(0);
   }
 
-  // Handle --help or no command
+  // Handle --help or no command. 'amicus <cmd> --help' scopes the usage to that
+  // subcommand; bare 'amicus --help' (or no command) prints the full usage.
   if (args.help || args._.length === 0) {
-    console.log(getUsage());
+    console.log(getUsage(args.help ? command : undefined));
     process.exit(0);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "1.5.0",
+  "version": "1.6.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.",
   "keywords": [
     "claude",
@@ -63,9 +63,10 @@
     "generate-docs": "node scripts/generate-docs.js",
     "generate-docs:check": "node scripts/generate-docs.js --check",
     "validate-docs": "node scripts/validate-docs.js --full",
-    "prepare": "node scripts/setup-hooks.js",
+    "setup-hooks": "node scripts/setup-hooks.js",
     "check:secrets": "node scripts/check-secrets.js --all",
-    "check:sizes": "node scripts/check-file-sizes.js --all"
+    "check:sizes": "node scripts/check-file-sizes.js --all",
+    "check:tarball": "node scripts/check-tarball-lifecycle.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",

package/scripts/postinstall.js

@@ -13,6 +13,8 @@ const path = require('path');
 const os = require('os');
 const { execFileSync } = require('child_process');
 
+const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
+
 const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'sidecar', 'SKILL.md');
 const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
 
@@ -172,6 +174,79 @@ function registerClaudeDesktop() {
   addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
 }
 
+/**
+ * Resolve the Electron binary path the same way src/sidecar/interactive.js
+ * getElectronPath() does: require('electron') returns the absolute path to the
+ * binary (or throws if the optionalDependency never installed/extracted).
+ * @returns {string|null} Path to the Electron binary, or null if unresolvable.
+ */
+function resolveElectron() {
+  try {
+    return require('electron');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * NON-FATAL verification that the OPTIONAL electron binary actually extracted.
+ * Electron is an optionalDependency: npm exits 0 even if its download/extract
+ * fails (or AV quarantines electron.exe), so without this the user only finds
+ * out the GUI is broken much later. Warn clearly that headless runs + the
+ * council still work, and point at `amicus doctor` / reinstall to get the GUI.
+ *
+ * This MUST never throw out of postinstall — the whole body is guarded so a
+ * resolver failure or a missing fs can never turn into a non-zero exit.
+ *
+ * @param {object} deps - { resolveElectron } override for testing.
+ */
+function verifyElectron(deps = {}) {
+  try {
+    const _resolve = deps.resolveElectron || resolveElectron;
+    const binPath = _resolve();
+    if (binPath && fs.existsSync(binPath)) { return; }
+    console.warn('[amicus] Warning: the Electron binary did not install — the interactive GUI / setup-wizard is unavailable.');
+    console.warn('[amicus] Headless runs and the council still work. Run `amicus doctor` to check, or `npm install -g amicus` to reinstall and add the GUI.');
+  } catch {
+    // Never let the electron check throw out of postinstall.
+  }
+}
+
+/**
+ * Configure git hooks for DEVELOPERS, folded into postinstall (#35).
+ *
+ * Previously this ran via npm's "prepare" lifecycle. But "prepare" also fires
+ * on the github: install path (`npm install -g github:BourbonDog/amicus`),
+ * where npm clones the repo, runs prepare, does a NESTED devDependency install,
+ * and re-packs — a fragile pipeline the registry install SKIPS entirely. That
+ * divergence (plus a reusable corrupt cached artifact) is what made github:
+ * installs roll back, especially on Windows. Removing the consumer-facing
+ * prepare lifecycle makes the github: path behave identically to the registry
+ * path.
+ *
+ * Hook setup still needs to happen for devs, so we run setup-hooks.js here.
+ * It is a no-op for consumers: setup-hooks.js exits 0 outside a git checkout
+ * (the published tarball / github: export has no .git), so this changes
+ * nothing for end users while keeping `npm install` wiring hooks for devs.
+ *
+ * Best-effort and self-contained: never throws (a hook-setup failure must
+ * never roll back the install), so it is safe to call before the optional
+ * skill/MCP setup.
+ *
+ * @param {object} deps - { env } override for testing.
+ */
+function setupHooks(deps = {}) {
+  try {
+    execFileSync('node', [SETUP_HOOKS_SCRIPT], {
+      stdio: 'inherit',
+      env: deps.env || process.env,
+    });
+  } catch (err) {
+    // Hook setup is for devs only and must never fail the install.
+    console.warn(`[amicus] Warning: could not configure git hooks: ${err && err.message}`);
+  }
+}
+
 function main(deps = {}) {
   if (process.env.AMICUS_SKIP_POSTINSTALL === '1') {
     console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup (plugin channel handles registration).');
@@ -181,22 +256,47 @@ function main(deps = {}) {
   const _installCouncilSkill = deps.installCouncilSkill || installCouncilSkill;
   const _registerClaudeCode = deps.registerClaudeCode || registerClaudeCode;
   const _registerClaudeDesktop = deps.registerClaudeDesktop || registerClaudeDesktop;
+  const _setupHooks = deps.setupHooks || setupHooks;
 
   console.log('[amicus] Installing...');
+  // Dev-only: configure git hooks (no-op for consumers). Folded in from the
+  // removed "prepare" lifecycle (#35) so github: installs run identically.
+  _setupHooks();
   _installSkill();
   _installCouncilSkill();
   _registerClaudeCode();
   _registerClaudeDesktop();
 
+  // Non-fatal: warn (only) if the optional Electron binary failed to extract.
+  verifyElectron(deps);
+
   console.log('');
   console.log('[amicus] Setup:');
   console.log('  - Configure API: Run `amicus setup` or set API keys directly');
   console.log('  - API keys: OPENROUTER_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENAI_API_KEY, etc.');
 }
 
-// Only run main when executed directly (not when required for testing)
+/**
+ * Top-level entry point. Wraps main() so a failure is never fatal: npm treats
+ * a non-zero postinstall as a reason to roll back / uninstall the ENTIRE global
+ * package, but skill-copy + MCP registration are optional — amicus itself still
+ * works without them. Warn clearly and exit 0 (mirrors scripts/setup-hooks.js).
+ */
+function runCli(deps = {}) {
+  try {
+    main(deps);
+  } catch (err) {
+    console.warn(`[amicus] Warning: optional post-install setup failed: ${err && err.message}`);
+    console.warn('[amicus] Skill install + MCP registration are optional — amicus itself still works.');
+    console.warn('[amicus] Run `amicus doctor` to check setup, or re-register manually later.');
+  }
+  // Always exit 0 so a failure here never rolls back the global install.
+  process.exit(0);
+}
+
+// Only run when executed directly (not when required for testing)
 if (require.main === module) {
-  main();
+  runCli();
 }
 
-module.exports = { main, addMcpToConfigFile, installSkill, installCouncilSkill, COUNCIL_FILES };
+module.exports = { main, runCli, addMcpToConfigFile, installSkill, installCouncilSkill, setupHooks, verifyElectron, resolveElectron, COUNCIL_FILES };

package/scripts/setup-hooks.js

@@ -12,10 +12,14 @@
  * core.hooksPath at it makes hooks fire in the main clone and in every
  * worktree with no per-worktree setup.
  *
- * Runs automatically via npm's "prepare" lifecycle. If you install with
- * --ignore-scripts (recommended for this repo), run it once by hand:
+ * Runs automatically via the postinstall flow (scripts/postinstall.js) so a
+ * fresh dev `npm install` still wires hooks. It is NOT a "prepare" script:
+ * prepare also fires on the github: install path, where it triggers a nested
+ * devDependency install + re-pack that the registry path skips (#35) — the
+ * source of the Windows github: rollback. If you install with --ignore-scripts
+ * (recommended for this repo), run it once by hand:
  *
- *   node scripts/setup-hooks.js
+ *   npm run setup-hooks      # or: node scripts/setup-hooks.js
  *
  * Safe to run anywhere: exits 0 outside a git checkout (npm tarball
  * installs, exported archives) and never fails the install.

package/src/cli-handlers-doctor.js

@@ -105,7 +105,7 @@ function runDoctorChecks(depsOverride = {}) {
   checks.push(guard('opencode-bin', 'OpenCode binary', () => (
     d.hasOpencodeBinary()
       ? { id: 'opencode-bin', name: 'OpenCode binary', status: 'ok', message: 'found', hint: null }
-      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: 'npm install -g amicus' }
+      : { id: 'opencode-bin', name: 'OpenCode binary', status: 'error', message: 'not found', hint: 'npm install -g amicus  (a transient install error can roll back the engine binaries — re-run, or: npm cache clean --force && npm install -g amicus)' }
   )));
 
   checks.push(guard('electron', 'Electron (interactive GUI)', () => (

package/src/cli.js

@@ -292,10 +292,15 @@ function isValidDurationFormat(duration) {
 }
 
 /**
- * Get usage text
+ * Usage text, split into composable parts so 'amicus <cmd> --help' can print
+ * only the relevant block while bare 'amicus --help' still composes the full
+ * text byte-identically.
+ *
+ * Each value is a section of the original monolithic template; concatenating
+ * USAGE_HEADER + every USAGE_COMMAND_BLOCKS value (in insertion order) +
+ * USAGE_TRAILER reproduces the original string exactly.
  */
-function getUsage() {
-  return `
+const USAGE_HEADER = `
 Usage: amicus <command> [options]
 
 Commands:
@@ -320,7 +325,12 @@ Commands:
     (no args)                List all configured providers
   update      Update to latest version
   mcp         Start MCP server (stdio transport)
+`;
 
+// Per-command option blocks, keyed by the invoked subcommand. Insertion order
+// must match the original template so the composed full usage is unchanged.
+const USAGE_COMMAND_BLOCKS = {
+  start: `
 Options for 'start':
   --model <model>              Optional (uses config default). Model to use:
                                - Short aliases: gemini, opus, gpt (see 'amicus setup')
@@ -354,7 +364,8 @@ Options for 'start':
   --validate-model             (Deprecated: validation is on by default)
   --no-validate-model          Skip model-catalog validation before launch
   --position <pos>             Window position: right (default), left, center
-
+`,
+  fanout: `
 Options for 'fanout':
   --models <a,b,c>             Required. Comma-separated aliases or provider/model IDs
   --council <name>             Run a saved council instead of --models (e.g. free). Mutually exclusive with --models
@@ -369,27 +380,34 @@ Options for 'fanout':
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
-
+`,
+  models: `
 Options for 'models':
   --search <q>                 Filter by substring over model id and name
   --refresh                    Force-refresh the catalog from provider APIs
   --check                      Audit aliases against the catalog (exit = stale count)
   --json                       Machine-readable output
-
+`,
+  list: `
 Options for 'list':
   --status <filter>            Filter by status (running, complete)
   --all                        Show all projects
   --json                       Output as JSON
-
+`,
+  abort: `
 Options for 'abort':
   --all                        Abort all running sessions in this project
-
+`,
+  read: `
 Options for 'read':
   --summary                    Show summary (default)
   --conversation               Show full conversation
   --metadata                   Show session metadata
   --json                       Emit the run/wave result as stable JSON
+`
+};
 
+const USAGE_TRAILER = `
 OpenCode Agent Types:
     Chat       Reads auto, writes/bash ask permission (interactive default)
     Build      Full tool access (headless default)
@@ -409,6 +427,25 @@ Examples:
   amicus resume abc123
   amicus read abc123 --conversation
 `;
+
+/**
+ * Get usage text.
+ *
+ * @param {string} [command] When provided AND it has a dedicated options block,
+ *   returns the top-level header plus only that command's block (scoped --help).
+ *   When omitted, or when the command has no dedicated block, returns the full
+ *   composed usage (byte-identical to the original monolithic string).
+ */
+function getUsage(command) {
+  // Each part carries its own leading/trailing newlines exactly as they sat in
+  // the original single template literal, so plain concatenation reproduces the
+  // blank-line separators (the header's trailing "\n" + a block's leading "\n"
+  // form the blank line between them). Scoped help keeps the header + trailer
+  // and substitutes just the one command's block in place of all blocks.
+  const block = command && Object.prototype.hasOwnProperty.call(USAGE_COMMAND_BLOCKS, command)
+    ? USAGE_COMMAND_BLOCKS[command]
+    : Object.values(USAGE_COMMAND_BLOCKS).join('');
+  return USAGE_HEADER + block + USAGE_TRAILER;
 }
 
 module.exports = {

package/src/headless.js

@@ -289,7 +289,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       agent: promptOptions.agent,
       userMessageLength: userMessage.length
     });
-    await sendPromptAsync(client, sessionId, promptOptions);
+    const promptResult = await sendPromptAsync(client, sessionId, promptOptions);
     writeProgress(sessionDir, 'prompt_sent');
     logger.info('Prompt sent successfully, entering polling loop', {
       sessionId,
@@ -302,6 +302,16 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let aborted = false;
     let sessionError = null; // Captures model/SDK errors from assistant messages
 
+    // Hard provider failure detected at the client boundary (#37): a non-2xx /
+    // 402 from promptAsync surfaces here even when the server never emits an
+    // assistant message carrying info.error. Seed sessionError so the loop's
+    // "error with no output" gate ends the run promptly with a usable reason.
+    const boundaryProviderError = !!(promptResult && promptResult.providerError);
+    if (boundaryProviderError) {
+      sessionError = promptResult.providerError;
+      logger.error('Provider error at client boundary', { taskId, sessionId, reason: sessionError });
+    }
+
     // Poll for completion by checking messages
     const startTime = Date.now();
     const deadline = startTime + timeoutMs;
@@ -383,6 +393,17 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           break;
         }
 
+        // Hard provider failure at the client boundary (#37): the request was
+        // rejected (e.g., 402) so no assistant message will ever arrive. Exit as
+        // soon as we confirm nothing streamed — don't wait for assistantFinished
+        // (which never flips here) or the full timeout.
+        if (boundaryProviderError && !mirror.output) {
+          logger.error('Provider error at boundary with no output, exiting', {
+            sessionError, pollCount
+          });
+          break;
+        }
+
         // If the model returned an error with no output, exit immediately
         // (don't wait for timeout — the model won't produce anything)
         if (sessionError && !mirror.output && assistantFinished) {

package/src/mcp-server.js

@@ -10,6 +10,19 @@ const { safeSessionDir } = require('./utils/validators');
 const { getSessionDir, SESSIONS_DIR, LEGACY_SESSIONS_DIR } = require('./session-manager');
 const { readProgress, isStalled } = require('./sidecar/progress');
 const { SharedServerManager } = require('./utils/shared-server');
+const { durationBetween } = require('./utils/result-schema');
+
+/**
+ * Elapsed run duration: time between createdAt and the run's end, bounding the
+ * end by completedAt/abortedAt/crashedAt so a delayed poll of a finished run
+ * reports the run duration, not time-since-start. Falls back to now() while
+ * still running. Returns 0 if createdAt is missing/malformed.
+ */
+function elapsedMs(metadata) {
+  const end = metadata.completedAt || metadata.abortedAt || metadata.crashedAt
+    || new Date().toISOString();
+  return durationBetween(metadata.createdAt, end) ?? 0;
+}
 
 const sharedServer = new SharedServerManager({ logger });
 
@@ -124,7 +137,7 @@ const handlers = {
         const { buildContext } = require('./sidecar/context-builder');
         const { buildPrompts } = require('./prompt-builder');
         const { runHeadless } = require('./headless');
-        const { finalizeSession } = require('./sidecar/session-utils');
+        const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
         // resolvedModel is already available from validateStartInputs() above
 
         sessionId = await createSession(client);
@@ -185,10 +198,12 @@ const handlers = {
             mcp: undefined, // shared server already has MCP config
           }
         ).then((result) => {
-          // Session complete - finalize and remove from tracking
+          // Session done — route through resolveTerminalState (same single source
+          // of truth as the CLI start.js path) so an errored/timed-out/aborted run
+          // can never silently default to 'complete' with a 0-byte summary (#36).
           try {
             const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-            finalizeSession(sessionDir, result.summary || '', cwd, meta);
+            finalizeHeadlessResult(sessionDir, result, cwd, meta);
           } catch (finErr) {
             logger.warn('Failed to finalize session', { error: finErr.message });
           }
@@ -259,7 +274,10 @@ const handlers = {
     const cwd = project || getProjectDir(input.project);
     const sessionDir = safeSessionDir(cwd, input.taskId);
     const metadata = readMetadata(input.taskId, cwd);
-    if (!metadata) { return textResult(`Session ${input.taskId} not found.`, true); }
+    if (!metadata) {
+      return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
+        'If you ran it in a different project, pass the original "project".', true);
+    }
 
     if (metadata.type === 'wave') {
       const legs = (metadata.legs || []).map((legId) => {
@@ -306,7 +324,7 @@ const handlers = {
         }
       }
 
-      const ms = Date.now() - new Date(metadata.createdAt).getTime();
+      const ms = elapsedMs(metadata);
       const response = {
         taskId: metadata.taskId, type: 'wave', status: metadata.status,
         legsComplete: done, legsTotal: legs.length, legs,
@@ -333,7 +351,7 @@ const handlers = {
       }
     }
 
-    const ms = Date.now() - new Date(metadata.createdAt).getTime();
+    const ms = elapsedMs(metadata);
     const response = {
       taskId: metadata.taskId, status: metadata.status,
       elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
@@ -372,7 +390,8 @@ const handlers = {
     const cwd = project || getProjectDir(input.project);
     const sessionDir = safeSessionDir(cwd, input.taskId);
     if (!fs.existsSync(sessionDir)) {
-      return textResult(`Session ${input.taskId} not found.`, true);
+      return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
+        'If you ran it in a different project, pass the original "project".', true);
     }
 
     const readMeta = (() => {
@@ -413,6 +432,13 @@ const handlers = {
     })();
     const summaryText = fs.readFileSync(summaryPath, 'utf-8');
     const header = metaForRead.model ? `**Model:** ${metaForRead.model}\n\n` : '';
+    // A failed shared-server run writes an EXISTING 0-byte summary.md (so we hit
+    // this file-exists branch, not "No summary available"). Surface the failure
+    // reason instead of returning an empty/uninformative body (#36).
+    if ((metaForRead.status === 'error' || metaForRead.status === 'crashed') && !summaryText.trim()) {
+      const reason = metaForRead.reason || 'Unknown error';
+      return textResult(`${header}**Status:** ${metaForRead.status}\n**Reason:** ${reason}\n\n(No summary — the session ended with an error.)`);
+    }
     return textResult(header + summaryText);
   },
 
@@ -636,6 +662,15 @@ const handlers = {
   },
 
   async amicus_setup() {
+    const { checkElectronAvailable } = require('./sidecar/interactive');
+    if (!checkElectronAvailable()) {
+      return textResult(
+        'The setup GUI cannot open because Electron is not installed, so no '
+        + 'window appeared. Run `amicus setup` in your terminal instead — it '
+        + 'falls back to a headless (readline) wizard for API key configuration.',
+        true
+      );
+    }
     try { spawnSidecarProcess(['setup']); } catch (err) {
       return textResult(`Failed to launch setup: ${err.message}`, true);
     }

package/src/opencode-client.js

@@ -27,6 +27,40 @@ async function getCreateOpencodeServer() {
   return sdk.createOpencodeServer;
 }
 
+/**
+ * Shared reason string for an HTTP 402 from the provider.
+ * Exported so #36 and a later pre-flight credit check can reuse the exact phrasing
+ * instead of re-deriving it.
+ */
+const INSUFFICIENT_CREDITS_REASON = 'Insufficient credits';
+
+/**
+ * Map an SDK request result to a propagated provider-failure reason.
+ *
+ * Keys on the actual HTTP status (result.response.status, falling back to
+ * result.error.status) so benign informational `error` payloads that ride on a
+ * 2xx response stay "continue to poll" — only a real non-2xx status becomes a
+ * session error.
+ *
+ *   402            -> 'Insufficient credits'
+ *   other non-2xx  -> 'Provider error: <status>'
+ *   2xx / unknown  -> null
+ *
+ * @param {{response?: {status?: number}, error?: {status?: number}}} [result]
+ * @returns {string|null} Reason string, or null when there is no hard failure.
+ */
+function providerErrorReason(result) {
+  if (!result) { return null; }
+  const status = (result.response && result.response.status)
+    || (result.error && result.error.status);
+  // No usable status — cannot distinguish a benign warning from a failure, so
+  // do not regress the "continue to poll" behavior.
+  if (typeof status !== 'number') { return null; }
+  if (status >= 200 && status < 300) { return null; }
+  if (status === 402) { return INSUFFICIENT_CREDITS_REASON; }
+  return `Provider error: ${status}`;
+}
+
 /**
  * Parse a model string into SDK format
  *
@@ -159,11 +193,25 @@ async function sendPrompt(client, sessionId, options) {
     }
   }
 
-  // Log but don't throw on promptAsync errors.
-  // promptAsync is fire-and-forget: the server queues the prompt for async
-  // processing. Errors here may be informational (e.g., model config warnings)
-  // rather than fatal. The polling loop will detect real failures via timeout.
-  if (result.error) {
+  // Detect a hard provider failure at the client boundary (#37). A non-2xx /
+  // 402 here must surface as a session error EVEN WHEN the server emits no
+  // assistant message carrying info.error — otherwise the run looks idle/empty.
+  // Keyed on HTTP status so benign informational errors (model config warnings
+  // on a 2xx) keep the fire-and-forget "continue to poll" behavior below.
+  const reason = providerErrorReason(result);
+  if (reason) {
+    result.providerError = reason;
+    const { logger } = require('./utils/logger');
+    logger.error('promptAsync returned a hard provider error', {
+      reason,
+      status: (result.response && result.response.status) || (result.error && result.error.status),
+      sessionId
+    });
+  } else if (result.error) {
+    // Log but don't throw on benign promptAsync errors.
+    // promptAsync is fire-and-forget: the server queues the prompt for async
+    // processing. These errors are informational (e.g., model config warnings)
+    // rather than fatal. The polling loop will detect real failures via timeout.
     const { logger } = require('./utils/logger');
     logger.error('promptAsync returned error (continuing to poll)', {
       error: result.error.message || JSON.stringify(result.error),
@@ -595,6 +643,8 @@ function parseMcpSpec(spec) {
 }
 
 module.exports = {
+  INSUFFICIENT_CREDITS_REASON,
+  providerErrorReason,
   parseModelString,
   createClient,
   createSession,

package/src/sidecar/continue.js

@@ -200,8 +200,9 @@ async function continueSidecar(options) {
   const metaPath = SessionPaths.metadataFile(sessionDir);
   const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
 
-  // Finalize session
-  finalizeSession(sessionDir, summary, project, meta);
+  // Finalize session. Interactive mode legitimately returns an empty summary,
+  // so pass status explicitly to stay out of the #36 empty-summary guard.
+  finalizeSession(sessionDir, summary, project, meta, { status: 'complete' });
 }
 
 module.exports = {

package/src/sidecar/conversation-mirror.js

@@ -17,6 +17,8 @@ function createMirrorState() {
     seenToolResultIds: new Set(),
     receivingReported: false,
     output: '',                 // accumulated assistant text
+    seenReasoningParts: new Map(), // partId -> last captured reasoning length
+    reasoningOutput: '',        // accumulated reasoning text (promoted to output only if no text part arrives)
     usageByMsg: new Map(),      // msgId -> {tokens, cost}
   };
 }
@@ -101,6 +103,22 @@ function mirrorMessages(messages, state, opts = {}) {
             timestamp: now(),
           });
         }
+      } else if (part.type === 'reasoning' && part.text) {
+        // Some providers (e.g. Gemini 3.x on the direct Google path) return the
+        // answer as a reasoning part with no separate text part. Accumulate it in a
+        // dedicated buffer; it is promoted to `output` at finalization ONLY when no
+        // visible text part ever arrives (see below), so models that emit BOTH a
+        // reasoning part and a text part are unaffected (their thinking never
+        // pollutes the answer).
+        const prevLen = state.seenReasoningParts.get(partId) || 0;
+        if (part.text.length > prevLen) {
+          state.reasoningOutput += part.text.slice(prevLen);
+          state.seenReasoningParts.set(partId, part.text.length);
+          if (!state.receivingReported) {
+            state.receivingReported = true;
+            progressUpdates.push({ stage: 'receiving', extra: { messagesReceived: 1 } });
+          }
+        }
       }
     }
   }
@@ -110,6 +128,15 @@ function mirrorMessages(messages, state, opts = {}) {
   const lastAssistant = list.filter(m => m.info && m.info.role === 'assistant').pop();
   assistantFinished = !!(lastAssistant && lastAssistant.info.time && lastAssistant.info.time.completed);
 
+  // Reasoning-only fallback: if the assistant finished but emitted only reasoning
+  // parts (no visible text), promote the reasoning text to `output` so the headless
+  // completion gates fire and the answer isn't lost as "No Output". Runs once — once
+  // `output` is non-empty this is skipped on subsequent polls.
+  if (assistantFinished && !state.output && state.reasoningOutput) {
+    state.output = state.reasoningOutput;
+    appendLines.push({ role: 'assistant', content: state.reasoningOutput, timestamp: now() });
+  }
+
   return { appendLines, progressUpdates, state, currentAssistantMsgId, assistantFinished, sessionError, messageCount };
 }
 

package/src/sidecar/resume.js

@@ -202,8 +202,10 @@ async function resumeSidecar(options) {
     // Output summary
     outputSummary(summary);
 
-    // Finalize session (use updatedMetadata which has resumedAt)
-    finalizeSession(sessionDir, summary, project, updatedMetadata);
+    // Finalize session (use updatedMetadata which has resumedAt). Pass status
+    // explicitly to preserve the pre-#36 default ('complete') and stay out of
+    // the empty-summary guard — interactive resume legitimately has no summary.
+    finalizeSession(sessionDir, summary, project, updatedMetadata, { status: 'complete' });
   } finally {
     if (heartbeat) { heartbeat.stop(); }
     releaseLock(sessionDir);

package/src/sidecar/session-finalize.js

@@ -23,4 +23,44 @@ function resolveTerminalState(result, signal) {
   return { status: 'error', exitCode: 1 };
 }
 
-module.exports = { resolveTerminalState };
+/**
+ * Finalize a headless run by routing through resolveTerminalState — the single
+ * source of truth shared with the CLI start.js path. An errored run writes
+ * status='error' + reason (and an EXISTING 0-byte summary.md so amicus_read hits
+ * its file-exists branch); every other state persists the (possibly partial)
+ * summary with the correct terminal status. Never defaults a failed run to
+ * 'complete'. Used by the shared-server MCP .then handler (#36).
+ *
+ * @param {string} sessionDir
+ * @param {{completed?:boolean,timedOut?:boolean,aborted?:boolean,error?:any,summary?:string}|null} result
+ * @param {string} project
+ * @param {object} metadata - mutated + persisted to metadata.json
+ */
+function finalizeHeadlessResult(sessionDir, result, project, metadata) {
+  // Lazy require to avoid a circular dependency (session-utils requires nothing
+  // here, but keep symmetry with start.js which also lazy-requires).
+  const fs = require('fs');
+  const path = require('path');
+  const { finalizeSession, SessionPaths } = require('./session-utils');
+
+  const terminal = resolveTerminalState(result);
+  if (terminal.status === 'error') {
+    // Write an existing (0-byte) summary so amicus_read hits the file-exists
+    // branch and surfaces metadata.reason rather than "No summary available".
+    fs.writeFileSync(SessionPaths.summaryFile(sessionDir), result && result.summary ? result.summary : '', { mode: 0o600 });
+    metadata.status = 'error';
+    metadata.reason = (result && result.error) ? String(result.error) : 'Incomplete';
+    metadata.completedAt = new Date().toISOString();
+    fs.writeFileSync(
+      path.join(sessionDir, 'metadata.json'),
+      JSON.stringify(metadata, null, 2),
+      { mode: 0o600 }
+    );
+    return;
+  }
+  // complete / timed-out / aborted: persist the (possibly partial) summary with
+  // the resolved status. Explicit status means the #36 guard won't re-classify.
+  finalizeSession(sessionDir, (result && result.summary) || '', project, metadata, { status: terminal.status });
+}
+
+module.exports = { resolveTerminalState, finalizeHeadlessResult };

package/src/sidecar/session-utils.js

@@ -90,8 +90,14 @@ function finalizeSession(sessionDir, summary, project, metadata, opts = {}) {
   // Save summary
   fs.writeFileSync(SessionPaths.summaryFile(sessionDir), summary, { mode: 0o600 });
 
-  // Update metadata to the resolved terminal status (default complete).
-  metadata.status = opts.status || 'complete';
+  // Update metadata to the resolved terminal status. Callers that know the
+  // terminal state (CLI start.js, shared-server finalizeHeadlessResult) pass it
+  // explicitly via opts.status — that always wins, so they are never
+  // re-classified. Defense-in-depth (#36): when NO status is supplied, an empty
+  // summary must never silently default to 'complete' — that hid errored/empty
+  // shared-server runs behind a 0-byte summary and a false success.
+  const hasSummary = typeof summary === 'string' && summary.trim().length > 0;
+  metadata.status = opts.status || (hasSummary ? 'complete' : 'error');
   metadata.completedAt = new Date().toISOString();
   fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
 

package/src/sidecar/setup.js

@@ -70,6 +70,31 @@ function detectApiKeys() {
   return readApiKeys();
 }
 
+/**
+ * #38 — Non-blocking OpenRouter credit warning. Reads the OpenRouter key
+ * value, calls checkOpenRouterCredit, and prints a WARNING (never blocks) when
+ * the key is zero-credit or free tier. Any failure is swallowed silently — a
+ * credit probe must never stop setup from completing.
+ */
+/* eslint-disable no-console -- CLI wizard requires direct console output */
+async function warnOnLowOpenRouterCredit() {
+  try {
+    const { readApiKeyValues } = require('../utils/api-key-store');
+    const { checkOpenRouterCredit } = require('../utils/api-key-validation');
+    const values = readApiKeyValues();
+    const key = values && values.openrouter;
+    if (!key) { return; }
+    const { warning } = await checkOpenRouterCredit(key);
+    if (warning) {
+      console.log(`Warning: ${warning}`);
+      console.log('');
+    }
+  } catch (err) {
+    logger.debug('OpenRouter credit check skipped', { error: err.message });
+  }
+}
+/* eslint-enable no-console */
+
 /**
  * Prompt the user with a question via readline
  * @param {readline.Interface} rl - Readline interface
@@ -246,6 +271,12 @@ async function runReadlineSetup() {
     }
     console.log('');
 
+    // #38 — non-blocking zero-credit / free-tier OpenRouter warning. Never
+    // blocks: free-tier councils against free models are legitimate.
+    if (keys.openrouter) {
+      await warnOnLowOpenRouterCredit();
+    }
+
     const mode = await askQuestion(rl,
       'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
     if (mode === '2') {
@@ -410,4 +441,5 @@ module.exports = {
   runApiKeySetup,
   seedCatalog,
   seedFreeCouncil,
+  warnOnLowOpenRouterCredit,
 };

package/src/utils/api-key-validation.js

@@ -87,11 +87,83 @@ function validateApiKey(provider, key) {
   });
 }
 
+/** Warning string for a zero-credit OpenRouter key (paid models will 402). */
+const OPENROUTER_NO_CREDIT_WARNING =
+  'OpenRouter key has no remaining credit — paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits, or build a free council (amicus setup → option 2).';
+
+/** Warning string for a free-tier OpenRouter key. */
+const OPENROUTER_FREE_TIER_WARNING =
+  'OpenRouter key is free tier — only :free models will route; paid models will fail (402). ' +
+  'Add credit at openrouter.ai/credits to use paid models.';
+
+/**
+ * Non-blocking credit/limit check for an OpenRouter key.
+ *
+ * Hits GET https://openrouter.ai/api/v1/key (returns limit, usage,
+ * is_free_tier, limit_remaining) and produces a WARNING — never an error —
+ * when is_free_tier is true or limit_remaining <= 0. Any failure (non-200,
+ * network error, malformed body) resolves with warning:null so setup is
+ * never blocked. Free-tier councils against free models are legitimate.
+ *
+ * @param {string} key OpenRouter API key
+ * @returns {Promise<{warning: string|null, isFreeTier: boolean,
+ *   limitRemaining: number|null, limit: number|null, usage: number|null}>}
+ */
+function checkOpenRouterCredit(key) {
+  const none = {
+    warning: null, isFreeTier: false, limitRemaining: null, limit: null, usage: null
+  };
+  if (!key || key.trim().length === 0) {
+    return Promise.resolve(none);
+  }
+
+  const headers = { 'Authorization': `Bearer ${key.trim()}` };
+
+  return new Promise((resolve) => {
+    const req = https.get('https://openrouter.ai/api/v1/key', { headers }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) { resolve(none); return; }
+        let data;
+        try {
+          data = (JSON.parse(body) || {}).data || {};
+        } catch (_e) {
+          resolve(none);
+          return;
+        }
+        const isFreeTier = data.is_free_tier === true;
+        const limitRemaining = (typeof data.limit_remaining === 'number')
+          ? data.limit_remaining : null;
+        const limit = (typeof data.limit === 'number') ? data.limit : null;
+        const usage = (typeof data.usage === 'number') ? data.usage : null;
+
+        let warning = null;
+        if (limitRemaining !== null && limitRemaining <= 0) {
+          warning = OPENROUTER_NO_CREDIT_WARNING;
+        } else if (isFreeTier) {
+          warning = OPENROUTER_FREE_TIER_WARNING;
+        }
+        resolve({ warning, isFreeTier, limitRemaining, limit, usage });
+      });
+    });
+    req.setTimeout(10000, () => {
+      req.destroy();
+      resolve(none);
+    });
+    req.on('error', () => { resolve(none); });
+  });
+}
+
 // Backwards compat alias
 const validateOpenRouterKey = validateApiKey;
 
 module.exports = {
   validateApiKey,
   validateOpenRouterKey,
+  checkOpenRouterCredit,
+  OPENROUTER_NO_CREDIT_WARNING,
+  OPENROUTER_FREE_TIER_WARNING,
   VALIDATION_ENDPOINTS
 };

package/src/utils/result-schema.js

@@ -267,6 +267,7 @@ function buildDoctorDoc({ version, timestamp, checks }) {
 module.exports = {
   SCHEMA_VERSION,
   TERMINAL_STATUSES,
+  durationBetween,
   statusFromResult,
   buildRunResult,
   buildWaveResult,