amicus 4.6.0 → 4.6.2

package/src/utils/base-url-classify.js

@@ -0,0 +1,74 @@
+/**
+ * @module base-url-classify
+ * v4.6.2 PR1 (spec §4, D1/D2): ANTHROPIC_BASE_URL classification, the
+ * normalization decision, and the once-per-process notice.
+ *
+ * The convention split (field-proven by a control pair on run 0084d48c):
+ * Anthropic SDKs — including Claude Code itself — treat the var as a HOST and
+ * append /v1 themselves; OpenCode's provider layer treats it as the FULL
+ * prefix and appends /messages. A host-form value is therefore correct for
+ * Claude Code and fatal for every OpenCode direct-anthropic leg
+ * (host/messages -> 404 "Not Found").
+ *
+ * Forms: absent (unset/blank) · host (path '' or '/') · v1 (path ends /v1)
+ * · other (any other path, or unparseable — passed through untouched; an
+ * exotic proxy serving /messages at a custom root stays possible, D1).
+ */
+'use strict';
+
+/** @param {string|undefined|null} value @returns {{form:string, normalized:string|null}} */
+function classifyBaseUrl(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return { form: 'absent', normalized: null };
+  }
+  const trimmed = value.trim();
+  let url;
+  try { url = new URL(trimmed); } catch { return { form: 'other', normalized: null }; }
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path === '') {
+    return { form: 'host', normalized: trimmed.replace(/\/+$/, '') + '/v1' };
+  }
+  if (path.endsWith('/v1')) { return { form: 'v1', normalized: null }; }
+  return { form: 'other', normalized: null };
+}
+
+/**
+ * The baseURL override the OpenCode server config should carry, or null.
+ * Null when: var absent, already /v1, nonstandard path, or normalization
+ * disabled via AMICUS_BASE_URL_NORMALIZE=0 (D1's escape hatch).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+function resolveBaseUrlOverride(env = process.env) {
+  if (env.AMICUS_BASE_URL_NORMALIZE === '0') { return null; }
+  const { form, normalized } = classifyBaseUrl(env.ANTHROPIC_BASE_URL);
+  return form === 'host' ? normalized : null;
+}
+
+let noticeShown = false;
+
+/**
+ * One notice per process (D2): the server may start many times (shared-server
+ * retries, fanout waves) and the treatment is identical every time.
+ * @param {string} value - the raw env value seen
+ * @param {string} normalized - the value handed to the engine config
+ * @param {{write?:Function, logger?:object}} [deps] - test seams
+ */
+function announceBaseUrlNormalizationOnce(value, normalized, deps = {}) {
+  if (noticeShown) { return; }
+  noticeShown = true;
+  const write = deps.write || (s => process.stderr.write(s));
+  const log = deps.logger || require('./logger').logger;
+  write(`Notice: ANTHROPIC_BASE_URL is host-form (${value}); passing ${normalized} to the engine `
+    + '(Anthropic SDKs append /v1 themselves; OpenCode treats the value as a full prefix; '
+    + 'set AMICUS_BASE_URL_NORMALIZE=0 to disable).\n');
+  log.info('ANTHROPIC_BASE_URL normalized for engine config', { value, normalized });
+}
+
+/** Test seam: reset the once-guard. */
+function _resetBaseUrlNotice() { noticeShown = false; }
+
+module.exports = {
+  classifyBaseUrl, resolveBaseUrlOverride,
+  announceBaseUrlNormalizationOnce, _resetBaseUrlNotice,
+};

package/src/utils/council-presets.js

@@ -42,13 +42,17 @@ const BUDGET_ALIASES = ['minimax', 'qwen-coder', 'deepseek'];
 /**
  * Frontier bench: three premium-flagship DEFAULT_ALIASES entries, one per
  * vendor family, verified against the same catalog snapshot:
- *   gpt-pro     openrouter/openai/gpt-5.5-pro          $0.00003 / $0.00018
- *   opus        openrouter/anthropic/claude-opus-4.8   $0.000005 / $0.000025
+ *   gpt-pro     openrouter/openai/gpt-5.6-sol-pro      $0.000005 / $0.00003
+ *   opus        openrouter/anthropic/claude-opus-5     $0.000005 / $0.000025
  *   gemini-pro  openrouter/google/gemini-3.1-pro-preview  $0.000002 / $0.000012
  * These are the three highest total (prompt+completion) prices in
  * DEFAULT_ALIASES that are also each a distinct vendor family (OpenAI /
  * Anthropic / Google) — `gpt` and `codex` (also OpenAI) and `claude`/`sonnet`
  * (also Anthropic) were skipped as same-family duplicates of the pick above.
+ * (opus re-pinned to claude-opus-5 on 2026-08-04 at the same live price;
+ * gpt-pro retargeted to gpt-5.6-sol-pro on 2026-08-04 — cheaper than the
+ * old gpt-5.5-pro pin but still OpenAI's premium tier, so the selection
+ * logic above is unchanged.)
  */
 const FRONTIER_ALIASES = ['gpt-pro', 'opus', 'gemini-pro'];
 

package/src/utils/curated-models.js

@@ -21,9 +21,11 @@ const { isDirectProvider } = require('./provider-registry');
  * resolve live from the catalog. A per-provider `fallback` entry is
  * OPTIONAL: when absent and the catalog cannot resolve that namespace,
  * the direct route is omitted (no pinned guess is better than a wrong one).
- * `gpt`'s pattern intentionally matches any plain numeric flagship id
- * (gpt-5.5, gpt-6) and excludes suffixed variants (-pro/-mini/-codex).
- * Pinned ids verified against the live catalog 2026-06-24.
+ * `gpt`'s pattern intentionally matches a plain numeric flagship id
+ * (gpt-5.5, gpt-6) OR that id's `-terra` tier variant (gpt-5.6-terra), and
+ * excludes every other suffixed variant (-pro/-mini/-codex/-sol/-luna) —
+ * see the tier-semantics comment on the entry below.
+ * Pinned ids verified against the live catalog 2026-08-04.
  */
 const FAMILIES = [
   { alias: 'gemini', label: 'Gemini Flash-class', blurb: 'fast, large context',
@@ -37,17 +39,26 @@ const FAMILIES = [
     idPattern: /^gemini-[\d.]+-pro(-preview|-exp|-latest)?$/,
     directProviders: ['google'],
     fallback: { openrouter: 'openrouter/google/gemini-3.1-pro-preview' } },
+  // 5.6 split the flagship into tiers: sol (premium, $5/$30), terra (mid,
+  // $1/$6), luna (economy, $0.10/$0.60), each with a -pro sibling, plus the
+  // unrelated gpt-5.3-codex family. Owner ruling: `gpt` tracks the TERRA
+  // (mid) tier — sol/luna/pro variants and codex are excluded deliberately.
+  // Bare numeric ids (gpt-5.5-style) stay matched as a within-family
+  // fallback if the terra naming ever disappears from the catalog.
   { alias: 'gpt', label: 'GPT flagship', blurb: 'strong coding',
     vendorPath: 'openai',
-    idPattern: /^gpt-[\d.]+$/,
+    idPattern: /^gpt-[\d.]+(-terra)?$/,
     directProviders: ['openai'],
-    fallback: { openrouter: 'openrouter/openai/gpt-5.5' } },
+    fallback: { openrouter: 'openrouter/openai/gpt-5.6-terra' } },
   { alias: 'opus', label: 'Claude Opus-class', blurb: 'deep analysis',
     vendorPath: 'anthropic',
     idPattern: /^claude-opus-[\d.-]+$/,
     directProviders: ['anthropic'],
-    fallback: { openrouter: 'openrouter/anthropic/claude-opus-4.8',
-                anthropic: 'anthropic/claude-opus-4-8' } },
+    // claude-opus-5 has no dotted version segment, so the two forms coincide —
+    // the anthropic: route is still AUTHORED (DIVERGENT_VENDORS), never derived.
+    // Direct id verified against Anthropic docs 2026-08-04.
+    fallback: { openrouter: 'openrouter/anthropic/claude-opus-5',
+                anthropic: 'anthropic/claude-opus-5' } },
   { alias: 'deepseek', label: 'DeepSeek flagship', blurb: 'open-source',
     vendorPath: 'deepseek',
     idPattern: /^deepseek-v[\d.]+(-pro)?$/,
@@ -58,10 +69,15 @@ const FAMILIES = [
 
 /**
  * Alias-only entries (no wizard quick pick); openrouter route only.
- * Refreshed against the live catalog 2026-06-11.
+ * Refreshed against the live catalog 2026-08-04.
  */
 const CARDLESS = [
-  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.5-pro' } },
+  // gpt-pro: the 5.6 premium (sol) tier's pro sibling, priced at its base
+  // tier ($5/$30 per Mtok). Owner ruling 2026-08-04: retargeted off
+  // gpt-5.5-pro ($30/$180 — still served, but expected to sunset with the
+  // 5.5 line). `gpt-pro` tracks SOL while the `gpt` family tracks terra —
+  // see the tier-semantics comment on the `gpt` family above.
+  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.6-sol-pro' } },
   // codex: newest codex-specific model on OpenRouter (verified 2026-06-09).
   { alias: 'codex', routes: { openrouter: 'openrouter/openai/gpt-5.3-codex' } },
   { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-5',
@@ -75,7 +91,10 @@ const CARDLESS = [
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
   { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-medium-3-5' } },
-  { alias: 'devstral', routes: { openrouter: 'openrouter/mistralai/devstral-2512' } },
+  // devstral was dropped 2026-08-04 (owner ruling): OpenRouter delisted the
+  // whole devstral family and the alias had no other route. No retarget — no
+  // served model is a devstral successor ("no pinned guess is better than a
+  // wrong one"); `mistral` remains the vendor's alias.
   { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5.1' } },
   { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.7' } },
   { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },

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/doctor-base-url-check.js

@@ -0,0 +1,41 @@
+/**
+ * @module doctor-base-url-check
+ * v4.6.2 PR1 (spec §4): the 'anthropic-base-url' doctor row.
+ *
+ * VERIFIABLE voice (BACKLOG ruling): states only what it string-inspected.
+ * It always prints the value the process SEES — the var can live ONLY in a
+ * parent process env (the field case: set in the Claude Code app process,
+ * absent from every persisted scope on disk), so the seen value IS the
+ * diagnostic; "where it is set" may be unfindable.
+ */
+'use strict';
+
+const { classifyBaseUrl } = require('./base-url-classify');
+
+/** @param {{env?:NodeJS.ProcessEnv}} [d] @returns {{id,name,status,message,hint}} */
+function evaluateAnthropicBaseUrl(d = {}) {
+  const id = 'anthropic-base-url'; const name = 'ANTHROPIC_BASE_URL';
+  const env = d.env || process.env;
+  const value = env.ANTHROPIC_BASE_URL;
+  const { form, normalized } = classifyBaseUrl(value);
+  if (form === 'absent') {
+    return { id, name, status: 'ok', message: 'not set', hint: null };
+  }
+  if (form === 'v1') {
+    return { id, name, status: 'ok', message: `${value} (full-prefix form)`, hint: null };
+  }
+  if (form === 'host') {
+    const disabled = env.AMICUS_BASE_URL_NORMALIZE === '0';
+    const treatment = disabled
+      ? 'normalization is disabled (AMICUS_BASE_URL_NORMALIZE=0) — direct-anthropic legs will 404'
+      : `amicus passes ${normalized} to the engine`;
+    return {
+      id, name, status: 'warn',
+      message: `host-form: ${value} — Anthropic SDKs append /v1; OpenCode treats it as the full prefix; ${treatment}`,
+      hint: disabled ? `set ANTHROPIC_BASE_URL=${normalized} (or unset AMICUS_BASE_URL_NORMALIZE)` : null,
+    };
+  }
+  return { id, name, status: 'ok', message: `${value} (nonstandard path — passed through unchanged)`, hint: null };
+}
+
+module.exports = { evaluateAnthropicBaseUrl };

package/src/utils/model-fetcher.js

@@ -16,6 +16,7 @@ const https = require('https');
  * would mislabel a direct-API request for it as valid.
  */
 const ANTHROPIC_MODELS = [
+  { id: 'anthropic/claude-opus-5', name: 'Claude Opus 5', contextLength: null, pricing: null },
   { id: 'anthropic/claude-opus-4-8', name: 'Claude Opus 4.8', contextLength: null, pricing: null },
   { id: 'anthropic/claude-sonnet-5', name: 'Claude Sonnet 5', contextLength: null, pricing: null },
   { id: 'anthropic/claude-haiku-4-5', name: 'Claude Haiku 4.5', contextLength: null, pricing: null },

package/src/utils/model-tiers.js

@@ -28,7 +28,13 @@ const { pickCurrent } = require('./quick-picks');
 const { isDirectProvider } = require('./provider-registry');
 const { toDefaultAliases, listCuratedRoutes } = require('./curated-models');
 
-/** Tier regex table: pattern matches the model segment after `<vendor>/` (or `openrouter/<vendor>/`). */
+/**
+ * Tier pattern table: each tier holds a regex — or an ORDERED regex list,
+ * tried first-match-wins — over the model segment after `<vendor>/` (or
+ * `openrouter/<vendor>/`). List order expresses preference, which a single
+ * regex cannot: ids sort numeric-descending, so `-pro` siblings would
+ * otherwise outrank their same-priced base.
+ */
 const TIERS = {
   anthropic: {
     economy: /^claude-haiku-/,
@@ -36,9 +42,17 @@ const TIERS = {
     frontier: /^claude-opus-/,
   },
   openai: {
-    economy: /^gpt-[\d.]+-mini$/,
-    balanced: /^gpt-[\d.]+$/,
-    frontier: /^gpt-[\d.]+-pro$/,
+    // The 5.6 line renamed the flagship into tiers — luna ($0.10/$0.60 per
+    // Mtok in/out), terra ($1/$6), sol ($5/$30), each with a -pro sibling
+    // priced at its base tier; no bare/-mini/-pro 5.6 ids exist. Owner
+    // ruling 2026-08-04: economy→luna, balanced→terra, frontier→sol, each
+    // preferring the base name, then its -pro sibling, then the 5.5-era
+    // naming so a stale catalog still resolves. balanced's primary is the
+    // same bare-or-terra pattern the `gpt` family uses (curated-models.js),
+    // so a future return to bare flagship ids is tracked automatically.
+    economy: [/^gpt-[\d.]+-luna$/, /^gpt-[\d.]+-luna-pro$/, /^gpt-[\d.]+-mini$/],
+    balanced: [/^gpt-[\d.]+(-terra)?$/, /^gpt-[\d.]+-terra-pro$/],
+    frontier: [/^gpt-[\d.]+-sol$/, /^gpt-[\d.]+-sol-pro$/, /^gpt-[\d.]+-pro$/],
   },
   google: {
     economy: /^gemini-[\d.]+-flash-lite/,
@@ -77,9 +91,16 @@ function buildGatewayOnlyAliasMap() {
 
 const GATEWAY_ONLY_ALIAS = buildGatewayOnlyAliasMap();
 
-/** Newest catalog id matching `regex` under `vendor`; direct namespace preferred over OpenRouter's. */
-function pickForTier(catalog, vendor, regex) {
-  return pickCurrent(catalog, '', vendor, regex) || pickCurrent(catalog, 'openrouter/', vendor, regex);
+/**
+ * First match wins over a tier's ordered patterns; within each pattern the
+ * newest matching id is picked, direct namespace preferred over OpenRouter's.
+ */
+function pickForTier(catalog, vendor, patterns) {
+  for (const regex of [].concat(patterns)) {
+    const pick = pickCurrent(catalog, '', vendor, regex) || pickCurrent(catalog, 'openrouter/', vendor, regex);
+    if (pick) { return pick; }
+  }
+  return null;
 }
 
 /** True when the catalog has ANY row (any tier) under this vendor's namespace, in either gateway. */

package/src/utils/no-output-backstop.js

@@ -0,0 +1,48 @@
+/**
+ * @module utils/no-output-backstop
+ * v4.6.2 PR2 (spec §5, D4): fail a headless leg fast when the model produces
+ * ZERO output, reasoning, and tool calls — the "accepted but not serving"
+ * class (the v4.6.1 gemini release-gate incident: requests accepted, zero
+ * tokens, three suites burned 130s timeouts each to learn nothing).
+ *
+ * Pure state machine, loop-driven (no timers of its own — the poll loop
+ * ticks it): armed at leg start, DISARMED PERMANENTLY by the first
+ * `progressed` tick (a 30-90s cold-prefill local model is never affected),
+ * fired when the deadline passes with nothing ever observed. `fired` is
+ * terminal. `ms <= 0` never arms — 0 is the documented escape hatch, which
+ * is why the env resolver uses envNumber (explicit 0 honored) rather than
+ * the `Number(env) || default` idiom.
+ *
+ * PR3's live probe reuses this with a 30s override — ms is an input; only
+ * the exported resolver reads the environment.
+ */
+'use strict';
+
+const { envNumber } = require('./env-num');
+
+const DEFAULT_NO_OUTPUT_BACKSTOP_MS = 120000;
+
+/** @param {object} [env] test seam; defaults to process.env */
+function resolveNoOutputBackstopMs(env) {
+  return envNumber('AMICUS_NO_OUTPUT_BACKSTOP_MS', DEFAULT_NO_OUTPUT_BACKSTOP_MS, env);
+}
+
+/**
+ * @param {{ms:number, startedAt:number}} opts
+ * @returns {{tick:(progressed:boolean, nowMs:number)=>string, state:()=>string}}
+ */
+function createNoOutputBackstop({ ms, startedAt }) {
+  let state = ms > 0 ? 'armed' : 'disarmed';
+  const deadline = startedAt + ms;
+  return {
+    tick(progressed, nowMs) {
+      if (state !== 'armed') { return state; }
+      if (progressed) { state = 'disarmed'; return state; }
+      if (nowMs >= deadline) { state = 'fired'; }
+      return state;
+    },
+    state() { return state; },
+  };
+}
+
+module.exports = { resolveNoOutputBackstopMs, createNoOutputBackstop, DEFAULT_NO_OUTPUT_BACKSTOP_MS };

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/result-schema.js

@@ -192,10 +192,32 @@ function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null,
  * of curated DEFAULT aliases (toGatewayRoutes() vs. the live catalog),
  * distinct from the flat `stale` audit above. Defaults to [] so existing
  * callers that omit it are unaffected.
+ * `drifted` (v4.6.2 PR1, 2A) is additive: stored user-config aliases whose
+ * target is still catalog-live but behind the current quick-pick family
+ * resolution (findDriftedStoredAliases). Defaults to [] so existing callers
+ * that omit it are unaffected. Paired with an additive `driftedCount`
+ * (drifted.length), mirroring the staleCount/stale and
+ * gatewayFindingsCount/gatewayFindings pairs above.
+ * `probe` (v4.6.2 PR3, spec §6 D5) is additive: the `--live` opt-in per-alias
+ * probe outcomes (probeStoredAliases — served/accepted-but-silent/error), one
+ * row per stored alias actually probed. Defaults to [] so every call without
+ * --live (i.e. every existing caller) is unaffected. Paired with an additive
+ * `probeCount` (probe.length), mirroring the driftedCount/drifted pair above.
+ * `probeSkipped` (v4.6.2 PR3 Task 4) is additive: null when the probe ran or
+ * `--live` wasn't requested; otherwise a stable reason slug (e.g.
+ * 'catalog-unavailable') for the one case this function can see — the
+ * `--refresh --check --live` skip (runRefresh returns before this is ever
+ * called) is announced by the caller instead, since that path emits a
+ * model-catalog doc, not this one.
  * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean,
- *   gatewayFindings?: Array<{alias,gateway,kind,model,expected?}>}} opts
+ *   gatewayFindings?: Array<{alias,gateway,kind,model,expected?}>,
+ *   drifted?: Array<{alias,stored,current}>,
+ *   probe?: Array<{alias,target,outcome,detail,cost}>,
+ *   probeSkipped?: string|null}} opts
  */
-function buildAuditDoc({ stale, catalogAvailable, gatewayFindings = [] }) {
+function buildAuditDoc({
+  stale, catalogAvailable, gatewayFindings = [], drifted = [], probe = [], probeSkipped = null
+}) {
   return {
     schemaVersion: SCHEMA_VERSION,
     type: 'alias-audit',
@@ -204,6 +226,11 @@ function buildAuditDoc({ stale, catalogAvailable, gatewayFindings = [] }) {
     stale,
     gatewayFindingsCount: gatewayFindings.length,
     gatewayFindings,
+    driftedCount: drifted.length,
+    drifted,
+    probeCount: probe.length,
+    probe,
+    probeSkipped,
   };
 }
 

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/live-normalize.js

@@ -126,6 +126,7 @@ function normalizeLive(doc) {
     stageName: active ? active.name : null,
     stages,
     seats: legRowsOf(doc).map(seatOf),
+    degrades: Array.isArray(doc.degrades) ? doc.degrades : [],
     // ⚠️ v4.4.1 RN-8 (D1 ruling: delete the promise). `legsTotal`/`legsComplete` used to be
     // mapped here under a comment promising them as "the honest fallback readout if a seat row
     // is ever unavailable" — a UI fallback nobody ever wired. Nothing in electron/workspace-ui/