amicus 4.5.0 → 4.5.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "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,30 @@
 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.1] - 2026-07-30
+
+### Added
+
+- **`electron-mcp` doctor check — doctor now validates Electron in the install the MCP actually
+  runs from (#76).** `amicus doctor` used to probe Electron only in the copy doctor itself runs
+  from (usually the global install), while `npx -y amicus@latest mcp` serves councils from an
+  npx-cache copy — so doctor could print `Electron: ok` while every `ui: true` run failed with
+  `electron-absent` (the electron-flavored recurrence of the engine's green-while-broken defect).
+  The new check enumerates running/global/npx-cache installs (reusing the engine scanner) and
+  probes Electron in each through a dual-root resolver — npm nests `electron` under
+  `amicus/node_modules` in a global install but hoists it to a sibling in the npx cache (the #69
+  layout lesson, now applied to Electron). With `--fix`, binary-missing npx copies are healed in
+  place via `repairElectron` under the #56 timeout guard; never-installed copies are reported,
+  not repaired.
+
+### Changed
+
+- **`workspaceOpenReason` distinguishes a broken Electron from a missing one (#76).**
+  `electron-absent` now means the electron package was never installed; the new
+  `electron-broken: binary missing under <dir> — run `amicus doctor --fix`` covers the
+  package-present-but-binary-missing state (interrupted postinstall, AV quarantine) that the old
+  single reason conflated with it — naming the exact dir and the one-command fix.
+
 ## [4.5.0] - 2026-07-28
 
 "Save and share your councils" — complex run configurations become one command, repeatable and

package/README.md

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

package/docs/ROADMAP.md

@@ -7,14 +7,12 @@ major jump, gated on funding/cofounder. The observability arc is split so the **
 first (v4.3)** and the **Electron "Council Workspace" (v4.4)** rides on top of it. `--dry-run` cost
 preview dropped to the backlog.
 
-Amicus is at **v4.4.1** (2026-07-27), the fast-follow patch on v4.4.0 (tagged 2026-07-26). Each
-4.x rev below leads with the benefit, not the plumbing.
+Amicus is at **v4.5.0** (tagged 2026-07-28). Each 4.x rev below leads with the benefit, not the
+plumbing.
 
-**Status:** v4.0 through **v4.4.1** have **shipped** — everything down to the v4.5 heading is a
-record of what landed, not a plan. **v4.5 (packs + templates + auto-open) is the next rev**, with
-**v4.6 (composition + tagging + GUI ergonomics)** behind it — the former combined v4.5 scope,
-split 2026-07-27 (design: `docs/superpowers/specs/2026-07-27-v4.5-save-and-share-design.md`). v5.0
-remains forward-looking.
+**Status:** v4.0 through **v4.5.0** have **shipped** — everything down to the v4.6 heading is a
+record of what landed, not a plan. **v4.6 (composition + tagging + GUI ergonomics) is the next
+rev.** v5.0 remains forward-looking.
 
 > 📁 **Reading this from an npm install?** Some references below point at working documents that
 > live in the git repository and are deliberately **not** in the published package — anything under
@@ -87,7 +85,7 @@ and a review that honestly finds nothing stops being an error.
 > repo's working notes (`.superpowers/sdd/v441/backlog-and-proposal.md`, local-only) and in the
 > repo's root `BACKLOG.md` — neither ships in the npm package; see the note at the top.
 
-## v4.5 — "Save and share your councils" *(scope split 2026-07-27 — composition moved to v4.6)*
+## v4.5 — "Save and share your councils" *(scope split 2026-07-27 — composition moved to v4.6)* — ✅ SHIPPED v4.5.0, 2026-07-28
 **Benefit:** complex councils become one-command, repeatable, and shareable — and the flagship GUI
 stops hiding. Design: `docs/superpowers/specs/2026-07-27-v4.5-save-and-share-design.md`.
 - **★ Auto-open the Council Workspace on a council run (Christian, 2026-07-26)** — when a council is

package/docs/council.md

@@ -413,8 +413,11 @@ bottom, first match wins:
 6. Otherwise → opens.
 
 **Response fields.** `amicus_council_run`'s result always carries `workspaceOpened: boolean`, and,
-**only when it did not open**, `workspaceOpenReason` — one of `param-suppressed`, `electron-absent`,
-`no-display`, `config-disabled`, `client-not-code-local`, or a `spawn-failed:`/`auto-open-failed:`
+**only when it did not open**, `workspaceOpenReason` — one of `param-suppressed`, `electron-absent`
+(the electron package was never installed for this copy), an `electron-broken:` detail (the package
+is present but its binary never arrived — interrupted download or AV quarantine; the reason names
+the electron dir and points at `amicus doctor --fix`), `no-display`, `config-disabled`,
+`client-not-code-local`, or a `spawn-failed:`/`auto-open-failed:`
 detail if the decision said to open but the launch itself failed. The launch is fire-and-forget: it
 never blocks the tool's response, and a launch failure never fails the council run itself — the run
 proceeds exactly as it would with no Workspace at all, and `amicus watch <runId> --ui` still works

package/docs/usage.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "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-handlers-doctor.js

@@ -7,6 +7,8 @@ const mcpChecks = require('./utils/doctor-mcp-checks');
 // engine-mcp check body — verifies the engine in the npx-cache copies the MCP
 // actually launches (bug report #1). Split out to keep this file under the gate.
 const engineCheck = require('./utils/doctor-engine-check');
+// electron-mcp check body (#76) — same blind spot, electron-flavored.
+const electronMcpCheck = require('./utils/doctor-electron-mcp-check');
 // local-providers check body (v4.2 §4.7 C8) — split out to keep this file
 // under the gate (mirrors the engineCheck/mcpChecks split above).
 const localProvidersCheck = require('./utils/doctor-local-providers-check');
@@ -47,6 +49,8 @@ function realDeps() {
     scanEngineInstalls: () => require('./utils/engine-install-scan').scanEngineInstalls(),
     // report #2: copy-from-sibling self-heal for `doctor --fix`.
     repairEngine: (o) => require('./utils/engine-repair').repairEngine(o),
+    // electron-mcp check (#76): same enumeration, electron probed per copy.
+    scanElectronInstalls: () => electronMcpCheck.scanElectronInstalls(),
     getElectronPath: () => require('./sidecar/interactive-process').getElectronPath(),
     // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
     // stays separate; repair only runs when fix is requested.
@@ -161,6 +165,12 @@ async function runDoctorChecks(depsOverride = {}) {
   // install) can't hide a broken copy the MCP would spawn (bug report #1/#4).
   checks.push(await guardAsync('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineMcp(d)));
 
+  // #76: same green-while-broken blind spot for Electron — probe the npx-cache
+  // copies `ui: true` actually depends on. fixTimeoutMs forwards the #56
+  // never-hang guard to the per-copy repairElectron calls.
+  checks.push(await guardAsync('electron-mcp', 'Electron (MCP launch path)',
+    () => electronMcpCheck.evaluateElectronMcp({ ...d, fixTimeoutMs: FIX_TIMEOUT_MS })));
+
   checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
     if (d.getElectronPath()) {
       return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null };

package/src/mcp-council-run.js

@@ -241,11 +241,13 @@ async function handleCouncilRunTool(input, project, helpers) {
   let workspaceOpened = false;
   let workspaceOpenReason = null;
   try {
-    const { isElectronUsable } = require('./sidecar/electron-install');
+    const { probeElectronState } = require('./sidecar/electron-state');
     const { getWorkspaceAutoOpen } = require('./utils/config');
+    const es = probeElectronState(); // 3-state (#76): splits absent vs broken
     const decision = ao.decide({
       client: helpers.clientName,
-      electronUsable: isElectronUsable(),
+      electronState: es.state,
+      electronDir: es.electronDir,
       platform: process.platform,
       env: process.env,
       autoOpenConfig: getWorkspaceAutoOpen(),

package/src/sidecar/electron-state.js

@@ -0,0 +1,61 @@
+/**
+ * Electron install-state probes (#76).
+ *
+ * Distinguishes the two states isElectronUsable() collapses into one boolean:
+ *   'package-missing' — the electron optionalDependency was never installed
+ *                       (possibly deliberate: headless-only install)
+ *   'binary-missing'  — package present but dist/<exe> absent (interrupted
+ *                       postinstall, AV quarantine) — repairElectron territory
+ *   'ok'              — the resolved exe exists on disk
+ *
+ * Also owns electronDirFor(): the per-install dual-root layout probe. npm
+ * NESTS electron under amicus/node_modules in a global install but HOISTS it
+ * to a sibling in the npx cache — the same layout asymmetry that broke the
+ * engine probe (#69). In-process require.resolve handles hoisting via walk-up,
+ * which is why the running copy probes itself fine; only CROSS-install probing
+ * (doctor) needs this explicit dual-root check.
+ */
+
+'use strict';
+
+const path = require('path');
+const fsDefault = require('fs');
+const { isElectronUsable, defaultElectronDir } = require('./electron-install');
+
+/**
+ * Locate the electron package dir serving a given amicus install. Checks the
+ * nested root first (require.resolve walk-up order), then the hoisted sibling.
+ * @param {string} pkgDir amicus package root
+ * @param {{fs?:object}} [deps]
+ * @returns {string|null} electron package dir, or null when not installed
+ */
+function electronDirFor(pkgDir, { fs = fsDefault } = {}) {
+  const candidates = [
+    path.join(pkgDir, 'node_modules', 'electron'),
+    path.join(path.dirname(pkgDir), 'electron'),
+  ];
+  for (const dir of candidates) {
+    try { if (fs.existsSync(dir)) { return dir; } } catch { /* unreadable root */ }
+  }
+  return null;
+}
+
+/**
+ * Probe one electron package dir into the 3-state verdict.
+ * `electronDir: null` (electronDirFor found nothing) short-circuits to
+ * package-missing; an explicit dir without package.json reports the same.
+ * @param {{electronDir?:string|null, fs?:object, platform?:string, env?:object}} [opts]
+ * @returns {{state:'ok'|'package-missing'|'binary-missing', electronDir:string|null}}
+ */
+function probeElectronState({
+  electronDir = defaultElectronDir(), fs = fsDefault, platform = process.platform, env = process.env,
+} = {}) {
+  if (!electronDir) { return { state: 'package-missing', electronDir: null }; }
+  let hasPkg = false;
+  try { hasPkg = fs.existsSync(path.join(electronDir, 'package.json')); } catch { /* unreadable */ }
+  if (!hasPkg) { return { state: 'package-missing', electronDir }; }
+  const usable = isElectronUsable({ electronDir, fs, platform, env });
+  return { state: usable ? 'ok' : 'binary-missing', electronDir };
+}
+
+module.exports = { electronDirFor, probeElectronState };

package/src/sidecar/workspace-auto-open.js

@@ -7,7 +7,10 @@
  * Decision order (spec §6 guard 4):
  * 1. uiParam === false → 'param-suppressed' (explicit user request beats everything, checked first)
  * 2. Hard guards (always checked, beat even explicit true):
- *    - !electronUsable → 'electron-absent'
+ *    - electron package-missing → 'electron-absent'
+ *    - electron binary-missing → 'electron-broken: …' (#76: package present but
+ *      the exe never arrived — a repairable state the old boolean conflated
+ *      with never-installed; the reason names the dir and the fix)
  *    - platform === 'linux' && !env.DISPLAY → 'no-display'
  * 3. uiParam === true → 'ok' (explicit request overrides config and client gate, never hard guards)
  * 4. autoOpenConfig === false → 'config-disabled'
@@ -16,7 +19,9 @@
  *
  * @param {object} options
  * @param {string} options.client - The client type (e.g., 'code-local', 'cowork', 'code-web')
- * @param {boolean} options.electronUsable - Whether Electron is available
+ * @param {boolean} [options.electronUsable] - Legacy boolean probe (used only when electronState is absent)
+ * @param {'ok'|'package-missing'|'binary-missing'} [options.electronState] - 3-state probe (#76); takes precedence
+ * @param {string|null} [options.electronDir] - Resolved electron dir, named in the electron-broken reason
  * @param {string} options.platform - The platform (e.g., 'win32', 'darwin', 'linux')
  * @param {object} options.env - Environment variables object
  * @param {boolean} options.autoOpenConfig - The config.workspace.autoOpen setting
@@ -26,6 +31,8 @@
 function shouldAutoOpenWorkspace({
   client,
   electronUsable,
+  electronState,
+  electronDir,
   platform,
   env,
   autoOpenConfig,
@@ -36,10 +43,17 @@ function shouldAutoOpenWorkspace({
     return { open: false, reason: 'param-suppressed' };
   }
 
-  // Step 2: Hard guards (always checked, beat even explicit uiParam === true)
-  if (!electronUsable) {
+  // Step 2: Hard guards (always checked, beat even explicit uiParam === true).
+  // electronState (3-state, #76) wins over the legacy electronUsable boolean,
+  // whose false collapses to package-missing (the old 'electron-absent').
+  const state = electronState || (electronUsable ? 'ok' : 'package-missing');
+  if (state === 'package-missing') {
     return { open: false, reason: 'electron-absent' };
   }
+  if (state === 'binary-missing') {
+    const where = electronDir ? ` under ${electronDir}` : '';
+    return { open: false, reason: `electron-broken: binary missing${where} — run \`amicus doctor --fix\`` };
+  }
 
   if (platform === 'linux' && !env.DISPLAY) {
     return { open: false, reason: 'no-display' };

package/src/utils/doctor-electron-mcp-check.js

@@ -0,0 +1,150 @@
+/**
+ * @module utils/doctor-electron-mcp-check
+ * The `electron-mcp` doctor check ("Electron (MCP launch path)"), split out of
+ * src/cli-handlers-doctor.js to keep that file under the 300-line gate
+ * (mirrors doctor-engine-check.js, which did the same for the engine — #76 is
+ * the electron-flavored recurrence of that check's bug report #1).
+ *
+ * The existing `electron` check verifies Electron in the RUNNING install. This
+ * one verifies the copies the MCP actually launches from — the npx-cache
+ * installs `npx -y amicus@latest mcp` resolves to — so a green doctor can no
+ * longer hide an npx copy whose `ui: true` will fail with electron-absent.
+ *
+ * Severity is WARN at worst (never error): a broken Electron only costs the
+ * GUI; headless councils still work — same tier the running-copy check uses.
+ */
+
+'use strict';
+
+const HINTS = require('./remediation-hints');
+
+const plural = (n, one, many) => (n === 1 ? one : many);
+
+/** One-line detail for a broken copy, distinguishing the two states (#76). */
+const describeBroken = (i) => (i.state === 'binary-missing'
+  ? `${i.pkgDir} (binary missing; electron dir: ${i.electronDir})`
+  : `${i.pkgDir} (not installed)`);
+
+/**
+ * Enumerate the amicus installs that could serve the MCP and probe Electron in
+ * each via the dual-root resolver (#69 lesson: npx HOISTS electron to a
+ * sibling; a global install nests it).
+ * @param {object} [deps] engine-install-scan seams plus {readAmicusMcpConfig}
+ * @returns {{installs:Array<{kind,pkgDir,electronDir,state}>, mcpLaunch:string}}
+ */
+function scanElectronInstalls(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const platform = deps.platform || process.platform;
+  const readAmicusMcpConfig = deps.readAmicusMcpConfig
+    || (() => require('./mcp-discovery').readAmicusMcpConfig());
+  const { listAmicusInstalls, classifyLaunch } = require('./engine-install-scan');
+  const { electronDirFor, probeElectronState } = require('../sidecar/electron-state');
+
+  const installs = listAmicusInstalls(deps).map((i) => {
+    const probe = probeElectronState({ electronDir: electronDirFor(i.pkgDir, { fs }), fs, platform });
+    return { ...i, electronDir: probe.electronDir, state: probe.state };
+  });
+  let config = null;
+  try { config = readAmicusMcpConfig(); } catch { /* unreadable config */ }
+  return { installs, mcpLaunch: classifyLaunch(config) };
+}
+
+/**
+ * @param {{scanElectronInstalls: () => {installs:Array, mcpLaunch:string}}} d
+ * @returns {{id,name,status,message,hint}}
+ */
+function evaluateElectronInstalls(d) {
+  const id = 'electron-mcp';
+  const name = 'Electron (MCP launch path)';
+  const { installs, mcpLaunch } = d.scanElectronInstalls();
+
+  if (mcpLaunch === 'none') {
+    return { id, name, status: 'ok', message: 'no amicus MCP registered — not checked', hint: null };
+  }
+  if (mcpLaunch === 'path') {
+    return {
+      id, name, status: 'ok',
+      message: 'MCP launches from a fixed path — covered by the Electron (interactive GUI) check', hint: null,
+    };
+  }
+
+  // 'npx' (and the 'unknown' fallback): verify the npx-cache copies, the ones
+  // whose optional-dependency electron install can silently half-complete.
+  const npxCopies = installs.filter((i) => i.kind === 'npx');
+  if (npxCopies.length === 0) {
+    return {
+      id, name, status: 'warn',
+      message: 'MCP launches via npx; no cached copy to inspect yet — run one council, then re-run doctor',
+      hint: null,
+    };
+  }
+
+  const broken = npxCopies.filter((i) => i.state !== 'ok');
+  if (broken.length === 0) {
+    return {
+      id, name, status: 'ok',
+      message: `electron present in ${npxCopies.length} npx-cache ${plural(npxCopies.length, 'copy', 'copies')}`,
+      hint: null,
+    };
+  }
+
+  // `doctor --fix` can heal binary-missing (repairElectron); a never-installed
+  // package it cannot — keep the hint honest about which state is fixable.
+  const anyRepairable = broken.some((i) => i.state === 'binary-missing');
+  if (npxCopies.length === 1) {
+    const [only] = broken;
+    const message = only.state === 'binary-missing'
+      ? `electron binary missing in the npx-cache copy the MCP launches: ${only.pkgDir} (electron dir: ${only.electronDir})`
+      : `electron not installed in the npx-cache copy the MCP launches: ${only.pkgDir} — GUI auto-open unavailable; headless still works`;
+    return { id, name, status: 'warn', message, hint: anyRepairable ? HINTS.doctorFix : null };
+  }
+  const detail = broken.map(describeBroken).join('; ');
+  return {
+    id, name, status: 'warn',
+    message: `electron unavailable in ${broken.length}/${npxCopies.length} npx-cache copies: ${detail}`,
+    hint: anyRepairable ? HINTS.doctorFix : null,
+  };
+}
+
+/**
+ * Fix-aware wrapper. When d.fix and the scan shows binary-missing npx copies,
+ * heal each in place via d.repairElectron({electronDir}) — the package dir is
+ * already on disk, so repairElectron can read its version and provision the
+ * exe — then re-report from a fresh scan. package-missing copies are never
+ * repaired (no package to repair into). Mirrors evaluateEngineMcp.
+ * @param {object} d doctor deps (scanElectronInstalls, fix?, repairElectron?, fixTimeoutMs?)
+ * @returns {Promise<{id,name,status,message,hint}>}
+ */
+async function evaluateElectronMcp(d) {
+  const verdict = evaluateElectronInstalls(d);
+  if (!d.fix || verdict.status === 'ok') { return verdict; }
+
+  const { installs } = d.scanElectronInstalls();
+  const repairable = installs.filter((i) => i.kind === 'npx' && i.state === 'binary-missing');
+  if (repairable.length === 0) { return verdict; }
+
+  const results = [];
+  for (const b of repairable) {
+    let r;
+    try {
+      r = await d.repairElectron({
+        electronDir: b.electronDir,
+        ...(d.fixTimeoutMs ? { timeoutMs: d.fixTimeoutMs } : {}),
+      });
+    } catch (e) { r = { repaired: false, reason: e && e.message }; }
+    results.push({ electronDir: b.electronDir, ...r });
+  }
+
+  const after = evaluateElectronInstalls(d); // fresh scan reflects the repairs
+  if (after.status === 'ok') {
+    const n = results.length;
+    return { ...after, message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})` };
+  }
+  const failed = results.filter((r) => !r.repaired)
+    .map((r) => `${r.electronDir}${r.reason ? ` — ${r.reason}` : ''}`).join('; ');
+  return failed
+    ? { ...after, message: `${after.message}; self-heal incomplete: ${failed}` }
+    : after;
+}
+
+module.exports = { scanElectronInstalls, evaluateElectronInstalls, evaluateElectronMcp };