amicus 4.5.4 → 4.6.1

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

@@ -113,7 +113,7 @@ function evaluateElectronInstalls(d) {
  * 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}>}
+ * @returns {Promise<{id,name,status,message,hint,fixed?,fixDetail?}>}
  */
 async function evaluateElectronMcp(d) {
   const verdict = evaluateElectronInstalls(d);
@@ -138,13 +138,72 @@ async function evaluateElectronMcp(d) {
   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')})` };
+    return {
+      ...after,
+      message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})`,
+      fixed: true,
+      fixDetail: `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('; ');
+  // Partial credit: some copies healed even though the check overall is still
+  // not 'ok' — flag it ONLY when >=1 repair actually succeeded (#84-style rule).
+  const healed = results.filter((r) => r.repaired).length;
+  const fixFields = healed > 0
+    ? { fixed: true, fixDetail: `self-healed ${healed} npx-cache ${plural(healed, 'copy', 'copies')}` }
+    : {};
   return failed
-    ? { ...after, message: `${after.message}; self-heal incomplete: ${failed}` }
-    : after;
+    ? { ...after, message: `${after.message}; self-heal incomplete: ${failed}`, ...fixFields }
+    : { ...after, ...fixFields };
+}
+
+/**
+ * The interactive-GUI electron check (`id: 'electron'`), moved verbatim from
+ * cli-handlers-doctor.js (v4.6 Plan 3 Task 1) for the 300-line gate — this
+ * file already owns the electron-flavored doctor logic (#76). Behavior
+ * identical; the only change is `fixTimeoutMs` arriving as a parameter
+ * instead of a closure constant.
+ * @param {object} d doctor deps (getElectronPath, fix?, repairElectron)
+ * @param {{fixTimeoutMs: number}} opts
+ * @returns {Promise<{id,name,status,message,hint,fixed?,fixDetail?}>}
+ */
+async function evaluateElectronInteractive(d, { fixTimeoutMs }) {
+  if (d.getElectronPath()) {
+    return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null };
+  }
+  // Broken (missing / quarantined). With --fix, self-heal in place (#56):
+  // repairElectron provisions the binary; {deferred} (no cache, no network)
+  // maps to WARN — a deferred download is not a failure. Without --fix, just
+  // point the user at `amicus doctor --fix`.
+  if (d.fix) {
+    let res;
+    try {
+      res = await d.repairElectron({ timeoutMs: fixTimeoutMs });
+    } catch (e) {
+      return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `repair failed: ${e.message} — headless still works`, hint: HINTS.doctorFix };
+    }
+    res = res || {};
+    if (res.repaired) {
+      return {
+        id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed (self-healed)', hint: null,
+        fixed: true, fixDetail: 'provisioned the Electron binary in place',
+      };
+    }
+    const why = res.reason ? ` — ${res.reason}` : '';
+    // Quarantine (AV deleted electron.exe post-extract) is NOT a deferral and
+    // must NEVER be silently retried: surface the allow-list instruction as a
+    // WARN and STOP. No re-run of repairElectron here (no loop).
+    const detail = res.quarantined
+      ? `antivirus quarantine${why}`
+      : res.deferred
+        ? `deferred${why}`
+        : res.contended
+          ? `repair already in progress${why}`
+          : `not provisioned${why}`;
+    return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: `${detail} — headless still works`, hint: HINTS.doctorFix };
+  }
+  return { id: 'electron', name: 'Electron (interactive GUI)', status: 'warn', message: 'not installed — headless still works', hint: HINTS.doctorFix };
 }
 
-module.exports = { scanElectronInstalls, evaluateElectronInstalls, evaluateElectronMcp };
+module.exports = { scanElectronInstalls, evaluateElectronInstalls, evaluateElectronMcp, evaluateElectronInteractive };

package/src/utils/doctor-engine-check.js

@@ -73,7 +73,7 @@ function evaluateEngineInstalls(d) {
  * the engine into each via d.repairEngine, then re-report from a fresh scan.
  * Without d.fix — or when nothing is copy-fixable — returns the plain verdict.
  * @param {object} d doctor deps (scanEngineInstalls, fix?, repairEngine?)
- * @returns {Promise<{id,name,status,message,hint}>}
+ * @returns {Promise<{id,name,status,message,hint,fixed?,fixDetail?}>}
  */
 async function evaluateEngineMcp(d) {
   const verdict = evaluateEngineInstalls(d);
@@ -94,11 +94,22 @@ async function evaluateEngineMcp(d) {
   const after = evaluateEngineInstalls(d); // fresh scan reflects the copies
   if (after.status === 'ok') {
     const n = results.length;
-    return { ...after, message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})` };
+    return {
+      ...after,
+      message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})`,
+      fixed: true,
+      fixDetail: `copied the engine into ${n} npx-cache ${plural(n, 'copy', 'copies')}`,
+    };
   }
   const failed = results.filter((r) => !r.repaired)
     .map((r) => `${r.pkgDir}${r.reason ? ` — ${r.reason}` : ''}`).join('; ');
-  return { ...after, message: `${after.message}; self-heal incomplete: ${failed}` };
+  // Partial credit: some copies healed even though the check overall is still
+  // not 'ok' — flag it ONLY when >=1 repair actually succeeded (#84-style rule).
+  const healed = results.filter((r) => r.repaired).length;
+  const fixFields = healed > 0
+    ? { fixed: true, fixDetail: `copied the engine into ${healed} npx-cache ${plural(healed, 'copy', 'copies')}` }
+    : {};
+  return { ...after, message: `${after.message}; self-heal incomplete: ${failed}`, ...fixFields };
 }
 
 module.exports = { evaluateEngineInstalls, evaluateEngineMcp };

package/src/utils/doctor-mcp-checks.js

@@ -68,14 +68,21 @@ function evaluateLegacyMcpEntry(d) {
   }
   if (d.fix) {
     const removed = (d.migrateLegacyMcpEntries() || []).filter(r => r.result === 'removed');
+    // Structured fix outcome (v4.6 Plan 3 Task 3): a repaired row carries
+    // fixed/fixDetail whenever ANY entry was actually removed, even on the
+    // partial-failure path below — a genuine no-op (removed.length === 0)
+    // stays unflagged.
+    const fixFields = removed.length > 0
+      ? { fixed: true, fixDetail: `removed the duplicate legacy 'sidecar' entry from ${removed.map(r => r.target).join(', ')}` }
+      : {};
     if (removed.length >= dupes.length) {
       const message = `removed legacy entry from: ${removed.map(r => r.target).join(', ')}`;
       return unreadableNote
-        ? { id, name, status: 'warn', message: `${message}; ${unreadableNote}`, hint: HINTS.removeLegacySidecar }
-        : { id, name, status: 'ok', message, hint: null };
+        ? { id, name, status: 'warn', message: `${message}; ${unreadableNote}`, hint: HINTS.removeLegacySidecar, ...fixFields }
+        : { id, name, status: 'ok', message, hint: null, ...fixFields };
     }
     const message = `removed ${removed.length}/${dupes.length} duplicate(s) — could not update every config`;
-    return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };
+    return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar, ...fixFields };
   }
   const message = `duplicate 'sidecar' entry in ${dupes.map(e => e.target).join(', ')} — doubles the MCP tool list`;
   return { id, name, status: 'warn', message: unreadableNote ? `${message}; ${unreadableNote}` : message, hint: HINTS.removeLegacySidecar };

package/src/utils/known-flags.js

@@ -29,7 +29,7 @@
  * Real flags that appear in NO usage block. Rejecting any of these would break
  * working callers, so they are enumerated deliberately rather than derived.
  *
- * ⚠️ The first four are spawned by the MCP server onto its own CLI children
+ * ⚠️ These are spawned by the MCP server onto its own CLI children
  * (src/mcp-server.js, src/mcp-council-run.js). They are not user-facing and are
  * intentionally undocumented — but they are on the argv of every MCP-launched
  * run, so rejecting them would break the entire MCP surface.
@@ -39,6 +39,7 @@ const INTERNAL_FLAGS = new Set([
   'run-id',          // MCP → `council run`: pins the child's run id
   'council-name',    // MCP → `council run`: preset name for ledger attribution
   'cowork-process',  // MCP → `start`: Cowork process handle for context capture
+  'dropped-members', // MCP → 'council run': per-member preset drops as JSON (v4.6 Plan 4)
 
   // User-facing but undocumented, and read by real handlers today. Listed so the
   // rejection is a bug fix and not a silent removal of working behaviour; if any

package/src/utils/remediation-hints.js

@@ -33,7 +33,7 @@ const REMEDIATION_HINTS = Object.freeze({
    */
   reinstallEngineAv:
     '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). '
-    + 'If your antivirus (e.g. Windows Defender) quarantined opencode.exe, allow-list it first, then reinstall.',
+    + 'If your antivirus (e.g. Windows Defender) quarantined opencode.exe — unverified, but a known cause — allow-list it first, then reinstall.',
 
   /**
    * Runtime server-start failure when the opencode engine binary does not
@@ -41,27 +41,27 @@ const REMEDIATION_HINTS = Object.freeze({
    * spawn ENOENT — surfaced by startServer (the missing-binary boundary).
    */
   engineMissing:
-    'OpenCode engine binary not found — it was likely skipped during install or quarantined by antivirus. '
-    + 'Run "amicus doctor", reinstall with "npm i -g amicus", and allow-list opencode.exe in your antivirus.',
+    'OpenCode engine binary not found — the cause was not verified. Common causes (unverified): '
+    + 'an install that skipped or rolled back the engine packages, or antivirus quarantine of opencode.exe. '
+    + 'Run "amicus doctor" to check the actual install, reinstall with "npm i -g amicus", '
+    + 'and allow-list opencode.exe in your antivirus if quarantine was the cause.',
 
   /** Electron absent — reinstall to add the interactive GUI (headless still works). */
   reinstallElectron: 'npm install -g amicus  (reinstall to add Electron)',
 
-  /**
-   * Electron present but broken (ABI mismatch / partial unpack). Delete the
-   * vendored copy and reinstall to force a clean rebuild.
-   */
-  rebuildElectron:
-    'rm -rf node_modules/electron && npm install -g amicus  (rebuild Electron after an ABI mismatch or partial unpack)',
-
   /** Point the user at the single recovery hub. */
   runDoctor: 'run: amicus doctor  (diagnoses config, keys, engine & MCP, with copy-paste fixes)',
 
   /**
-   * Self-heal the optional Electron GUI in place (#56). This is the convergence
-   * target for the three "reinstall to fix Electron" hints — it provisions the
-   * binary from cache (or downloads on demand) WITHOUT a global reinstall, so it
-   * can't loop the way `npm install -g amicus` could when the rollback recurs.
+   * Self-heal the optional Electron GUI in place (#56). The convergence target
+   * for the "reinstall to fix Electron" hints — it provisions the binary from
+   * cache (or downloads on demand) WITHOUT a global reinstall, so it can't
+   * loop the way `npm install -g amicus` could when the rollback recurs.
+   * (`rebuildElectron`, the manual rm-rf-and-reinstall variant, was deleted
+   * 2026-08-03 by owner ruling: no live call site once this hint became the
+   * target, and its prose asserted unverified causes. A reintroduction must
+   * use the unverified-cause voice — absence-pinned in
+   * tests/remediation-hints.test.js.)
    */
   doctorFix: 'amicus doctor --fix  (self-heal the Electron GUI in place — provisions the binary; no reinstall, so it can\'t loop)',
 
@@ -78,6 +78,12 @@ const REMEDIATION_HINTS = Object.freeze({
    * atomic tmp-write and rename leaves a stray temp file in the config dir
    * forever. `doctor --fix` sweeps files older than 60s (never a live writer's
    * ms-lived tmp).
+   *
+   * Voice ruling (Christian, 2026-08-03): this hint keeps its confident cause.
+   * "Left by an interrupted write" is definitional, not a guess — the atomic
+   * write pattern admits no other producer, and the age gate excludes live
+   * writers — so the Plan 3 unverified-cause voice deliberately does NOT
+   * apply. Do not re-file it against that criterion.
    */
   sweepSessionIndexTmp:
     'amicus doctor --fix  (sweeps orphaned .sessions-index.json.*.tmp files left by an interrupted write)',

package/src/utils/result-schema.js

@@ -209,9 +209,10 @@ function buildAuditDoc({ stale, catalogAvailable, gatewayFindings = [] }) {
 
 /**
  * Build a doctor health-check document (`doctor --json`).
- * @param {{version: string, timestamp: string, checks: Array<{id,name,status,message,hint}>}} opts
+ * @param {{version: string, timestamp: string, checks: Array<{id,name,status,message,hint}>,
+ *   degrades?: Array<{kind,channel,what,why,effect,remedy?,data?}>}} opts
  */
-function buildDoctorDoc({ version, timestamp, checks }) {
+function buildDoctorDoc({ version, timestamp, checks, degrades }) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'doctor',
@@ -219,6 +220,9 @@ function buildDoctorDoc({ version, timestamp, checks }) {
     version,
     timestamp,
     checks,
+    // v4.6 Plan 3 (spec §4/§6): the shared-vocabulary surface. Additive and
+    // OPTIONAL — present only when a check failed or --fix repaired something.
+    ...(degrades && degrades.length ? { degrades } : {}),
   };
 }
 

package/src/utils/session-index-tmp-sweep.js

@@ -70,7 +70,8 @@ function evaluateSessionIndexTmpSweep(d) {
   }
   const remaining = files.length - swept;
   if (remaining === 0) {
-    return { id, name, status: 'ok', message: `swept ${swept} orphaned tmp file(s)`, hint: null };
+    const fixFields = swept > 0 ? { fixed: true, fixDetail: `swept ${swept} orphaned session-index tmp file(s)` } : {};
+    return { id, name, status: 'ok', message: `swept ${swept} orphaned tmp file(s)`, hint: null, ...fixFields };
   }
   return { id, name, status: 'warn', message: `swept ${swept}, ${remaining} remaining (too fresh or unremovable)`, hint: HINTS.sweepSessionIndexTmp };
 }

package/src/utils/update-notice.js

@@ -0,0 +1,171 @@
+/**
+ * @module utils/update-notice — "a newer amicus exists" for the MCP channel
+ *
+ * The MCP server is the one entry point that skips bin/amicus.js's update
+ * banner (deliberately — stdout is protocol). This module is the MCP-shaped
+ * replacement (spec docs/superpowers/specs/2026-08-03-mcp-update-notice-design.md):
+ * updater.js's cached check rendered as ONE appended text content block on the
+ * first successful tool result of the process (latched, D1), plus an always-on
+ * line in amicus_guide.
+ *
+ * Voice contract (v4.6 hint ruling): the version pair is verified fact; the
+ * upgrade instruction is stated as fact only when derived from a readable MCP
+ * registration config — fallbacks keep the "likely" hedge. Everything here is
+ * advisory: every export swallows its own failures rather than throwing into
+ * a tool result.
+ */
+
+'use strict';
+
+/** Upgrade wordings (spec §4). Config-derived rows are verified-voiced;
+ *  NPX_CACHED_LINE keeps the hedge — the config read is best-effort. */
+const GLOBAL_LINE = 'Run `npm install -g amicus`, then restart your MCP client.';
+const NPX_LATEST_LINE = 'Restart your MCP client — it launches `amicus@latest` and will pick up the new version.';
+const NPX_CACHED_LINE = 'Your MCP config likely launches a cached/pinned npx copy; '
+  + 'point it at `npx -y amicus@latest mcp` (or clear the npx cache), then restart your MCP client.';
+const GENERIC_LINE = 'Upgrade your amicus install, then restart your MCP client.';
+
+const CHANGELOG_URL = 'https://github.com/BourbonDog/amicus/blob/main/CHANGELOG.md';
+
+/**
+ * Flavor of THIS install — the copy serving the current process. Pure path
+ * heuristic on the realpath of our own package.json (no `npm root -g` shellout
+ * on the tool-result path): a `_npx` segment is the npx cache; any other
+ * `node_modules` home is a global-style install; no `node_modules` at all is a
+ * dev clone or similar.
+ * @param {{fs?: object, pkgPath?: string}} [deps]
+ * @returns {'global'|'npx'|'other'}
+ */
+function classifySelfInstall(deps = {}) {
+  const fs = deps.fs || require('fs');
+  const pkgPath = deps.pkgPath || require('./version-info').PKG_PATH;
+  try {
+    // Split the raw realpath — NOT path.dirname first: dirname is platform-
+    // bound (posix dirname collapses a foreign backslash path to '.', the CI
+    // path-fixture failure class), and the basename 'package.json' can never
+    // collide with the segment names probed here.
+    const parts = fs.realpathSync(pkgPath).split(/[\\/]/);
+    if (parts.includes('_npx')) { return 'npx'; }
+    if (parts.includes('node_modules')) { return 'global'; }
+    return 'other';
+  } catch {
+    return 'other';
+  }
+}
+
+/**
+ * True when some RAW config arg is the amicus package token pinned `@latest`.
+ * Raw on purpose: mcp-self-identity's normalizeToken strips `@version`
+ * suffixes, which is exactly the information this check needs.
+ * @param {{args?: unknown[]}|null|undefined} config
+ */
+function pinsAmicusLatest(config) {
+  const args = Array.isArray(config && config.args) ? config.args : [];
+  return args.some((a) => {
+    const t = String(a).toLowerCase().replace(/\\/g, '/');
+    const base = t.includes('/') ? t.slice(t.lastIndexOf('/') + 1) : t;
+    return base === 'amicus@latest';
+  });
+}
+
+/**
+ * The one correct upgrade move for this install (spec §4), chosen
+ * config-first (what a RESTART will launch), self-path fallback.
+ * Never throws; worst case is the generic line.
+ * @param {{readConfig?: Function, classifyLaunch?: Function, selfFlavor?: Function}} [deps]
+ * @returns {string}
+ */
+function upgradeInstruction(deps = {}) {
+  try {
+    const readConfig = deps.readConfig
+      || (() => require('./mcp-discovery').readAmicusMcpConfig());
+    const classifyLaunchFn = deps.classifyLaunch
+      || require('./engine-install-scan').classifyLaunch;
+    const selfFlavor = deps.selfFlavor || (() => classifySelfInstall(deps));
+
+    let config = null;
+    try { config = readConfig(); } catch { config = null; }
+
+    const launch = classifyLaunchFn(config);
+    if (launch === 'npx') {
+      return pinsAmicusLatest(config) ? NPX_LATEST_LINE : NPX_CACHED_LINE;
+    }
+    if (launch === 'path') {
+      // A path registration launches (approximately) the running copy — let
+      // its flavor pick between the npm-global move and the generic one.
+      return selfFlavor() === 'global' ? GLOBAL_LINE : GENERIC_LINE;
+    }
+    // 'none' / 'unknown' — config unreadable or unrecognized: self-path fallback.
+    const flavor = selfFlavor();
+    if (flavor === 'global') { return GLOBAL_LINE; }
+    if (flavor === 'npx') { return NPX_CACHED_LINE; }
+    return GENERIC_LINE;
+  } catch {
+    return GENERIC_LINE;
+  }
+}
+
+/**
+ * The full notice text: verified version pair + instruction + changelog.
+ * @param {{current: string, latest: string}} info
+ * @param {string} [instruction] - resolved lazily when omitted
+ */
+function buildUpdateNotice(info, instruction) {
+  return `Update available: amicus v${info.current} → v${info.latest}. `
+    + `${instruction || upgradeInstruction()} Changelog: ${CHANGELOG_URL}`;
+}
+
+/** Once-per-process latch (spec D1). Flips ONLY on an actual append. */
+let _noticeShown = false;
+
+/** Test seam: re-arm the latch. */
+function _resetLatchForTests() { _noticeShown = false; }
+
+/**
+ * The seam the MCP registration wrapper routes EVERY result through: append
+ * the notice block to the first successful tool result of this process, then
+ * stay quiet. No-op on isError results, unknown update state, malformed
+ * results, or any internal failure — the original result always comes back.
+ * @param {{content?: Array, isError?: boolean}|null} result
+ * @param {{getUpdateInfo?: Function}} [deps]
+ */
+function maybeAppendUpdateNotice(result, deps = {}) {
+  try {
+    if (_noticeShown) { return result; }
+    if (!result || result.isError || !Array.isArray(result.content)) { return result; }
+    const getUpdateInfo = deps.getUpdateInfo || require('./updater').getUpdateInfo;
+    const info = getUpdateInfo();
+    if (!info || !info.hasUpdate) { return result; }
+    result.content.push({ type: 'text', text: buildUpdateNotice(info) });
+    _noticeShown = true;
+    return result;
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * The amicus_guide version-line suffix (NOT latched — the guide is the
+ * on-demand surface), or null when there is nothing to say.
+ * @param {{getUpdateInfo?: Function}} [deps] - plus upgradeInstruction seams
+ * @returns {string|null}
+ */
+function guideUpdateLine(deps = {}) {
+  try {
+    const getUpdateInfo = deps.getUpdateInfo || require('./updater').getUpdateInfo;
+    const info = getUpdateInfo();
+    if (!info || !info.hasUpdate) { return null; }
+    return `**Update available: v${info.latest}** — ${upgradeInstruction(deps)}`;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  classifySelfInstall,
+  upgradeInstruction,
+  buildUpdateNotice,
+  maybeAppendUpdateNotice,
+  guideUpdateLine,
+  _resetLatchForTests,
+};

package/src/workspace/run-scan.js

@@ -70,7 +70,11 @@ function readPointer(project, runId) {
   const id = String(runId).replace(/^council-/, '');
   if (!RUN_ID_RE.test(id)) { return { runId: id, error: 'invalid runId' }; }
   const ptr = runState.readPointer(project, id);
-  if (!ptr) { return { runId: id, error: 'pointer missing, unreadable, or invalid' }; }
+  if (!ptr) {
+    return { runId: id, error: 'pointer missing — run pointers live under the LAUNCH directory '
+      + '(where `council run` was invoked), not --out-dir. If this run used --out-dir, point '
+      + '--project at the launch directory instead.' };
+  }
   return { runId: id, runDir: ptr.runDir };
 }