amicus 4.6.0 → 4.6.1

package/src/council/run-retry.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * @module council/run-retry
+ * SL-2 (spec: docs/superpowers/specs/2026-08-03-sl2-stage1-retry-design.md):
+ * the Stage-1 once-only retry pass. A sub-wave that died before its legs
+ * existed, or a leg that ended with no usable output, is relaunched exactly
+ * once — serially, after every surviving launch settled — and the outcome is
+ * announced in the one voice: a `stage1-retry` HEAL per recovered seat; the
+ * ordinary dead-wave/dead-leg degrade, noted by the CALLER (run-stages.js),
+ * when the retry also died. This module emits heals only — it never notes a
+ * degrade and never touches `degraded.value`, so the sink invariant holds by
+ * construction. No retry of a retry: the pass consumes first-attempt losses
+ * only.
+ */
+
+const briefings = require('./briefings');
+const { materializeReviews, isAbortExit } = require('./run-launch');
+const runState = require('./run-state');
+const { waveStillDeadNote, srcLegStillDeadNote, retryLegStillDeadNote, missingLegStillDeadNote }
+  = require('./run-retry-notes');
+
+/** 1-based lens index for a loss, from the waveId convention or the model. */
+function lensIndexOf(o, waveId, model) {
+  const m = /-l(\d+)$/.exec(waveId || '');
+  if (m) { return Number(m[1]); }
+  const i = (o.models || []).indexOf(model);
+  return i === -1 ? null : i + 1;
+}
+
+/**
+ * Dedup helper (Task-4 review hardening): the same seat can arrive twice in
+ * one grouping pass — two dead legs naming it, or a dead wave and a dead leg
+ * both naming it. One seat must still mean ONE `firstFailures` entry — first
+ * occurrence wins — while every SOURCE record is kept regardless (srcWaves/
+ * srcLegs are the audit trail and are never deduped). The critic unit's
+ * `.models` is fixed at creation (there is only ever one critic seat), so
+ * only bench/lens units grow `.models` here — the critic call sites pass
+ * `trackModel: false`.
+ */
+function recordFailure(unit, seat, ff, trackModel = true) {
+  if (unit.firstFailures.some(f => f.seat === seat)) { return; }
+  unit.firstFailures.push(ff);
+  if (trackModel) { unit.models.push(seat); }
+}
+
+/**
+ * Group Stage-1 losses into retry units. Pure — no I/O.
+ * Bench losses (a dead bench wave's models + dead bench legs) collapse into
+ * ONE retry wave; the critic and each lens retry as solos (their briefings
+ * differ). Stable order: bench, critic, lenses ascending. The critic matches
+ * on EITHER carrier — waveId convention or model — mirroring
+ * verdict.js summarizeSeatLoss.
+ */
+function groupStage1Losses(o, deadWaves = [], deadLegs = []) {
+  const isCriticWave = (w) =>
+    w.waveId === `${o.runId}-c1` || (!!o.critic && (w.models || []).includes(o.critic));
+  const bench = { unit: 'bench', waveId: `${o.runId}-s1r1`, retryOfWaveId: `${o.runId}-s1`,
+    models: [], firstFailures: [], srcWaves: [], srcLegs: [] };
+  const lensUnits = new Map(); // lensIndex (number, or null for unmappable) -> unit
+  const criticUnit = { unit: 'critic', waveId: `${o.runId}-c1r1`, retryOfWaveId: `${o.runId}-c1`,
+    models: o.critic ? [o.critic] : [], firstFailures: [], srcWaves: [], srcLegs: [] };
+
+  const lensUnitFor = (i) => {
+    if (!lensUnits.has(i)) {
+      // Task-4 review hardening: an unmappable loss (lensIndexOf resolved
+      // neither the waveId convention nor a model-roster membership) must
+      // still be GROUPABLE — dropping it here would let it vanish before the
+      // orchestrator ever sees it — but must not manufacture a fake
+      // `-lnullr1` waveId. The orchestrator refuses to launch any unit with
+      // `lensIndex === null` and routes its sources to skipped instead.
+      lensUnits.set(i, i === null
+        ? { unit: 'lens', lensIndex: null, waveId: null, retryOfWaveId: null,
+          models: [], firstFailures: [], srcWaves: [], srcLegs: [] }
+        : { unit: 'lens', lensIndex: i, waveId: `${o.runId}-l${i}r1`,
+          retryOfWaveId: `${o.runId}-l${i}`, models: [], firstFailures: [], srcWaves: [], srcLegs: [] });
+    }
+    return lensUnits.get(i);
+  };
+
+  for (const w of deadWaves) {
+    const models = w.models || [];
+    if (o.lenses) {
+      const u = lensUnitFor(lensIndexOf(o, w.waveId, models[0]));
+      u.srcWaves.push(w);
+      models.forEach(seat => recordFailure(u, seat, { seat, class: 'wave', waveId: w.waveId, reason: w.reason }));
+    } else if (isCriticWave(w)) {
+      criticUnit.srcWaves.push(w);
+      recordFailure(criticUnit, o.critic,
+        { seat: o.critic, class: 'wave', waveId: w.waveId, reason: w.reason }, false);
+    } else {
+      bench.srcWaves.push(w);
+      models.forEach(seat => recordFailure(bench, seat, { seat, class: 'wave', waveId: w.waveId, reason: w.reason }));
+    }
+  }
+  for (const leg of deadLegs) {
+    const seat = leg.modelInput || leg.model;
+    const ff = { seat, class: 'leg', status: leg.status, reason: leg.error || null };
+    if (o.lenses) {
+      const u = lensUnitFor(lensIndexOf(o, null, seat));
+      u.srcLegs.push(leg);
+      recordFailure(u, seat, ff);
+    } else if (o.critic && seat === o.critic) {
+      criticUnit.srcLegs.push(leg);
+      recordFailure(criticUnit, seat, ff, false);
+    } else {
+      bench.srcLegs.push(leg);
+      recordFailure(bench, seat, ff);
+    }
+  }
+
+  const out = [];
+  // Task-4 review hardening: gate on whether the unit received any SOURCE
+  // record, not on firstFailures.length — a zero-model dead wave contributes
+  // a srcWaves entry but nothing to firstFailures/models (nothing for the
+  // `.forEach` above to iterate), and must still surface here so the
+  // orchestrator can route it to skipped instead of it vanishing silently.
+  if (bench.srcWaves.length > 0 || bench.srcLegs.length > 0) { out.push(bench); }
+  if (criticUnit.srcWaves.length > 0 || criticUnit.srcLegs.length > 0) { out.push(criticUnit); }
+  // Coordinator-review MINOR-7a: null sorts LAST (Infinity), not first (0) —
+  // an unmappable loss is not "lens index 0"; it should not perturb the
+  // ascending order of the real, well-indexed lens retries.
+  out.push(...[...lensUnits.values()].sort((a, b) => (a.lensIndex ?? Infinity) - (b.lensIndex ?? Infinity)));
+  return out;
+}
+
+/** The briefing a retry unit re-issues — same builders Stage 1 used. */
+function briefingFor(o, unit) {
+  if (unit.unit === 'critic') { return briefings.buildCriticBriefing({ briefing: o.briefing, date: o.date }); }
+  if (unit.unit === 'lens') {
+    return briefings.buildLensBriefing({ lens: o.lenses[unit.lensIndex - 1], briefing: o.briefing, date: o.date });
+  }
+  return briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date });
+}
+
+/**
+ * The retry pass. Serial by design (spec D-order: bench, critic, lenses) —
+ * the per-wave-fallback path, where waves actually die, is exactly where
+ * concurrent relaunches would race the same server start again.
+ */
+async function retryStage1Losses(ctx, { deadWaves = [], deadLegs = [], counts = { reviewed: 0, total: 0 } } = {}) {
+  const { o, launchers } = ctx;
+  const out = { aborted: null, recoveredLegs: [], stillDeadNotes: [],
+    stillDeadWaves: [], stillDeadLegs: [], skippedDeadWaves: [], skippedDeadLegs: [] };
+
+  for (const unit of groupStage1Losses(o, deadWaves, deadLegs)) {
+    // Task-4 review hardening: a unit this pass cannot even ATTEMPT — an
+    // unmappable lens loss (no carrier resolved an index), a lens index
+    // outside the run's actual lens roster (coordinator-review MINOR-7b: a
+    // malformed waveId like "...-l99" must not become an out-of-range
+    // `o.lenses[98]` access inside briefingFor), or a unit whose sources
+    // named zero models — is never launched. Its sources fall back to the
+    // ordinary skipped-loss path so the caller's normal degrade notes still
+    // fire; being unmappable is not an exemption from the record.
+    const lensOutOfRange = unit.unit === 'lens' && unit.lensIndex !== null
+      && (unit.lensIndex < 1 || unit.lensIndex > (o.lenses || []).length);
+    if (unit.lensIndex === null || lensOutOfRange || unit.models.length === 0) {
+      out.skippedDeadWaves.push(...unit.srcWaves);
+      out.skippedDeadLegs.push(...unit.srcLegs);
+      continue;
+    }
+    if (ctx.overBudget()) { // D7: skip silently — the loss is already announced by the caller
+      out.skippedDeadWaves.push(...unit.srcWaves);
+      out.skippedDeadLegs.push(...unit.srcLegs);
+      continue;
+    }
+    runState.appendStageWave(o.runDir, 'stage1', unit.waveId); // BEFORE launch: abort cascade
+    const common = { project: o.runDir, timeout: o.timeout, gateway: o.gateway,
+      noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+      councilRunId: o.runId, councilName: o.councilName,
+      fallback: o.fallback, catalog: o.catalog,
+      waveId: unit.waveId, retryOfWaveId: unit.retryOfWaveId, prompt: briefingFor(o, unit) };
+    // Dispatch by UNIT TYPE, not model count (spec §4: bench is always a wave —
+    // even down to its last surviving seat — critic/lens are always solos).
+    // A model-count proxy (`models.length === 1`) is wrong for a bench unit
+    // that lost exactly one seat: it would route that retry through
+    // launchSolo, which no bench caller wires up.
+    const res = unit.unit === 'bench'
+      ? await launchers.launchWave({ ...common, models: unit.models.slice() })
+      : await launchers.launchSolo({ ...common, model: unit.models[0] });
+    ctx.addWave(res.wave); // reservation released + measured legs counted (run-budget)
+    if (isAbortExit(res.exitCode)) { out.aborted = res.exitCode; return out; }
+
+    const legs = (res.wave && Array.isArray(res.wave.legs)) ? res.wave.legs : [];
+    if (legs.length === 0) {
+      // The retry wave itself died wholesale — final failure keeps each
+      // source's granularity (D5): wave-origin stays a dead-wave, leg-origin
+      // stays a dead-leg, both enriched with the retry fact. Coordinator-
+      // review MINOR-4: emitted ONCE per SEAT — the grouping dedup (Task-4
+      // hardening) keeps BOTH src records when a seat arrives via a srcWave
+      // AND a srcLeg (or via two srcLegs), so without this a single lost
+      // seat could be announced twice. Waves are processed first (mirrors
+      // the "wave wins" precedent from the grouping-level dedup); a seat
+      // already covered by its wave's note is skipped when its srcLeg is
+      // reached.
+      const notedSeats = new Set();
+      for (const w of unit.srcWaves) {
+        out.stillDeadNotes.push(waveStillDeadNote(w, unit));
+        out.stillDeadWaves.push(w);
+        for (const m of (w.models || [])) { notedSeats.add(m); }
+      }
+      for (const l of unit.srcLegs) {
+        const seat = l.modelInput || l.model;
+        if (notedSeats.has(seat)) { continue; }
+        notedSeats.add(seat);
+        out.stillDeadNotes.push(srcLegStillDeadNote(l, unit, counts));
+        out.stillDeadLegs.push(l);
+      }
+      continue;
+    }
+    const usable = new Set(materializeReviews(o.runDir, legs).map(m => m.leg));
+    const seenSeats = new Set(legs.map(leg => leg.modelInput || leg.model));
+    const lostWaveSeats = new Map(); // waveId -> seats still lost from a wave-origin
+    for (const leg of legs) {
+      const seat = leg.modelInput || leg.model;
+      const ff = unit.firstFailures.find(f => f.seat === seat) || null;
+      // SL-2 fix-wave: a retry response should only ever name seats THIS unit
+      // launched for (unit.models is built in lockstep with firstFailures via
+      // groupStage1Losses's recordFailure) — but if a leg turns up for a seat
+      // with no firstFailures entry, that seat never lost its seat in the
+      // first place. Skip it entirely: no heal (it would fabricate an "ended
+      // 'unknown'" why for a seat that never failed) and no still-dead note —
+      // the seat's first-attempt review stands untouched, rather than this
+      // stray leg doubling it into a duplicate bench entry alongside the real one.
+      if (!ff) { continue; }
+      if (usable.has(leg)) {
+        out.recoveredLegs.push(leg);
+        ctx.degrade.note({ channel: 'stage1-retry', kind: 'heal',
+          what: `seat ${seat} reviewed on retry`,
+          why: ff && ff.class === 'wave'
+            ? `its first wave ${ff.waveId} produced no legs (${ff.reason}) and was relaunched once`
+            : `its first leg ended '${ff ? ff.status : 'unknown'}' with no usable output and was relaunched once`,
+          effect: 'The seat is in this council; nothing was lost',
+          data: { seat, retryWaveId: unit.waveId, retryOfWaveId: unit.retryOfWaveId, firstFailure: ff } });
+      } else {
+        out.stillDeadNotes.push(retryLegStillDeadNote(seat, ff, leg, unit, counts));
+        if (ff && ff.class === 'wave') {
+          if (!lostWaveSeats.has(ff.waveId)) { lostWaveSeats.set(ff.waveId, []); }
+          lostWaveSeats.get(ff.waveId).push(seat);
+        } else {
+          const src = unit.srcLegs.find(l => (l.modelInput || l.model) === seat);
+          if (src) { out.stillDeadLegs.push(src); }
+        }
+      }
+    }
+    // CRITICAL fix (coordinator review): the loop above only visits seats
+    // that came back WITH a leg record. A partial wave return (unit models
+    // [a,b], the wave comes back with only a's leg) leaves 'b' invisible to
+    // that loop entirely — no heal, no still-dead note, no skip: it would
+    // vanish from every array. Reconcile against the full launched-seat set
+    // (the union of unit.models, every srcWave's models, and every srcLeg's
+    // seat — not just unit.models alone, so this holds even if some future
+    // change to the grouping made unit.models an incomplete union) so every
+    // launched seat lands in exactly one of recovered / still-dead / skipped.
+    const launchedSeats = new Set(unit.models);
+    for (const w of unit.srcWaves) { for (const m of (w.models || [])) { launchedSeats.add(m); } }
+    for (const l of unit.srcLegs) { launchedSeats.add(l.modelInput || l.model); }
+    for (const seat of launchedSeats) {
+      if (seenSeats.has(seat)) { continue; } // already handled above (healed or still-dead)
+      const ff = unit.firstFailures.find(f => f.seat === seat) || null;
+      out.stillDeadNotes.push(missingLegStillDeadNote(seat, ff, unit, counts));
+      if (ff && ff.class === 'wave') {
+        if (!lostWaveSeats.has(ff.waveId)) { lostWaveSeats.set(ff.waveId, []); }
+        lostWaveSeats.get(ff.waveId).push(seat);
+      } else {
+        const src = unit.srcLegs.find(l => (l.modelInput || l.model) === seat);
+        if (src) { out.stillDeadLegs.push(src); }
+      }
+    }
+    // Wave-origin seats still lost: the return-contract wave entry carries only
+    // the still-lost subset (a partially healed wave is not wholly dead).
+    for (const w of unit.srcWaves) {
+      const lost = lostWaveSeats.get(w.waveId) || [];
+      if (lost.length > 0) { out.stillDeadWaves.push({ ...w, models: lost }); }
+    }
+  }
+  return out;
+}
+
+module.exports = { groupStage1Losses, retryStage1Losses };

package/src/council/run-stages.js

@@ -20,6 +20,7 @@
 const { validateFindings, countAttemptedFindings } = require('./findings');
 const briefings = require('./briefings');
 const { materializeReviews, isAbortExit } = require('./run-launch');
+const { retryStage1Losses } = require('./run-retry');
 const runState = require('./run-state');
 const { runStage2 } = require('./run-stage2');
 
@@ -133,7 +134,25 @@ async function runStage1(ctx) {
   const { aborted, legs, deadWaves } = await launchStage1(ctx);
   if (aborted) { return { aborted, reviews: [], deadLegs: [], deadWaves: [], degraded: false }; }
 
-  for (const d of deadWaves) {
+  const firstPass = materializeReviews(o.runDir, legs);
+  const alive0 = new Set(firstPass.map(m => m.leg));
+  const deadLegs0 = legs.filter(l => !alive0.has(l));
+
+  // SL-2: one retry BEFORE anything is recorded lost — the sink never
+  // un-flips, so a degrade for a seat the retry saves must never fire at all.
+  const retry = await retryStage1Losses(ctx, { deadWaves, deadLegs: deadLegs0,
+    counts: { reviewed: firstPass.length, total: legs.length } });
+  if (retry.aborted) {
+    // Final whole-branch review: same bug class as the post-retry-repair
+    // abort fixed ~87 lines below ("Must be the post-retry set") — subtract
+    // whatever retry.recoveredLegs already healed before this abort landed.
+    const healed = new Set(retry.recoveredLegs.map(l => l.modelInput || l.model));
+    return { aborted: retry.aborted, reviews: [], degraded: false,
+      deadLegs: deadLegs0.filter(l => !healed.has(l.modelInput || l.model)),
+      deadWaves: deadWaves.map(w => ({ ...w, models: (w.models || []).filter(m => !healed.has(m)) })).filter(w => w.models.length > 0) };
+  }
+
+  for (const d of retry.skippedDeadWaves) {
     ctx.degrade.note({
       channel: 'dead-wave',
       what: `Stage-1 wave ${d.waveId} (${d.models.join(', ') || 'no models'}) produced NO legs`,
@@ -143,21 +162,27 @@ async function runStage1(ctx) {
       data: { waveId: d.waveId, models: d.models, reason: d.reason },
     });
   }
-
-  const materialized = materializeReviews(o.runDir, legs);
-  const alive = new Set(materialized.map(m => m.leg));
-  const deadLegs = legs.filter(l => !alive.has(l));
-
-  for (const leg of deadLegs) {
+  for (const leg of retry.skippedDeadLegs) {
     ctx.degrade.note({
       channel: 'dead-leg',
       what: `seat ${leg.modelInput || leg.model} did not review`,
       why: `the leg ended '${leg.status}'${leg.error ? `: ${leg.error}` : ''} with no usable output`,
-      effect: `${materialized.length} of ${legs.length} seats reviewed; `
+      effect: `${firstPass.length} of ${legs.length} seats reviewed; `
         + 'the run continues with the bench that did and will exit degraded (2)',
       data: { seat: leg.modelInput || leg.model, status: leg.status, reason: leg.error || null },
     });
   }
+  for (const rec of retry.stillDeadNotes) { ctx.degrade.note(rec); }
+
+  // Invariant this merge relies on: retry.recoveredLegs only ever names seats
+  // that actually lost their seat on the first pass (run-retry.js's recovery
+  // loop drops any leg for a seat with no firstFailures entry) — so `legs`
+  // and `recoveredLegs` can never both carry a leg for the same seat here.
+  // materializeReviews re-writing an already-materialized recovered leg's
+  // review-*.md a second time is accepted as an idempotent no-op, not a bug.
+  const materialized = materializeReviews(o.runDir, [...legs, ...retry.recoveredLegs]);
+  const stillDeadLegs = [...retry.skippedDeadLegs, ...retry.stillDeadLegs];
+  const stillDeadWaves = [...retry.skippedDeadWaves, ...retry.stillDeadWaves];
 
   const reviews = [];
   let repairSeq = 0;
@@ -206,7 +231,12 @@ async function runStage1(ctx) {
       });
       ctx.addWave(solo.wave);
       if (isAbortExit(solo.exitCode)) {
-        return { aborted: solo.exitCode, reviews, deadLegs, deadWaves, degraded: false };
+        // SL-2 fix-wave: this used to read the pre-retry `deadWaves` binding —
+        // run.js persists this return into stage-1 state before the abort
+        // short-circuit, so a heal-then-abort run was recording seats as dead
+        // that had actually reviewed on retry. Must be the post-retry set,
+        // same as the normal-completion return below.
+        return { aborted: solo.exitCode, reviews, deadLegs: stillDeadLegs, deadWaves: stillDeadWaves, degraded: false };
       }
       const repaired = (solo.leg && solo.leg.summary) || '';
       if (repaired.trim()) { repairing = repaired; }
@@ -255,8 +285,8 @@ async function runStage1(ctx) {
       ...(repairRefused ? { repairRefused } : {}),
     });
   }
-  return { aborted: null, reviews, deadLegs, deadWaves,
-    degraded: deadLegs.length > 0 || deadWaves.length > 0 };
+  return { aborted: null, reviews, deadLegs: stillDeadLegs, deadWaves: stillDeadWaves,
+    degraded: stillDeadLegs.length > 0 || stillDeadWaves.length > 0 };
 }
 
 // runStage2 lives in ./run-stage2.js (300-line gate) but is re-exported here so

package/src/council/verdict.js

@@ -73,8 +73,15 @@ function deriveSeatLoss({ runId, critic, degrades = [] } = {}) {
   return {
     ...base,
     criticSeated: base.criticSeated && !criticLeg,
+    // SL-2 handoff: a reconciliation note (run-retry-notes.js's
+    // missingLegStillDeadNote) carries data.status: null when the retry
+    // produced no leg for the seat at all — there is no status to name, so
+    // the old `ended '${status}'` template rendered the literal string
+    // "ended 'null'". A status-carrying record keeps the original text.
     reason: base.reason || (criticLeg
-      ? (criticLeg.data.reason || `the critic leg ended '${criticLeg.data.status}' with no usable output`)
+      ? (criticLeg.data.reason || (criticLeg.data.status
+        ? `the critic leg ended '${criticLeg.data.status}' with no usable output`
+        : 'the critic leg produced no usable output'))
       : null),
     deadBenchSeats: [...base.deadBenchSeats,
       ...legs.filter(l => l.data.seat !== critic).map(l => l.data.seat)],

package/src/mcp-server.js

@@ -1459,6 +1459,21 @@ async function startMcpServer() {
     { capabilities: { roots: {} } }
   );
 
+  // MCP update notice (spec 2026-08-03): the MCP server replaces the CLI's
+  // deliberately-skipped pre-command update check. Fire-and-forget — startup
+  // is never delayed; when the async init resolves with an update known, one
+  // stderr line lands in the client's MCP log. The per-result notice itself
+  // is appended by maybeAppendUpdateNotice in the registration wrapper below.
+  const { initUpdateCheck, getUpdateInfo } = require('./utils/updater');
+  const { maybeAppendUpdateNotice } = require('./utils/update-notice');
+  initUpdateCheck().then(() => {
+    const updateInfo = getUpdateInfo();
+    if (updateInfo && updateInfo.hasUpdate) {
+      process.stderr.write(
+        `[amicus] update available: v${updateInfo.current} -> v${updateInfo.latest}\n`);
+    }
+  }).catch(() => { /* advisory only */ });
+
   for (const tool of getTools()) {
     const register = (name) => server.registerTool(
       name,
@@ -1466,11 +1481,11 @@ async function startMcpServer() {
       async (input) => {
         try {
           const project = await resolveProjectDir(input.project, server);
-          return await handlers[tool.name](input, project, server);
+          return maybeAppendUpdateNotice(await handlers[tool.name](input, project, server));
         }
         catch (err) {
           logger.error(`MCP tool error: ${name}`, { error: err.message });
-          return textResult(`Error: ${err.message}`, true);
+          return maybeAppendUpdateNotice(textResult(`Error: ${err.message}`, true));
         }
       }
     );

package/src/mcp-tools.js

@@ -574,9 +574,13 @@ function getGuideText() {
     .map(([name, model]) => `| ${name} | ${model} |`)
     .join('\n');
   // #33: surface the running version (and a call-time staleness warning) so a
-  // post-upgrade agent session can tell it's running old code.
+  // post-upgrade agent session can tell it's running old code. Spec 2026-08-03
+  // adds the registry-side sibling: a newer release exists (not latched here —
+  // the guide is the on-demand surface).
   const warn = versionWarning();
+  const updateLine = require('./utils/update-notice').guideUpdateLine();
   const versionLine = `**Running amicus version:** ${RUNNING_VERSION}`
+    + (updateLine ? `\n\n> ${updateLine}` : '')
     + (warn ? `\n\n> ⚠️ ${warn}` : '');
 
   return `# Amicus Usage Guide

package/src/utils/degrade.js

@@ -16,6 +16,7 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   'dead-leg', 'dead-wave', 'budget-refusal', 'shared-server-unavailable',
   'dropped-members', 'chair-skipped-cost-ceiling', 'chair-failed',
   'thin-cross-review', 'debate-degraded', 'inexact-under-ceiling',
+  'stage1-retry',
   'internal',
   // doctor channels
   'doctor-check-failed', 'doctor-fix',

package/src/utils/remediation-hints.js

@@ -49,21 +49,19 @@ const REMEDIATION_HINTS = Object.freeze({
   /** 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)',
 
@@ -80,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/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,
+};