amicus 4.4.1 → 4.5.1

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

package/src/utils/error-doc.js

@@ -24,6 +24,11 @@ const ERROR_CODES = Object.freeze({
   COST_EXCEEDED: 'COST_EXCEEDED',   // council run: whole-run --max-cost ceiling hit pre-tally (v4.0 §4)
   // council run: --claude-review file unreadable/invalid, or --chair claude (v4.1 §4.4)
   COUNCIL_CLAUDE_REVIEW_INVALID: 'COUNCIL_CLAUDE_REVIEW_INVALID',
+  TEMPLATE_NOT_FOUND: 'TEMPLATE_NOT_FOUND', // --template name/path unresolvable at run time (v4.5 F9)
+  TEMPLATE_RENDER: 'TEMPLATE_RENDER',       // strict render rule violated: unknown var, slot/data mismatch (v4.5 F9)
+  PACK_NOT_FOUND: 'PACK_NOT_FOUND',         // --pack name not in packs dir / path unreadable (v4.5 B7/F5)
+  PACK_INVALID: 'PACK_INVALID',             // pack schema/structural/seat validation failure (v4.5 B7/F5)
+  PACK_KIND_MISMATCH: 'PACK_KIND_MISMATCH', // e.g. a council pack passed to fanout (v4.5 B7/F5)
 });
 
 /**

package/src/utils/result-schema-rebuild.js

@@ -90,6 +90,7 @@ function buildWaveResultFromSession(project, waveId) {
     waveId,
     legs,
     promptMeta: meta.promptMeta || null,
+    ...(meta.pack ? { pack: meta.pack } : {}), // v4.5 Task 13: absent-not-null, mirrors promptMeta's sourcing above.
     createdAt: meta.createdAt || null,
     completedAt: meta.completedAt || null,
   });

package/src/utils/result-schema.js

@@ -44,7 +44,9 @@ function durationBetween(createdAt, completedAt) {
  * @param {string|null} [opts.modelInput] - What the caller typed (alias), if known
  * @param {string|null} [opts.sessionDir]
  * @param {string|null} [opts.waveId] - Explicit wave id (falls back to metadata.parentWave)
- * @returns {object} run document
+ * @returns {object} run document; `pack` (v4.5 Task 13) is additive — present only when
+ *   metadata.pack was recorded (solo session launched via --pack), sourced straight off
+ *   `metadata` like `usage`/`opencodeSessionId` already are (no new function parameter needed).
  */
 function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null, usage = null }) {
   const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
@@ -68,6 +70,7 @@ function buildRunResult({ taskId, metadata = {}, result = null, summary = null,
     sessionDir,
     opencodeSessionId: metadata.opencodeSessionId || null,
     usage: usage !== null ? usage : (metadata.usage || null),
+    ...(metadata.pack ? { pack: metadata.pack } : {}),
   };
 }
 
@@ -122,9 +125,11 @@ function waveExitCode(waveStatus) {
  * @param {string|null} [opts.completedAt]
  * @param {string|null} [opts.status] - Override (e.g. 'aborted' on signal); default aggregates legs
  * @param {string[]} [opts.notices] - Advisory per-leg migration notices (#61 FIX 2); never affects status/exitCode.
+ * @param {{name: string, version: string, hash: string, source: string}|null} [opts.pack] - v4.5 Task 13:
+ *   additive — present only when the wave was launched via --pack (absent, never null, otherwise).
  * @returns {object} wave document
  */
-function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [] }) {
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null, notices = [], pack = null }) {
   const { sumWaveUsage } = require('./pricing');
   // Named buckets only (see "COUNTS REMAINDER RULE" above). 'crashed' and
   // 'idle-timeout' legs are intentionally NOT bucketed — they land in `total`
@@ -151,6 +156,7 @@ function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = nul
     durationMs,
     usage: sumWaveUsage(legs),
     notices: Array.isArray(notices) ? notices.filter(Boolean) : [],
+    ...(pack ? { pack } : {}),
   };
 }
 

package/src/workspace/artifact-guard.js

@@ -96,14 +96,37 @@ function artifactAllowlist(run) {
     }
   }
 
+  // ⚠️ Task 18 (RN-1): the collision above is a real run-integrity defect — the run directory
+  // physically holds ONE file where two models' artifacts should be, and no renderer trick can
+  // recover both. What the renderer CAN stop doing is showing model A's prose under model B's
+  // name. Deterministic disambiguation: per colliding sanitized name, sort the RAW models
+  // (sorting, not insertion order, is what keeps this reproducible across processes/runs); the
+  // first (sorted) keeps the bare sanitized name, the rest get `~2`, `~3`, ... The suffixed
+  // names deliberately do not exist on disk — the presence manifest (run-detail.js, via
+  // fs.statSync over this same allowlist) marks them absent, so the renderer shows the honest
+  // "not written yet" empty state for every model but the first, instead of cross-matching.
+  const nameFor = new Map(); // raw model -> its (possibly suffixed) sanitized name
   for (const m of uniqueModels) {
-    names.push(`review-${sanitizeName(m)}.md`);
-    names.push(`judge-${sanitizeName(m)}.md`);
-    // rebuttal-/revote- are keyed on the same BENCH ALIAS through the same sanitizeName
-    // (materializeDebate is called with `d.raiser` / the revote leg's model — both aliases).
+    let s = sanitizeName(m);
+    const collision = collisionModels.get(s);
+    if (collision) {
+      const sortedRaw = [...collision].sort();
+      const index = sortedRaw.indexOf(m);
+      if (index > 0) { s = `${s}~${index + 1}`; }
+    }
+    nameFor.set(m, s);
+  }
+
+  for (const m of uniqueModels) {
+    const s = nameFor.get(m);
+    names.push(`review-${s}.md`);
+    names.push(`judge-${s}.md`);
+    // rebuttal-/revote- are keyed on the same BENCH ALIAS through the same (now possibly
+    // suffixed) name — materializeDebate is called with `d.raiser` / the revote leg's model
+    // (both aliases), so a colliding pair's debate artifacts are disambiguated the same way.
     if (debated) {
-      names.push(`rebuttal-${sanitizeName(m)}.md`);
-      names.push(`revote-${sanitizeName(m)}.md`);
+      names.push(`rebuttal-${s}.md`);
+      names.push(`revote-${s}.md`);
     }
   }
   // `uniqueModels` already collapsed genuinely-repeated bench entries, so this final Set is
@@ -115,6 +138,21 @@ function artifactAllowlist(run) {
       sanitized, models: [...models],
     }));
   }
+  // Consumed by workspace-panels.js (wireLazyPanels' file lists + drillIntoJudge's artifact
+  // lookup), which prefers this map over re-deriving names via sanitizeName(model) directly —
+  // that re-derivation is exactly what would ignore the suffixing above and misattribute prose.
+  // ⚠️ Fix-wave (review finding 1) residual limit this map cannot close: the BARE (unsuffixed)
+  // name is still exactly ONE physical file on disk, and its actual bytes belong to whichever
+  // colliding model's writer ran LAST — no map can recover which one that was. The guarantee
+  // delivered here is narrower than "attribution is fully sound": at most the sorted-first
+  // model can still be misattributed under the bare name; artifactCollisions (the run-integrity
+  // banner rendered by workspace-app.js's renderBanners) is what covers that residual case.
+  list.artifactsByModel = Object.fromEntries(
+    [...nameFor].map(([m, s]) => [m, {
+      review: `review-${s}.md`, judge: `judge-${s}.md`,
+      rebuttal: `rebuttal-${s}.md`, revote: `revote-${s}.md`,
+    }]),
+  );
   return list;
 }
 

package/src/workspace/run-detail.js

@@ -209,6 +209,12 @@ function getRunDetail(project, runId) {
       // would otherwise silently misattribute prose. Surfaced here (rather than only inside
       // the low-level allowlist helper) so the renderer can warn the user directly.
       artifactCollisions: artifactNames.collisions || [],
+      // ⚠️ Task 18 (RN-1): the de-collision map itself (raw model -> {review, judge} filename),
+      // built once in artifactAllowlist alongside `collisions` above. `|| null` (absent, not an
+      // empty object) so workspace-panels.js can tell "no map at all" (older detail payloads —
+      // pre-v4.5 runs, live-doc consumers not yet updated) apart from a real map, and fall back
+      // to its legacy sanitizeName(model) computation only in the former case.
+      artifactsByModel: artifactNames.artifactsByModel || null,
     };
   }