amicus 4.6.0 → 4.6.2

package/src/headless.js

@@ -454,19 +454,72 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       promptOptions.reasoning = reasoning;
     }
 
-    // Send prompt asynchronously (returns immediately, we poll for results)
+    // v4.6.2 PR2 amendment (controller live smoke, field evidence): arm BEFORE
+    // the prompt send, not after. OpenCode's prompt-send handler can itself
+    // block on the upstream provider call before ever returning — a silently-
+    // accepting endpoint (the v4.6.1 gemini class) hung the very next line's
+    // await for 6+ minutes with the backstop never even created yet, upstream
+    // of every mechanism that was supposed to catch it. `startedAt` here means
+    // "time since the leg asked for output". Disarmed permanently by the first
+    // SUBSTANTIVE-activity tick in the poll loop below (output/tool/result/
+    // reasoning/settle — NOT the placeholder-compatible message/assistant-id
+    // signals; see substantiveActivity); 0 (or negative) disables — the
+    // send itself is unbounded in that case too (see withTimeout below).
+    const { resolveNoOutputBackstopMs, createNoOutputBackstop } = require('./utils/no-output-backstop');
+    // v4.6.2 PR3 Task 1: Number.isFinite, not `!== undefined` — a non-number
+    // (e.g. a string arriving from a CLI/JSON boundary) must fall through to
+    // env resolution instead of reaching the deadline arithmetic below.
+    // `startedAt + ms` string-concatenates when ms is a string, producing a
+    // deadline `nowMs >= deadline` can never satisfy — the backstop would
+    // silently never fire. Finite zero (the documented explicit-disable
+    // value) still takes the direct branch: Number.isFinite(0) === true.
+    const noOutputBackstopMs = Number.isFinite(options.noOutputBackstopMs)
+      ? options.noOutputBackstopMs : resolveNoOutputBackstopMs(options._env);
+    const noOutputBackstop = createNoOutputBackstop({ ms: noOutputBackstopMs, startedAt: Date.now() });
+    let backstopFired = false;
+    // Single source for the reason string so the pre-send firing site below and
+    // the per-poll firing site further down (still ticking the SAME instance)
+    // can never drift apart.
+    const noOutputBackstopReason = () => 'NO_OUTPUT_BACKSTOP: model produced no '
+      + `output, reasoning, or tool calls in ${Math.round(noOutputBackstopMs / 1000)}s `
+      + '— likely a listed-but-not-serving model or a dead endpoint';
+
+    // Send prompt asynchronously (returns immediately, we poll for results) —
+    // bounded by the backstop: an endpoint that accepts but never answers must
+    // not hang this await the way it hung the field-observed leg.
     logger.info('Sending prompt to OpenCode', {
       sessionId,
       model,
       agent: promptOptions.agent,
       userMessageLength: userMessage.length
     });
-    const promptResult = await sendPromptAsync(client, sessionId, promptOptions);
-    writeProgress(sessionDir, 'prompt_sent');
-    logger.info('Prompt sent successfully, entering polling loop', {
-      sessionId,
-      timeoutMs
-    });
+    const sendPromptLabel = 'sendPromptAsync';
+    const sendPromptPromise = sendPromptAsync(client, sessionId, promptOptions);
+    let promptResult = null;
+    try {
+      promptResult = await withTimeout(sendPromptPromise, noOutputBackstopMs, sendPromptLabel);
+      writeProgress(sessionDir, 'prompt_sent');
+      logger.info('Prompt sent successfully, entering polling loop', {
+        sessionId,
+        timeoutMs
+      });
+    } catch (sendErr) {
+      const isBackstopTimeout = noOutputBackstopMs > 0
+        && sendErr.message === `${sendPromptLabel} timed out after ${noOutputBackstopMs}ms`;
+      if (!isBackstopTimeout) { throw sendErr; } // a genuine sendPromptAsync failure — unchanged behavior
+      // The backstop deadline won the race — OpenCode never returned from the
+      // prompt-send call at all; the "accepts, never responds" shape dies
+      // upstream of the poll loop entirely. Swallow the orphaned promise so it
+      // can never surface as an unhandled rejection whenever/if it eventually
+      // settles on its own (Promise.race already subscribes each racer
+      // internally, so this is defensive belt-and-suspenders, not load-bearing
+      // — verified empirically before relying on it).
+      sendPromptPromise.catch(() => {});
+      backstopFired = true;
+      logger.warn('No-output backstop fired before the prompt send resolved', {
+        taskId, sessionId, backstopMs: noOutputBackstopMs,
+      });
+    }
 
     const mirror = createMirrorState();
     let completed = false;
@@ -474,6 +527,14 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let aborted = false;
     let sessionError = null; // Captures model/SDK errors from assistant messages
 
+    // Seed sessionError exactly like the #37 boundary-provider-error case right
+    // below does, so the run ends with a usable reason (the poll loop is
+    // skipped entirely on this path — see the while-condition and the
+    // backstop-abort block further down).
+    if (backstopFired) {
+      sessionError = noOutputBackstopReason();
+    }
+
     // Hard provider failure detected at the client boundary (#37): a non-2xx /
     // 402 from promptAsync surfaces here even when the server never emits an
     // assistant message carrying info.error. Seed sessionError so the loop's
@@ -573,7 +634,14 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       return false;
     };
 
-    while (!completed && (Date.now() - startTime) < timeoutMs) {
+    // `!backstopFired`: a no-op for the pre-existing mid-loop firing path (that
+    // branch already `break`s the instant it sets backstopFired, so this outer
+    // condition is never re-checked with it true from there) — it only matters
+    // for the NEW pre-send-timeout path above, where backstopFired can already
+    // be true before the loop ever starts. Skips the loop entirely rather than
+    // burning one wasted pollIntervalMs sleep before falling through to the
+    // post-loop abort block below.
+    while (!completed && !backstopFired && (Date.now() - startTime) < timeoutMs) {
       watchdog.touch();
       await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
 
@@ -729,6 +797,26 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           || newAssistant || reasoningActivity || settleActivity;
         if (progressed) { lastProgressAt = Date.now(); }
 
+        // v4.6.2 PR2 amendment 2 (controller live smoke + debug trace): the
+        // backstop disarms only on SUBSTANTIVE activity — output, reasoning,
+        // or tool motion (the spec's "first token/reasoning/tool_use").
+        // messageActivity/newAssistant are excluded: OpenCode creates an empty
+        // assistant placeholder on prompt ACCEPTANCE, which is precisely the
+        // accepted-but-not-serving bookkeeping the backstop must not trust.
+        // `progressed` itself (and every stall/idle consumer of it above) is
+        // deliberately untouched — this is a narrower, backstop-only signal.
+        const substantiveActivity = outputGrew || toolActivity || resultActivity
+          || reasoningActivity || settleActivity;
+
+        // No-output backstop: one tick per poll. Fired is terminal — break the
+        // loop; the post-loop block below mirrors the timeout path.
+        if (noOutputBackstop.tick(substantiveActivity, Date.now()) === 'fired') {
+          backstopFired = true;
+          sessionError = noOutputBackstopReason();
+          logger.warn('No-output backstop fired', { taskId, backstopMs: noOutputBackstopMs });
+          break;
+        }
+
         // B53: a wedged tool call (tool_use emitted, result never arrives) otherwise
         // burns the full --timeout with zero output — the stable-poll idle gate above
         // requires mirror.output.length > 0, which a pre-text wedge never satisfies.
@@ -832,7 +920,15 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     });
 
     // Handle timeout
-    if (!completed && !aborted && (Date.now() - startTime) >= timeoutMs) {
+    // v4.6.2 PR2 fix wave: `!backstopFired` — the backstop's own break can
+    // land after the post-break poll tail (getMessages + mirror processing
+    // already inside that iteration) has ALSO crossed timeoutMs when the two
+    // thresholds are configured close together, so this block must yield
+    // once the backstop already ended the leg. Exactly one terminal-timing
+    // signal per leg: statusFromResult() (src/utils/result-schema.js) checks
+    // timedOut BEFORE error, so a leg carrying both would misreport as an
+    // ordinary 'timeout' instead of the distinctly-named backstop reason.
+    if (!completed && !aborted && !backstopFired && (Date.now() - startTime) >= timeoutMs) {
       timedOut = true;
       logger.warn('Task timed out', { taskId, elapsed: Date.now() - startTime });
 
@@ -846,6 +942,20 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       }
     }
 
+    // Backstop fired: abort the OpenCode session exactly like the timeout path
+    // (the agent keeps running otherwise). The leg's error already carries the
+    // NO_OUTPUT_BACKSTOP reason; no separate degrade machinery — the ordinary
+    // dead-leg path (SL-2 retry, sink announcement, exit codes) inherits it.
+    if (backstopFired && !completed && !aborted) {
+      try {
+        const { abortSession } = require('./opencode-client');
+        await abortSession(client, sessionId, ...dirArgs);
+        logger.info('Session aborted after no-output backstop', { taskId, sessionId });
+      } catch (abortErr) {
+        logger.warn('Failed to abort session after backstop', { error: abortErr.message });
+      }
+    }
+
     watchdog.cancel();
     if (uninstallSignals) { uninstallSignals(); }
 

package/src/mcp-council-awareness.js

@@ -185,6 +185,7 @@ function buildCouncilStatusPayload(project, taskId) {
     legsTotal, legsComplete, elapsed: elapsedOf(run),
     exitCode: run.exitCode !== undefined ? run.exitCode : null,
     version: RUNNING_VERSION,
+    degrades: run.degrades || [],
   };
   if (usageLegs.length) { payload.usage = rollupWaveUsage(usageLegs); }
   if (allLegIds.length) {

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

@@ -557,6 +557,27 @@ function buildServerOptions(options = {}) {
     : (options.model ? [options.model] : []);
   config.provider = buildProviderModels(resolvedForProvider);
 
+  // v4.6.2 PR1 (spec §4, D1/D2): a host-form ANTHROPIC_BASE_URL is correct
+  // for Anthropic SDKs (they append /v1) and fatal for OpenCode's
+  // direct-anthropic provider (it appends /messages -> 404). Carry the
+  // normalized full-prefix form as a provider-config override — config-level,
+  // no process env is written anywhere. AMICUS_BASE_URL_NORMALIZE=0 disables.
+  // Merge order keeps any existing options.baseURL authoritative (M-5 lesson:
+  // never clobber a user-authored value with a derived one).
+  const { resolveBaseUrlOverride, announceBaseUrlNormalizationOnce } = require('./utils/base-url-classify');
+  const baseUrlEnv = options._env || process.env;
+  const anthropicBaseUrl = resolveBaseUrlOverride(baseUrlEnv);
+  if (anthropicBaseUrl) {
+    if (!Object.prototype.hasOwnProperty.call(config.provider, 'anthropic')) {
+      config.provider.anthropic = { models: {} };
+    }
+    config.provider.anthropic.options = {
+      baseURL: anthropicBaseUrl,
+      ...(config.provider.anthropic.options || {}),
+    };
+    announceBaseUrlNormalizationOnce(baseUrlEnv.ANTHROPIC_BASE_URL, anthropicBaseUrl, options._noticeDeps);
+  }
+
   // Register custom 'chat' agent: reads auto-approved, writes/bash require permission
   const chatAgent = {
     description: 'Conversational agent — reads are auto-approved, writes and commands require permission',

package/src/sidecar/fanout-leg.js

@@ -74,7 +74,7 @@ function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
  * Adds `.reason` (alias of buildRunResult's `.error`) and `.legId` so the
  * fallback loop reads a stable shape without re-deriving them.
  */
-async function runSingleAttempt({ leg, legId, waveId, project, directory, follow, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce }) {
+async function runSingleAttempt({ leg, legId, waveId, project, directory, follow, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce, noOutputBackstopMs }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
@@ -121,7 +121,7 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     result = await runHeadless(
       leg.model, systemPrompt, userMessage, legId, project,
       timeoutMs, agent || 'build',
-      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce, directory }
+      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce, directory, noOutputBackstopMs }
     );
   } catch (err) {
     result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId: legId };

package/src/sidecar/fanout.js

@@ -267,7 +267,7 @@ async function runFanout(options) {
         timeoutMs, agent: options.agent, client, server,
         summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
         foldNonce, directory: options.directory, follow,
-        fallback: options.fallback, catalog: options.catalog,
+        fallback: options.fallback, catalog: options.catalog, noOutputBackstopMs: options.noOutputBackstopMs,
       });
     }));
   } finally {

package/src/sidecar/models-probe.js

@@ -0,0 +1,119 @@
+// src/sidecar/models-probe.js
+'use strict';
+
+/**
+ * @module models-probe
+ * v4.6.2 PR3 (spec §6, D5): `models --check --live` probe tier. Presence in
+ * the catalog is not proof of service — a stored alias can point at a model
+ * id the catalog still lists but the provider no longer actually serves (the
+ * v4.6.1 `gemini` incident: stored `google/gemini-3.1-flash-lite-preview`,
+ * catalog-live, silently dead). This module is the check that would have
+ * caught it: probe every STORED alias with one ordinary engine leg — real
+ * session dir, real spend-ledger row (D5) — on a single quiet fanout wave,
+ * and classify each leg served / accepted-but-silent / error.
+ *
+ * Never called without `--live`; the spend gate lives in the CLI layer
+ * (src/sidecar/models.js), not here — this module always spends when called.
+ */
+
+/** Probe backstop override (spec D5) — a fixed constant, NOT env-configurable;
+ * the env knob (AMICUS_NO_OUTPUT_BACKSTOP_MS) stays the ordinary 120s leg default. */
+const PROBE_WINDOW_MS = 30000;
+
+/** Fixed tiny prompt — a probe leg only needs to prove the model answers at all. */
+const PROBE_PROMPT = 'Reply with exactly: OK';
+
+/**
+ * Classify one leg run-document (buildRunResult shape, src/utils/result-
+ * schema.js) per the plan's Global Constraints classification contract.
+ * Precedence matters: 'complete' wins outright; otherwise a NO_OUTPUT_
+ * BACKSTOP error (PR2's silent-leg detector, armed here at PROBE_WINDOW_MS
+ * instead of its 120s default) is the one specific error shape that means
+ * "the model accepted the request and never produced a token" rather than an
+ * ordinary routing/auth/timeout failure.
+ * @param {{status?:string, error?:string|null}} leg
+ * @returns {'served'|'accepted-but-silent'|'error'}
+ */
+function classifyLeg(leg) {
+  if (leg.status === 'complete') { return 'served'; }
+  if (typeof leg.error === 'string' && /^NO_OUTPUT_BACKSTOP:/.test(leg.error)) { return 'accepted-but-silent'; }
+  return 'error';
+}
+
+/**
+ * Stored (user-config) aliases only — the `--live` probe's scope (spec §6):
+ * defaults/curated-route rows follow the catalog by construction and have no
+ * "was it actually served" question for a live probe to answer. Exported so
+ * the CLI's cap pre-check (models.js) and this module share one predicate.
+ * @param {Array<{source:string}>} sources collectAliasSources() output
+ * @returns {Array<{alias:string,model:string,source:string}>}
+ */
+function selectStoredAliases(sources) {
+  return sources.filter(s => s.source === 'user-config');
+}
+
+/**
+ * Probe every STORED alias with one ordinary engine leg (real session dirs,
+ * real spend rows — D5) on one quiet fanout wave. Returns per-alias outcomes;
+ * never called without --live (the spend gate lives in the CLI layer).
+ * @param {{project?:string}} opts
+ * @param {{runFanout?:Function, collectAliasSources?:Function}} [deps]
+ * @returns {Promise<{results:Array<{alias:string,target:string,outcome:'served'|'accepted-but-silent'|'error',detail:string|null,cost:number|null}>, waveId:string|null}>}
+ */
+async function probeStoredAliases(opts = {}, deps = {}) {
+  const collectAliasSources = deps.collectAliasSources || require('../utils/alias-audit').collectAliasSources;
+  const runFanout = deps.runFanout || require('./fanout').runFanout;
+
+  const stored = selectStoredAliases(collectAliasSources());
+  if (stored.length === 0) { return { results: [], waveId: null }; }
+
+  // runFanout's `models` is the same comma-separated STRING the CLI --models
+  // flag takes (validateFanoutModels -> parseModelsList splits it back apart)
+  // — NOT an array; see council/run-launch.js's launchWave for the identical
+  // `.join(',')` seam. An array here would parse to [] and fail the whole
+  // wave with BAD_ARGS.
+  const { wave, errorDoc } = await runFanout({
+    models: stored.map(s => s.model).join(','),
+    prompt: PROBE_PROMPT,
+    quiet: true,
+    noOutputBackstopMs: PROBE_WINDOW_MS,
+    timeout: 2, // minutes — the overall ceiling behind the backstop
+    project: opts.project,
+  });
+
+  // Final-review blocker 1: two classes of wave never reach leg-creation at
+  // all — the budget preflight refusing before any session exists (failPre ->
+  // {wave: null, errorDoc}) or the shared server failing to start (errorWave ->
+  // {legs: [], error: message}) — so EVERY stored alias would otherwise hit
+  // the `legs[i] || {}` fallback and fabricate a generic `detail: null` row,
+  // which the CLI's `${head} — ${r.detail}` template renders as the literal
+  // string "null", masking the real reason (worse with `quiet: true`, which
+  // suppresses every other print this failure would normally surface on).
+  // Both failure classes carry a real message; thread it onto every row that
+  // has no leg of its own to explain itself.
+  const waveFailure = errorDoc ? errorDoc.message : ((wave && wave.error) || null);
+
+  // Positional zip, not a model-id lookup: deriveLegIds (fanout.js) assigns
+  // legs 1:1 in --models order, and two stored aliases may legitimately share
+  // one target model, so a leg's own identity can't disambiguate which alias
+  // it answers for — only its index can.
+  const legs = (wave && wave.legs) || [];
+  const results = stored.map((s, i) => {
+    const leg = legs[i] || {};
+    const outcome = classifyLeg(leg);
+    const cost = (leg.usage && leg.usage.cost && typeof leg.usage.cost.amount === 'number')
+      ? leg.usage.cost.amount
+      : null;
+    return {
+      alias: s.alias,
+      target: s.model,
+      outcome,
+      detail: leg.error || waveFailure || null,
+      cost,
+    };
+  });
+
+  return { results, waveId: (wave && wave.waveId) || null };
+}
+
+module.exports = { probeStoredAliases, selectStoredAliases, PROBE_WINDOW_MS, PROBE_PROMPT };

package/src/sidecar/models.js

@@ -5,6 +5,7 @@
  *   amicus models --search <q>     substring filter over id+name
  *   amicus models --refresh        force-refresh the cache
  *   amicus models --check          stale-alias audit (exit = stale count, max 100)
+ *   amicus models --check --live   + probe every stored alias with a real leg (spends)
  *   --json on all of the above     versioned documents (result-schema)
  *
  * Returns an exit code; bin/amicus.js plumbs it like fanout's.
@@ -13,11 +14,13 @@
 'use strict';
 
 const { getCatalogInfo, refreshCatalog, catalogPath } = require('../utils/model-catalog');
-const { collectAliasSources, findStaleAliases, suggestReplacements } = require('../utils/alias-audit');
+const { collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements } = require('../utils/alias-audit');
 const { auditGatewayRoutes } = require('../utils/gateway-route-audit');
 const { buildCatalogDoc, buildAuditDoc } = require('../utils/result-schema');
 const { getFamilies } = require('../utils/curated-models');
 const { pickCurrent } = require('../utils/quick-picks');
+const { probeStoredAliases, selectStoredAliases } = require('./models-probe');
+const { DEFAULT_MAX_LEGS } = require('./fanout-validate');
 
 const CHECK_EXIT_CAP = 100;
 
@@ -91,9 +94,19 @@ async function runList(args) {
   return 0;
 }
 
+// v4.6.2 PR3 Task 4: shared --live skip line; reason doubles as the JSON probeSkipped slug.
+function fmtLiveSkipped(reason) {
+  return `--live skipped: ${reason} — nothing was probed`;
+}
+
 async function runRefresh(args) {
   const models = await refreshCatalog();
   const { fetchedAt, lastRefreshAttempt, lastRefreshError } = await getCatalogInfo({ maxAgeMs: Number.POSITIVE_INFINITY });
+  // --refresh short-circuits --check below (args.check is guaranteed true here) — must announce, not silently skip.
+  if (args.live) {
+    const line = fmtLiveSkipped('refresh-precedes-check');
+    (args.json ? process.stderr : process.stdout).write(line + '\n');
+  }
   if (args.json) {
     process.stdout.write(JSON.stringify(buildCatalogDoc({
       models, fetchedAt, refreshed: true, lastRefreshAttempt, lastRefreshError
@@ -128,41 +141,87 @@ function fmtGatewayFinding(f) {
   return `  GATEWAY DIVERGENT: ${f.alias} direct form ${f.model} no longer matches catalog (now ${f.expected})`;
 }
 
+const PROBE_LABELS = { served: 'SERVED', 'accepted-but-silent': 'SILENT', error: 'ERROR' };
+
+/** '$0.0004' | '$1.23' | '—' (unknown). Deliberately NOT formatCost (pricing.js):
+ * a probe result's `cost` is a bare number (models-probe.js doesn't carry the
+ * reported/estimated source tag), so this never claims a precision it can't back. */
+function fmtProbeCost(cost) {
+  if (cost === null || cost === undefined || Number.isNaN(cost)) { return '—'; }
+  return cost < 1 ? `$${cost.toFixed(4)}` : `$${cost.toFixed(2)}`;
+}
+
+/** One readable line per probed alias (`--check --live`, v4.6.2 PR3): uppercase
+ * class prefix padded to a fixed column, two-space indent — mirrors the STALE/
+ * DRIFTED/GATEWAY line style above. @param {object} r probeStoredAliases() row */
+function fmtProbeLine(r) {
+  const head = `  ${(PROBE_LABELS[r.outcome] + ':').padEnd(8)}${r.alias} -> ${r.target}`;
+  if (r.outcome === 'served') { return `${head} (${fmtProbeCost(r.cost)})`; }
+  if (r.outcome === 'accepted-but-silent') { return `${head} — ${r.detail} (accepted but not serving)`; }
+  return `${head} — ${r.detail}`;
+}
+
 async function runCheck(args) {
   const catalogInfo = await getCatalogInfo();
   const catalog = catalogInfo.models;
   if (!catalog || catalog.length === 0) {
+    const probeSkipped = args.live ? 'catalog-unavailable' : null;
     if (args.json) {
       process.stdout.write(JSON.stringify(buildAuditDoc({
-        stale: [], catalogAvailable: false
+        stale: [], catalogAvailable: false, probeSkipped
       }), null, 2) + '\n');
     } else {
       process.stdout.write('Catalog unavailable (offline or no providers reachable); cannot check.\n');
+      if (probeSkipped) { process.stdout.write(fmtLiveSkipped(probeSkipped) + '\n'); }
     }
     return 0;
   }
   const sources = collectAliasSources();
   const stale = findStaleAliases(sources, catalog)
     .map(s => ({ ...s, suggestions: suggestReplacements(s.model, catalog) }));
+  const drifted = findDriftedStoredAliases(sources, catalog);
   // Task 6 (#gwid): per-gateway-form audit of the curated DEFAULTS
   // (toGatewayRoutes()) — additive to the flat audit above. Informational by
   // default; --strict promotes it to a build-breaking exit code (CI gate).
   const gatewayFindings = auditGatewayRoutes(catalogInfo);
   const legacyExitCode = Math.min(stale.length, CHECK_EXIT_CAP);
-  const exitCode = args.strict
+  let exitCode = args.strict
     ? Math.max(legacyExitCode, Math.min(gatewayFindings.length, CHECK_EXIT_CAP))
     : legacyExitCode;
 
+  // v4.6.2 PR3 (spec §6, D5): opt-in --live probe of stored aliases with real
+  // engine legs. Never spends without --live — probeStoredAliases is only
+  // ever called inside this block (regression-tested: a mocked module must
+  // see zero calls when the flag is absent). The cap pre-check runs BEFORE
+  // the call so a doomed wave never spends a token (Task 2 review carry-in:
+  // without it, runFanout fails wave-creation and models-probe.js degrades
+  // every row to a generic error, losing the real reason).
+  let probeResults = [];
+  if (args.live) {
+    const storedCount = selectStoredAliases(sources).length;
+    const envCap = Number(process.env.AMICUS_FANOUT_MAX_LEGS);
+    const maxLegs = (Number.isInteger(envCap) && envCap > 0) ? envCap : DEFAULT_MAX_LEGS;
+    if (storedCount > maxLegs) {
+      process.stderr.write(`Error: --live would probe ${storedCount} stored aliases, exceeding the `
+        + `fan-out cap of ${maxLegs} (set AMICUS_FANOUT_MAX_LEGS to raise)\n`);
+      return 1;
+    }
+    const probe = await probeStoredAliases({ project: args.cwd || process.cwd() });
+    probeResults = probe.results;
+    const nonServed = probeResults.filter(r => r.outcome !== 'served').length;
+    exitCode = Math.max(exitCode, Math.min(nonServed, CHECK_EXIT_CAP));
+  }
+
   if (args.json) {
     process.stdout.write(JSON.stringify(buildAuditDoc({
-      stale, catalogAvailable: true, gatewayFindings
+      stale, catalogAvailable: true, gatewayFindings, drifted, probe: probeResults
     }), null, 2) + '\n');
     return exitCode;
   }
   const driftLines = buildFallbackDriftReport(catalog);
-  if (stale.length === 0) {
+  if (stale.length === 0 && drifted.length === 0) {
     process.stdout.write(`All aliases resolve to catalog models (${sources.length} checked).\n`);
-  } else {
+  } else if (stale.length > 0) {
     for (const s of stale) {
       process.stdout.write(`STALE: ${s.alias} -> ${s.model} (${s.source})\n`);
       if (s.suggestions.length > 0) {
@@ -173,10 +232,22 @@ async function runCheck(args) {
       }
     }
   }
+  for (const dr of drifted) {
+    process.stdout.write(`DRIFTED: ${dr.alias} -> ${dr.stored} (stored; current resolution: ${dr.current})\n`);
+    process.stdout.write(`  stored aliases don't follow catalog updates — refresh: amicus setup --add-alias ${dr.alias}=${dr.current}\n`);
+  }
   if (driftLines.length > 0) {
     process.stdout.write('Pinned fallback drift:\n');
     for (const l of driftLines) { process.stdout.write(l + '\n'); }
   }
+  if (args.live) {
+    if (probeResults.length === 0) {
+      process.stdout.write('Live probe: no stored aliases to probe\n');
+    } else {
+      process.stdout.write(`Live probe (${probeResults.length} stored aliases):\n`);
+      for (const r of probeResults) { process.stdout.write(fmtProbeLine(r) + '\n'); }
+    }
+  }
   if (gatewayFindings.length > 0) {
     process.stdout.write('Per-gateway route audit (curated defaults):\n');
     for (const f of gatewayFindings) { process.stdout.write(fmtGatewayFinding(f) + '\n'); }
@@ -209,6 +280,10 @@ async function handleModels(args) {
     process.stderr.write('Error: --search requires a value\n');
     return 1;
   }
+  if (args.live && !args.check) {
+    process.stderr.write('Error: --live requires --check\n');
+    return 1;
+  }
   if (args.refresh) { return runRefresh(args); }
   if (args.check) { return runCheck(args); }
   return runList(args);

package/src/utils/alias-audit.js

@@ -108,4 +108,55 @@ function suggestReplacements(staleModel, catalog, n = 3) {
     .slice(0, n);
 }
 
-module.exports = { collectAliasSources, findStaleAliases, suggestReplacements };
+/**
+ * Stored aliases whose target is LIVE in the catalog but no longer what a
+ * fresh `amicus setup` would seed today — the v4.6.1 release-gate class
+ * (stored `gemini` -> 3.1-flash-lite-preview: still catalog-listed so
+ * findStaleAliases passes it, no longer what the family resolves to).
+ * Report + suggest, never auto-repair (this module's charter).
+ *
+ * Only user-config rows are checked (defaults/curated follow the catalog by
+ * construction), only for aliases that are quick-pick families (a custom
+ * alias has no "current" to drift from), and only when the stored target is
+ * itself catalog-live (a dead target is findStaleAliases's finding, not
+ * ours). The `current` display value goes through toStorableRoute() — the
+ * guarded 4.1.2 helper — never a bare prefix strip (spec D3).
+ *
+ * Drift membership, however, is NOT a raw compare against that single
+ * canonicalized display string. toStorableRoute() canonicalizes a
+ * direct-capable vendor's OpenRouter pick down to the bare direct form
+ * (e.g. 'google/gemini-3.6-flash'), but a stored alias may legitimately hold
+ * the gateway-prefixed form of that SAME model ('openrouter/google/gemini-
+ * 3.6-flash' — the exact route pickCurrent/resolveQuickPicks resolves live,
+ * and what a STALE fix's own suggestion may have pointed a user to store).
+ * Comparing only against the canonicalized string would false-positive that
+ * as drift. Instead, a stored row only counts as drift when its model is
+ * absent from the family's FULL live route-value set (every value in that
+ * family's `routes` map — openrouter form and any direct form together, per
+ * resolveQuickPicks) — i.e. it names a genuinely different model, not the
+ * same model under a different gateway form.
+ * @param {Array<{alias:string,model:string,source:string}>} sources
+ * @param {Array<{id:string}>} catalog
+ * @returns {Array<{alias:string,stored:string,current:string}>}
+ */
+function findDriftedStoredAliases(sources, catalog) {
+  if (!catalog || catalog.length === 0) { return []; }
+  const { resolveQuickPicks, toStorableRoute } = require('./quick-picks');
+  const current = new Map();
+  for (const r of resolveQuickPicks(catalog)) {
+    if (r.source !== 'live') { continue; }
+    const stored = toStorableRoute(r);
+    if (stored) { current.set(r.alias, { display: stored, routeValues: new Set(Object.values(r.routes)) }); }
+  }
+  const byProvider = idsByProvider(catalog);
+  return sources
+    .filter(({ source }) => source === 'user-config')
+    .filter(({ model }) => {
+      const ids = byProvider.get(model.split('/')[0]);
+      return !!(ids && ids.has(model));
+    })
+    .filter(({ alias, model }) => current.has(alias) && !current.get(alias).routeValues.has(model))
+    .map(({ alias, model }) => ({ alias, stored: model, current: current.get(alias).display }));
+}
+
+module.exports = { collectAliasSources, findStaleAliases, findDriftedStoredAliases, suggestReplacements };