amicus 4.5.0 → 4.5.2

package/schemas/council-verdict.schema.json

@@ -4,53 +4,207 @@
   "title": "amicus council-verdict document",
   "description": "Verdict record (`council verdict --json`, amicus_verdict, verdict.json). overallVerdict is the chair's parsed VERDICT line — null in every Stage-4 manual path, populated by the headless engine.",
   "type": "object",
-  "required": ["schemaVersion", "type", "runId", "council", "overallVerdict", "findings", "streetCred", "runStats", "tierCounts"],
+  "required": [
+    "schemaVersion",
+    "type",
+    "runId",
+    "council",
+    "overallVerdict",
+    "findings",
+    "streetCred",
+    "runStats",
+    "tierCounts"
+  ],
   "properties": {
-    "schemaVersion": { "const": 2 },
-    "type": { "const": "council-verdict" },
-    "runId": { "type": "string" },
-    "runType": { "type": ["string", "null"] },
-    "date": { "type": ["string", "null"] },
-    "chair": { "type": ["string", "null"] },
-    "council": { "type": "array", "items": { "type": "string" } },
-    "claudeInCouncil": { "type": "boolean" },
+    "schemaVersion": {
+      "const": 2
+    },
+    "type": {
+      "const": "council-verdict"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "runType": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "date": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chair": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "council": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "claudeInCouncil": {
+      "type": "boolean"
+    },
     "overallVerdict": {
       "oneOf": [
-        { "enum": ["Ship it", "Fix these first", "Fundamental rethink"] },
-        { "type": "null" }
+        {
+          "enum": [
+            "Ship it",
+            "Fix these first",
+            "Fundamental rethink"
+          ]
+        },
+        {
+          "type": "null"
+        }
       ]
     },
     "findings": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "tier", "decision", "applied"],
+        "required": [
+          "id",
+          "tier",
+          "decision",
+          "applied"
+        ],
         "properties": {
-          "id": { "type": "string" },
-          "raiser": { "type": ["string", "null"] },
-          "severity": { "type": ["string", "null"] },
-          "tier": { "enum": ["Confirmed", "Contested", "Singleton", "Disputed"] },
-          "basis": { "type": "object" },
-          "confidence": { "enum": ["thin", "solid"] },
-          "tierOverride": { "type": ["object", "null"] },
-          "duplicateOf": { "type": ["string", "null"] },
-          "adjudications": { "type": "array" },
-          "decision": { "type": ["string", "null"] },
-          "applied": { "type": "boolean" },
+          "id": {
+            "type": "string"
+          },
+          "raiser": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "severity": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "tier": {
+            "enum": [
+              "Confirmed",
+              "Contested",
+              "Singleton",
+              "Disputed"
+            ]
+          },
+          "basis": {
+            "type": "object"
+          },
+          "confidence": {
+            "enum": [
+              "thin",
+              "solid"
+            ]
+          },
+          "tierOverride": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "duplicateOf": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "adjudications": {
+            "type": "array"
+          },
+          "decision": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "applied": {
+            "type": "boolean"
+          },
           "debate": {
             "type": "object",
             "properties": {
-              "action": { "enum": ["defended", "amended", "withdrawn", "no-response"] },
-              "previousTier": { "type": ["string", "null"] }
+              "action": {
+                "enum": [
+                  "defended",
+                  "amended",
+                  "withdrawn",
+                  "no-response"
+                ]
+              },
+              "previousTier": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
             },
-            "required": ["action"],
+            "required": [
+              "action"
+            ],
             "additionalProperties": false
           }
         }
       }
     },
-    "streetCred": { "type": "array", "items": { "type": "object" } },
-    "runStats": { "type": "array", "items": { "type": "object" } },
-    "tierCounts": { "type": "object" }
+    "streetCred": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "runStats": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "tierCounts": {
+      "type": "object"
+    },
+    "seatLoss": {
+      "type": "object",
+      "description": "Present only when --critic was requested. Records whether the adversarial seat actually reviewed: a dead critic wave is survivable (the quorum gate guards only the bench), so a run can otherwise reach a full verdict with the critic silently absent.",
+      "properties": {
+        "criticRequested": {
+          "type": "string",
+          "description": "The model asked for as critic."
+        },
+        "criticSeated": {
+          "type": "boolean",
+          "description": "False when the critic wave died before producing legs."
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Why the critic wave died, when it did."
+        },
+        "deadBenchSeats": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Bench models lost to dead waves, excluding the critic."
+        }
+      },
+      "required": [
+        "criticRequested",
+        "criticSeated"
+      ]
+    }
   }
 }

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/council/run-assemble.js

@@ -19,7 +19,7 @@
 const fs = require('fs');
 const path = require('path');
 const { writeFileAtomic } = require('../utils/atomic-write');
-const { buildVerdict, writeVerdictAtomic } = require('./verdict');
+const { buildVerdict, summarizeSeatLoss, writeVerdictAtomic } = require('./verdict');
 const { buildReport } = require('./report');
 const { validateFindings } = require('./findings');
 const { toGlobalFindings } = require('./anonymize');
@@ -178,8 +178,12 @@ function writeTallyFiles({ runDir, tallyInput, record }) {
  * buildVerdict's own signature.
  * @returns {object} the verdict written to disk
  */
-function writeVerdictFiles({ runDir, record, overallVerdict, chairText }) {
-  const verdict = buildVerdict(record, []);
+function writeVerdictFiles({ runDir, record, overallVerdict, chairText, critic, deadWaves }) {
+  // v4.5.2 — computed here rather than in run.js so verdict assembly stays in
+  // one place; see summarizeSeatLoss in ./verdict for why a lost critic has to
+  // reach the verdict at all.
+  const seatLoss = summarizeSeatLoss({ runId: record.meta.runId, critic, deadWaves });
+  const verdict = buildVerdict(record, [], { seatLoss });
   verdict.overallVerdict = (overallVerdict === undefined) ? null : overallVerdict;
   writeVerdictAtomic(path.join(runDir, 'verdict.json'), verdict);
   const html = buildReport({ verdict }, { format: 'html' });

package/src/council/run.js

@@ -284,7 +284,8 @@ async function runCouncil(options, deps = {}) {
     runState.updateStage(o.runDir, tallyStage, { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, tallyStage, null, o.follow);
     emitStageTerminal(o.runDir, o.runId, tallyStage, 'complete', null, o.follow);
-    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
+    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText,
+      critic: o.critic, deadWaves });
     runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
     emitStageStarted(o.runDir, o.runId, 'verdict', null, o.follow);
     emitStageTerminal(o.runDir, o.runId, 'verdict', 'complete', null, o.follow);

package/src/council/verdict.js

@@ -16,6 +16,44 @@ const VERDICT_SCHEMA_VERSION = 2;
  * @param {{overallVerdict?: (string|null)}} [opts] engine hook (Plan B): the
  *   parsed chair `VERDICT:` line; omitted/undefined → null.
  */
+/**
+ * Describe which requested seats actually reviewed, for the verdict's own face.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. The critic is a SOLO wave with one leg,
+ * so losing it loses 100% of the adversarial role — and unlike a dead bench wave
+ * (which trips the quorum gate and fails the run loudly) a dead critic is
+ * survivable, so the run continues to a full verdict, tally and chair synthesis
+ * that never saw the critic's findings. Run `dfb6a692` did exactly that and the
+ * only record was `deadWaves` in run.json, a file nobody opens when the verdict
+ * reads clean. A user who typed `--critic` asked for adversarial review; a
+ * verdict produced without it must say so where the verdict is read.
+ *
+ * Returns null when no critic was requested — there is nothing to report, and an
+ * always-present block would train readers to ignore it.
+ *
+ * @param {{runId: string, critic: ?string,
+ *   deadWaves: Array<{waveId: string, models: string[], reason: string}>}} o
+ * @returns {?{criticRequested: string, criticSeated: boolean, reason: ?string,
+ *   deadBenchSeats: string[]}}
+ */
+function summarizeSeatLoss({ runId, critic, deadWaves = [] } = {}) {
+  if (!critic) { return null; }
+  // Match on EITHER carrier. The `-c1` suffix is the convention run-stages.js
+  // uses, but a wave that names the critic model is the critic wave whatever it
+  // is called — and relying on the id alone would silently under-report if that
+  // convention ever changes.
+  const isCriticWave = w =>
+    w.waveId === `${runId}-c1` || (w.models || []).includes(critic);
+  const dead = deadWaves.find(isCriticWave) || null;
+  return {
+    criticRequested: critic,
+    criticSeated: !dead,
+    reason: dead ? dead.reason : null,
+    deadBenchSeats: deadWaves.filter(w => !isCriticWave(w))
+      .flatMap(w => w.models || []),
+  };
+}
+
 function buildVerdict(record, decisions = [], opts = {}) {
   const byId = new Map(decisions.map(d => [d.id, d]));
   return {
@@ -46,6 +84,9 @@ function buildVerdict(record, decisions = [], opts = {}) {
     streetCred: record.streetCred.map(s => ({ model: s.model, withSelf: s.withSelf, peersOnly: s.peersOnly })),
     runStats: record.runStats,
     tierCounts: record.tierCounts,
+    // Additive and OPTIONAL (schemaVersion stays 2): present only when a critic
+    // was requested, so its absence never has to be interpreted.
+    ...(opts.seatLoss ? { seatLoss: opts.seatLoss } : {}),
   };
 }
 
@@ -93,4 +134,6 @@ function writeVerdictAtomic(filePath, verdict) {
   fs.renameSync(tmp, filePath);
 }
 
-module.exports = { buildVerdict, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION };
+module.exports = {
+  buildVerdict, summarizeSeatLoss, readOverallVerdict, writeVerdictAtomic, VERDICT_SCHEMA_VERSION,
+};

package/src/headless.js

@@ -272,6 +272,12 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       if (options.mcp) {
         serverOptions.mcp = options.mcp;
       }
+      // v4.5.2: explicit per-call override only — see the note at the matching
+      // hop in src/sidecar/session-utils.js. The default and the env knob both
+      // resolve downstream in buildServerOptions.
+      if (options.timeout !== undefined) {
+        serverOptions.timeout = options.timeout;
+      }
       // v4.4.1 fix wave (F5): this is the OTHER server-start site. It calls
       // startServer directly rather than going through startOpenCodeServer, so
       // the lock-class retry added for the concurrent-start race never covered

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/opencode-client.js

@@ -402,11 +402,67 @@ async function getSessionStatus(client, sessionId, directory) {
   return result.data || {};
 }
 
+/**
+ * How long to wait for OpenCode to announce it is listening, per platform.
+ *
+ * ⚠️ ADDED v4.5.2 from a field report. `@opencode-ai/sdk` defaults this to
+ * 5000ms (`dist/server.js:4-8`) and lets the caller override it; amicus never
+ * passed one, so every start on every platform ran on the SDK's 5s — untunable
+ * and invisible to `amicus doctor`. A reporter's Windows box (project on a
+ * OneDrive-synced volume, Defender active) blew through it on a cold
+ * OpenCode/SQLite open: the council's shared server failed to acquire, the run
+ * degraded to the per-wave configuration `src/council/run-server.js` exists to
+ * eliminate, and the whole Stage-1 bench died (`COUNCIL_QUORUM: Only 0 …`).
+ *
+ * The asymmetry decides the number: a slow start costs LATENCY, a failed start
+ * costs a REVIEW SEAT. win32 gets the widest window because that is where
+ * sync-backed volumes and always-on AV filter drivers are the norm.
+ *
+ * This is a ceiling, not a sleep — a healthy start still resolves in well under
+ * a second and pays none of it.
+ */
+const SERVER_START_TIMEOUT_MS = Object.freeze({ win32: 30000, default: 15000 });
+
+/**
+ * Resolve the start timeout: explicit option → env override → platform default.
+ *
+ * `0` and negatives are REJECTED rather than honored. For most amicus knobs `0`
+ * is a documented disable switch (see src/utils/env-num.js), but a 0ms start
+ * timeout disables nothing — it fails every start instantly. That is an own-goal
+ * an operator can only reach by accident, so it falls back to the default.
+ *
+ * @param {object} [options] - Server options ({timeout} respected if positive)
+ * @param {object} [env] - Environment (test seam; defaults to process.env)
+ * @param {string} [platform] - Platform (test seam; defaults to process.platform)
+ * @returns {number} milliseconds
+ */
+function resolveServerStartTimeoutMs(options = {}, env, platform) {
+  const plat = platform || process.platform;
+  const dflt = SERVER_START_TIMEOUT_MS[plat] || SERVER_START_TIMEOUT_MS.default;
+  const positive = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+  if (options.timeout !== undefined) {
+    const explicit = positive(options.timeout);
+    if (explicit) { return explicit; }
+  }
+  const raw = (env || process.env).AMICUS_SERVER_START_TIMEOUT_MS;
+  if (raw !== undefined && raw !== null && String(raw).trim() !== '') {
+    const fromEnv = positive(raw);
+    if (fromEnv) { return fromEnv; }
+  }
+  return dflt;
+}
+
 /**
  * Build the server options object for createOpencodeServer.
  * Extracted for testability (no SDK dependency).
  *
  * @param {object} [options] - Server options
+ * @param {number} [options.timeout] - Start timeout in ms. Omit to use
+ *   AMICUS_SERVER_START_TIMEOUT_MS or the platform default; NEVER omitted from
+ *   the object handed to the SDK, so the SDK's own 5000ms default is unreachable.
  * @param {number} [options.port] - Port to run on
  * @param {string} [options.hostname='127.0.0.1'] - Hostname to bind to
  * @param {AbortSignal} [options.signal] - Abort signal to stop server
@@ -544,6 +600,9 @@ function buildServerOptions(options = {}) {
 
   const serverOptions = {
     hostname: options.hostname || '127.0.0.1',
+    // ALWAYS set — unlike port/signal below, an omitted timeout is not a
+    // harmless "let the SDK decide", it is the 5000ms that cost a bench.
+    timeout: resolveServerStartTimeoutMs(options),
   };
 
   // Only include port/signal when explicitly set — passing undefined
@@ -660,11 +719,27 @@ async function startServer(options = {}) {
     }
   }
 
-  const createOpencodeServer = await getCreateOpencodeServer();
+  // `_createOpencodeServer` is a test seam, matching `_hasOpencodeBinary` /
+  // `_ensureEngine` / `_opencodeRoots` above: the SDK arrives through a dynamic
+  // `import()`, which `jest.mock` cannot intercept under CommonJS, so the start
+  // path is otherwise unreachable from a unit test.
+  const createOpencodeServer = options._createOpencodeServer
+    || await getCreateOpencodeServer();
   const serverOptions = buildServerOptions(options);
 
+  // Measure the healthy path. The v4.5.2 timeout had to be sized from the
+  // asymmetry of the failure (a slow start costs latency, a failed one costs a
+  // review seat) because nothing recorded how long a GOOD start takes — so the
+  // margin against the ceiling was unmeasurable on exactly the slow boxes that
+  // needed it. Now it is one debug line, not an inference.
+  const startedAt = Date.now();
   const sdkServer = await createOpencodeServer(serverOptions);
-  const client = await createClient(sdkServer.url);
+  const { logger } = require('./utils/logger');
+  logger.debug('OpenCode server started', {
+    startMs: Date.now() - startedAt,
+    timeoutMs: serverOptions.timeout,
+  });
+  const client = await (options._createClient || createClient)(sdkServer.url);
 
   // Capture the Go server PID once so close() can force-kill it cross-platform
   // (F3 #15). Prefer a PID the SDK exposes; fall back to the port listener.
@@ -822,6 +897,8 @@ module.exports = {
   abortSession,
   checkHealth,
   buildServerOptions,
+  resolveServerStartTimeoutMs,
+  SERVER_START_TIMEOUT_MS,
   buildServerHandle,
   startServer,
   loadMcpConfig,

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/session-utils.js

@@ -253,6 +253,10 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.models) { serverOptions.models = options.models; }
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
+  // Explicit per-call override only. Unset is the normal case and is correct:
+  // buildServerOptions resolves AMICUS_SERVER_START_TIMEOUT_MS / the platform
+  // default downstream, so forwarding `undefined` here would change nothing.
+  if (options.timeout !== undefined) { serverOptions.timeout = options.timeout; }
 
   // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
   // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).

package/src/sidecar/unzip.js

@@ -173,7 +173,22 @@ async function robustExtract(zip, opts = {}) {
     deps = {},
   } = opts;
   const fs = deps.fs || fsDefault;
-  const extractZip = deps.extractZip || require('extract-zip');
+  // GUARDED (v4.5.2). This `require` used to be bare, and `extract-zip` was
+  // never declared in dependencies — it resolved in the dev tree only because
+  // `puppeteer` (a devDependency) pulls it transitively, so a published install
+  // threw MODULE_NOT_FOUND here and took the WHOLE function with it: the native
+  // fallback below, the bounded idle/max timers, and `doctor --fix` all became
+  // unreachable. The dependency is now declared, so this should never fire —
+  // but Strategy 1 being unavailable is precisely what the native strategies
+  // exist for, so it must degrade into them rather than out of the function.
+  let extractZip = deps.extractZip;
+  if (!extractZip) {
+    try {
+      extractZip = require('extract-zip');
+    } catch (e) {
+      extractZip = () => { throw new Error(`extract-zip unavailable: ${e.message}`); };
+    }
+  }
   const spawn = deps.spawn || spawnSync;
   const setTimer = deps.setTimeout || setTimeout;
   const clearTimer = deps.clearTimeout || clearTimeout;

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' };