amicus 4.6.2 → 4.7.0

package/src/sidecar/read.js

@@ -10,6 +10,11 @@ const path = require('path');
 const { safeSessionDir, TASK_ID_PATTERN } = require('../utils/validators');
 const { SESSIONS_DIR } = require('../session-manager');
 const { fenceSidecarOutput } = require('../utils/untrusted-fence');
+// F8 D15 (errata E-PR3-5) search core — split out (T6 review) to keep this
+// file under its line budget; both list surfaces still reach it through
+// this module's own searchSessions re-export below.
+const { searchSessions } = require('./list-search');
+const { normalizeLimit, truncationNotice } = require('./list-limit');
 
 /**
  * Format a timestamp as relative age
@@ -54,6 +59,8 @@ function enumerateSessions(project, opts = {}) {
           type: meta.type || 'run',
           parentWave: meta.parentWave || null,
           legCount: Array.isArray(meta.legs) ? meta.legs.length : null,
+          mode: meta.mode || (meta.headless ? 'headless' : 'interactive'),
+          ...(meta.tag ? { tag: meta.tag } : {}),
         });
       } catch { /* skip unreadable */ }
     }
@@ -67,29 +74,96 @@ function enumerateSessions(project, opts = {}) {
   return sessions;
 }
 
+/**
+ * Enumerate sessions across every project the global sessions-index
+ * (src/utils/session-index.js) knows about, plus the current project. --all
+ * support (F8 D14): the index is a navigation aid, never authoritative, so a
+ * stale entry pointing at a missing/unreadable project directory is skipped
+ * silently rather than surfaced as an error.
+ *
+ * Dedup is by CANONICAL identity (T5 review fix-wave): the index stores
+ * canonical spellings (canonicalProjectPath — forward slashes, upper-cased
+ * drive letter) while `project` arrives however the caller spelled it
+ * (process.cwd() is backslashed on Windows). A raw string Set treated those
+ * as two different projects, double-counting every row of the current
+ * project whenever it was also present in the index (which it usually is —
+ * every session start records itself). The current project is seeded FIRST
+ * so its rows keep the caller's spelling rather than the index's.
+ * @param {{status?: string, project?: string}} [opts]
+ * @returns {Array<object>} enumerateSessions rows, each stamped with `project`
+ */
+function enumerateAllProjects(opts = {}) {
+  const { status, project = process.cwd() } = opts;
+  const { readIndex } = require('../utils/session-index');
+  const { canonicalProjectPath } = require('../utils/project-path');
+  const index = readIndex();
+
+  const byCanonical = new Map();
+  for (const p of [project, ...Object.values(index)]) {
+    if (!p || typeof p !== 'string') { continue; }
+    const key = canonicalProjectPath(p);
+    if (!byCanonical.has(key)) { byCanonical.set(key, p); }
+  }
+
+  let sessions = [];
+  for (const p of byCanonical.values()) {
+    try {
+      const rows = enumerateSessions(p, {}).map(s => ({ ...s, project: p }));
+      sessions = sessions.concat(rows);
+    } catch { /* unreadable project — skip silently */ }
+  }
+
+  sessions.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  if (status && status !== 'all') {
+    sessions = sessions.filter(s => s.status === status);
+  }
+  return sessions;
+}
+
 /**
  * List previous sidecar sessions
  * Spec Reference: §4.2
  *
  * @param {object} options
  * @param {string} [options.status] - Filter by status (all, running, complete)
+ * @param {boolean} [options.all] - Cross-project via the global sessions-index (F8 D14)
  * @param {boolean} [options.json] - Output as JSON
  * @param {string} [options.project] - Project directory
+ * @param {string|boolean} [options.search] - id/tag/briefing substring filter (F8 D15); `true` = valueless flag (usage error)
+ * @param {number|string|boolean} [options.limit] - cap printed rows (PR3 rider); 0/absent = unlimited, `true` = valueless flag (usage error)
  */
 async function listSidecars(options) {
-  const { status, json, project = process.cwd() } = options;
+  const { status, all, json, search, limit, project = process.cwd() } = options;
+  // Mirrors models.js:279-281's valueless-flag shape.
+  if (search === true) { throw new Error('--search requires a value'); }
+  const cap = normalizeLimit(limit); // throws on valueless/non-integer/negative
 
-  const sessions = enumerateSessions(project, { status });
+  let sessions = all
+    ? enumerateAllProjects({ status, project })
+    : enumerateSessions(project, { status });
+  if (search) { sessions = searchSessions(sessions, search, { project }); }
   if (sessions.length === 0) {
     console.log('No amicus sessions found.');
     return;
   }
 
+  // v4.7 PR3 rider: cap OUTPUT only — the newest-first sort has already run, so
+  // slicing here yields the N most recent. Enumeration is deliberately NOT
+  // capped: `--all` must still walk every project or the sort would rank rows
+  // it never saw.
+  const total = sessions.length;
+  const truncated = cap > 0 && total > cap;
+  if (truncated) { sessions = sessions.slice(0, cap); }
+
   if (json) {
     console.log(JSON.stringify(sessions, null, 2));
   } else {
-    console.log('ID        MODEL                  STATUS     AGE         BRIEFING');
-    console.log('─'.repeat(80));
+    console.log(
+      'ID'.padEnd(10) + 'MODEL'.padEnd(23) + 'STATUS'.padEnd(11) +
+      'TAG'.padEnd(12) + 'AGE'.padEnd(12) + 'BRIEFING' +
+      (all ? '  PROJECT' : '')
+    );
+    console.log('─'.repeat(all ? 100 : 80));
     sessions.forEach(s => {
       const age = formatAge(s.createdAt);
       const briefingShort = (s.briefing || '').slice(0, 30) +
@@ -98,11 +172,20 @@ async function listSidecars(options) {
         `${(s.id || '').padEnd(10)}` +
         `${(s.type === 'wave' ? `wave(${s.legCount ?? 0} legs)` : (s.model || '')).padEnd(23)}` +
         `${(s.status || 'unknown').padEnd(11)}` +
+        `${(s.tag || '').padEnd(12)}` +
         `${age.padEnd(12)}` +
-        `${briefingShort}`
+        `${briefingShort}` +
+        (all ? `  ${s.project || ''}` : '')
       );
     });
   }
+
+  // No silent caps: say what was elided, and how to see it all. In --json mode
+  // this goes to stderr so stdout stays a single parseable document.
+  if (truncated) {
+    const notice = truncationNotice(cap, total);
+    if (json) { console.error(notice); } else { console.log(notice); }
+  }
 }
 
 /**
@@ -184,6 +267,8 @@ async function readSidecar(options) {
 module.exports = {
   formatAge,
   enumerateSessions,
+  enumerateAllProjects,
+  searchSessions,
   listSidecars,
   readSidecar
 };

package/src/sidecar/start-metadata.js

@@ -0,0 +1,58 @@
+// src/sidecar/start-metadata.js
+'use strict';
+
+/**
+ * @module start-metadata
+ * createSessionMetadata, split out of start.js to keep that file under the
+ * hard size gate (v4.7 PR3 Task 1: F8 relief). Pure move — same writes, same
+ * order, same atomicity. start.js re-exports this so no importer changes.
+ */
+
+const fs = require('fs');
+
+const { writeFileAtomic } = require('../utils/atomic-write');
+const { SessionPaths } = require('./session-utils');
+
+/** Create session directory and save metadata */
+function createSessionMetadata(taskId, project, options) {
+  const { model, prompt, briefing, noUi, headless, agent, thinking, pack, tag } = options;
+
+  const sessionDir = SessionPaths.sessionDir(project, taskId);
+  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+
+  const effectiveBriefing = prompt || briefing;
+  const isHeadless = noUi !== undefined ? noUi : headless;
+
+  // Preserve fields from existing metadata (e.g., pid written by MCP handler)
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    } catch {
+      // ignore corrupt metadata
+    }
+  }
+
+  const metadata = {
+    ...existing,
+    taskId,
+    model,
+    project,
+    briefing: effectiveBriefing,
+    mode: isHeadless ? 'headless' : 'interactive',
+    agent: agent || (isHeadless ? 'build' : 'chat'),
+    thinking: thinking || 'medium',
+    status: 'running',
+    pid: existing.pid || process.pid,
+    createdAt: existing.createdAt || new Date().toISOString(),
+    ...(pack ? { pack } : {}), // v4.5 Task 13: absent-not-null; ...existing above preserves a prior write when this call omits pack.
+    ...(tag ? { tag } : {}), // v4.7 F8 (D13): absent-not-null, same merge-preserve idiom as pack above.
+  };
+
+  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+
+  return sessionDir;
+}
+
+module.exports = { createSessionMetadata };

package/src/sidecar/start.js

@@ -27,53 +27,13 @@ const { mapAgentToOpenCode } = require('../utils/agent-mapping');
 const { discoverParentMcps } = require('../utils/mcp-discovery');
 const { stripSelfMcpEntries } = require('../utils/mcp-self-identity');
 const { generateFoldNonce } = require('../utils/fold-marker');
+const { createSessionMetadata } = require('./start-metadata');
 
 /** Generate a unique 8-character hex task ID */
 function generateTaskId() {
   return crypto.randomBytes(4).toString('hex');
 }
 
-/** Create session directory and save metadata */
-function createSessionMetadata(taskId, project, options) {
-  const { model, prompt, briefing, noUi, headless, agent, thinking, pack } = options;
-
-  const sessionDir = SessionPaths.sessionDir(project, taskId);
-  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
-
-  const effectiveBriefing = prompt || briefing;
-  const isHeadless = noUi !== undefined ? noUi : headless;
-
-  // Preserve fields from existing metadata (e.g., pid written by MCP handler)
-  const metaPath = SessionPaths.metadataFile(sessionDir);
-  let existing = {};
-  if (fs.existsSync(metaPath)) {
-    try {
-      existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
-    } catch {
-      // ignore corrupt metadata
-    }
-  }
-
-  const metadata = {
-    ...existing,
-    taskId,
-    model,
-    project,
-    briefing: effectiveBriefing,
-    mode: isHeadless ? 'headless' : 'interactive',
-    agent: agent || (isHeadless ? 'build' : 'chat'),
-    thinking: thinking || 'medium',
-    status: 'running',
-    pid: existing.pid || process.pid,
-    createdAt: existing.createdAt || new Date().toISOString(),
-    ...(pack ? { pack } : {}), // v4.5 Task 13: absent-not-null; ...existing above preserves a prior write when this call omits pack.
-  };
-
-  writeFileAtomic(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
-
-  return sessionDir;
-}
-
 /**
  * Build MCP configuration from options.
  * Merge priority: CLI --mcp > --mcp-config > file config > discovered parent MCPs
@@ -154,7 +114,7 @@ async function startSidecar(options) {
     contextMaxTokens = 80000, noUi, headless = false, timeout = 15,
     agent, mcp, mcpConfig, summaryLength = 'normal', thinking,
     client, sessionDir, noMcp, excludeMcp, opencodePort, coworkProcess, includeContext = true,
-    position = 'right', json = false, modelInput = null, pack = null
+    position = 'right', json = false, modelInput = null, pack = null, tag
   } = options;
 
   const effectivePrompt = prompt || briefing;
@@ -183,7 +143,7 @@ async function startSidecar(options) {
   );
 
   const sessDir = createSessionMetadata(taskId, effectiveProject, {
-    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking, pack
+    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking, pack, tag
   });
   saveInitialContext(sessDir, systemPrompt, userMessage);
   acquireLock(sessDir, effectiveHeadless ? 'headless' : 'interactive');
@@ -270,6 +230,11 @@ async function startSidecar(options) {
         gateway: String(model).startsWith('openrouter/') ? 'openrouter' : 'direct',
         // (To also attribute v4.2 'local': thread the resolved route gateway — dropped today at
         // cli-handlers-run.js:47 — into createSessionMetadata and read `meta.gateway`, as continue.js:111 does.)
+        // v4.7 F8 D16: same in-scope-value rule as gateway above — `m` is the
+        // just-re-read metadata (line 214), which carries `tag` when
+        // createSessionMetadata stored one (absent otherwise); `|| null` folds
+        // that into spend-ledger.js's null-not-absent dim convention.
+        tag: m.tag || null,
       });
     } catch { /* best-effort */ }
   }

package/src/sidecar/workspace-auto-open.js

@@ -23,7 +23,7 @@
  * @param {'ok'|'package-missing'|'binary-missing'} [options.electronState] - 3-state probe (#76); takes precedence
  * @param {string|null} [options.electronDir] - Resolved electron dir, named in the electron-broken reason
  * @param {string} options.platform - The platform (e.g., 'win32', 'darwin', 'linux')
- * @param {object} options.env - Environment variables object
+ * @param {object} [options.env] - Environment variables object
  * @param {boolean} options.autoOpenConfig - The config.workspace.autoOpen setting
  * @param {boolean|undefined} options.uiParam - Explicit UI parameter (true, false, or undefined)
  * @returns {{open: boolean, reason: string}}
@@ -34,7 +34,7 @@ function shouldAutoOpenWorkspace({
   electronState,
   electronDir,
   platform,
-  env,
+  env = {},
   autoOpenConfig,
   uiParam,
 }) {

package/src/spend-query.js

@@ -17,7 +17,7 @@
  * NOT hand-copy this array elsewhere: a 7th dimension added here must reach
  * both surfaces automatically, not just the one someone remembered to edit.
  */
-const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day'];
+const GROUP_DIMS = ['model', 'wave', 'council', 'project', 'op', 'day', 'tag'];
 
 /** Cap on rows returned when a caller opts into raw rows (CLI --rows / MCP rows:true). */
 const ROWS_CAP = 1000;
@@ -55,6 +55,7 @@ function rowKey(row, dimension) {
     case 'project': return row.project || '(unattributed)';
     case 'op': return row.op || '(unattributed)';
     case 'day': return typeof row.ts === 'string' ? row.ts.slice(0, 10) : '(unattributed)';
+    case 'tag': return row.tag || '(unattributed)';
     default: return '(unattributed)';
   }
 }

package/src/template/apply.js

@@ -52,10 +52,10 @@ function applyTemplate({ templateRef, prompt, artifactFile, varList, project })
     try {
       raw = fs.readFileSync(artifactPath);
     } catch (err) {
-      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: cannot read --artifact ${artifactFile}: ${err.message}`, hint: null } };
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: cannot read --artifact ${artifactFile}: ${err.message}`, hint: 'Check that the --artifact path exists and is readable — relative paths resolve from the current working directory.' } };
     }
     if (raw.length > ARTIFACT_CAP_BYTES) {
-      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: --artifact ${artifactFile} is ${raw.length} bytes; the cap is 256 KB`, hint: null } };
+      return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: `Error: --artifact ${artifactFile} is ${raw.length} bytes; the cap is 256 KB`, hint: 'Trim --artifact to under 256 KB, or point it at a smaller excerpt.' } };
     }
     artifact = raw.toString('utf-8');
     if (artifact.charCodeAt(0) === 0xFEFF) { artifact = artifact.slice(1); }
@@ -66,11 +66,14 @@ function applyTemplate({ templateRef, prompt, artifactFile, varList, project })
     artifact,
     artifactPath,
     date: new Date().toISOString().slice(0, 10),
-    project: String(project),
+    project: path.resolve(String(project)),
     vars,
   });
   if (res.error) {
-    return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: res.error, hint: null } };
+    // No variable list here on purpose: renderTemplate's own message already ends
+    // with a knownList()-derived "Known: ..." line. A copy would be a third
+    // hand-maintained KNOWN_VARIABLES mirror, which BACKLOG's T3-m2 hard gate forbids.
+    return { error: { code: ERROR_CODES.TEMPLATE_RENDER, message: res.error, hint: 'amicus template show <name>' } };
   }
 
   return {

package/src/template/render.js

@@ -7,8 +7,9 @@
  * happens ONLY in template files (spec carried decision 7) — --prompt text is
  * always literal, so this module never sees non-template input.
  *
- * v4.5 variable set. {{input}} is deliberately ABSENT — it ships with v4.6's
- * --input-from; on v4.5 it fails as an unknown variable, which is accurate.
+ * v4.5 variable set. {{input}} is deliberately ABSENT — it ships with
+ * composable waves (--input-from), a future rev; on v4.5 it fails as an
+ * unknown variable, which is accurate.
  * No {{model}}: prompts are built once per wave, model-independent.
  */
 
@@ -37,6 +38,9 @@ function renderTemplate(text, data) {
   for (const name of used) {
     if (name.startsWith('var.')) {
       const key = name.slice(4);
+      if (key === '') {
+        return { error: `Error: Unknown template variable {{var.}} — {{var.<key>}} requires a key. Known: ${knownList()}` };
+      }
       if (!(key in vars)) {
         return { error: `Error: template uses {{var.${key}}} but no --var ${key}=<value> was given` };
       }

package/src/template/store.js

@@ -18,7 +18,7 @@ function _getConfigDir() { return require('../utils/config').getConfigDir(); }
 
 /**
  * v4.5 ships `review` only. `critique`/`refine` are {{input}}-centric and
- * arrive with v4.6's chaining (--input-from).
+ * arrive with composable waves (--input-from).
  */
 const BUILTIN_TEMPLATES = Object.freeze({
   review: [

package/src/utils/alias-audit.js

@@ -62,6 +62,12 @@ function idsByProvider(catalog) {
  * at least one live resolution from any other source. This ensures the
  * suggested `--add-alias` fix actually clears the warning, and prevents
  * permanently unclearable noise when the default openrouter route is live.
+ *
+ * A stale 'defaults' entry is additionally suppressed when it is the alias's
+ * DERIVED direct-form pin (per curated-models.directFormProvenance()) and the
+ * alias is either covered live from another source or declares gatewayOnly
+ * (v4.6.3 PR1, spec D2) — an AUTHORED defaults pin and user-config rows are
+ * never suppressed this way.
  * @param {Array<{alias,model,source}>} sources
  * @param {Array<{id:string}>} catalog
  */
@@ -75,11 +81,24 @@ function findStaleAliases(sources, catalog) {
   const covered = new Set(
     sources.filter(({ model }) => isLive(model) === true).map(({ alias }) => alias)
   );
+  // v4.6.3 PR1 (spec D2). Lazy-required so suites that doMock curated-models
+  // for other cases keep working; a stub without the accessor simply gets no
+  // suppression (fail-open toward reporting).
+  const cm = require('./curated-models');
+  const provenance = typeof cm.directFormProvenance === 'function' ? (cm.directFormProvenance() || {}) : {};
   return sources.filter(({ alias, model, source }) => {
     const ids = byProvider.get(model.split('/')[0]);
     if (!ids) { return false; } // provider unverifiable
     if (ids.has(model)) { return false; } // live
     if (source.startsWith('curated-route') && covered.has(alias)) { return false; }
+    // A 'defaults' pin that is the alias's DERIVED direct form: its absence
+    // from the direct namespace is a routing fact, not staleness, while the
+    // alias has live coverage (or declares gatewayOnly). The fix: suggestion
+    // this row would otherwise print is a retarget nobody should run — the
+    // 2026-08-05 release-gate false positive (v4.6.3 spec §3).
+    const prov = provenance[alias];
+    if (source === 'defaults' && prov && prov.directForm === 'derived' &&
+        (prov.gatewayOnly || covered.has(alias))) { return false; }
     return true;
   });
 }

package/src/utils/cli-preflight.js

@@ -40,4 +40,30 @@ function requireValidTaskId(args, useJson, commandLabel, usage) {
   return taskId;
 }
 
-module.exports = { requireNoUiForJson, requireValidTaskId };
+/**
+ * `pack save --version <semver>` can never work, and used to fail SILENTLY:
+ * `version` is a global BOOLEAN_FLAG (src/cli.js), so parseArgs sets
+ * `args.version = true` and drops the semver into positionals, then
+ * bin/amicus.js prints the version banner BEFORE command dispatch — so
+ * `handlePack` never runs and no pack is written, at exit 0. `--version=2.0.0`
+ * fails identically (the inline value is discarded at the isBooleanFlag branch,
+ * ahead of the --key=value branch). The pack's own version is `--pack-version`.
+ *
+ * Returns the failure rather than exiting, so bin/amicus.js keeps one exit site
+ * and this stays unit-testable (bin/amicus.js is a script, not a module).
+ *
+ * @param {object} args - parsed CLI args
+ * @returns {{code: string, message: string, hint: string}|null} null when there is no conflict
+ */
+function packSaveVersionConflict(args) {
+  if (!args || !args.version) { return null; }
+  const argv = Array.isArray(args._) ? args._ : [];
+  if (argv[0] !== 'pack' || argv[1] !== 'save') { return null; }
+  return {
+    code: ERROR_CODES.BAD_ARGS,
+    message: "Error: --version is amicus's own global flag, not the saved pack's version",
+    hint: 'Use --pack-version <semver> to set the version of the pack being saved.',
+  };
+}
+
+module.exports = { requireNoUiForJson, requireValidTaskId, packSaveVersionConflict };

package/src/utils/config.js

@@ -419,6 +419,21 @@ function getCouncilWithSource(name, catalog = []) {
  * @returns {{models:string[], dropped:string[], droppedMembers:Array<{member:string, reason:string}>}}
  *   `dropped` is the flat member-ref list (unchanged shape, pre-v4.5-Wave-2
  *   callers keep working); `droppedMembers` additively pairs each with WHY.
+ *
+ *   Standing note (D18, v4.7 PR5): each `droppedMembers` entry is `{member, reason}`
+ *   (that is the real key — BACKLOG.md's description of this shape had drifted to
+ *   `{ref, reason}`). The two `reason` literals are produced below, in the
+ *   alias-miss and catalog-miss branches of `classifyCouncilMembers`; they are
+ *   free text, not a coded enum, and today NO consumer branches on the string. They
+ *   are not display-only: `council/presets-cli.js` (`amicus council show`,
+ *   `:149-150`) renders `${member} (${reason})`, `council/run.js` (`:80-87`) carries
+ *   it verbatim into a degrade-note payload, and `reason` is also persisted into
+ *   `run.json` (`run-state.js`, `mcp-council-run.js`) — not merely shown to a human.
+ *   `cli-council-run-bench.js` (`:74`) only type-checks that `reason` is a string
+ *   when round-tripping `--dropped-members` across the MCP→CLI spawn boundary. The
+ *   tripwire: if a THIRD reason string is ever added here, stop and re-decide
+ *   whether `reason` should become a coded enum instead of free text — this note
+ *   marks that decision point, it does not make it.
  */
 function classifyCouncilMembers(members, catalog = []) {
   const aliases = getEffectiveAliases();

package/src/utils/curated-models.js

@@ -68,7 +68,9 @@ const FAMILIES = [
 ];
 
 /**
- * Alias-only entries (no wizard quick pick); openrouter route only.
+ * Alias-only entries (no wizard quick pick). Every entry authors an
+ * openrouter route; entries whose vendor's direct API genuinely serves the
+ * model also author a direct route (claude/sonnet/haiku/fable).
  * Refreshed against the live catalog 2026-08-04.
  */
 const CARDLESS = [
@@ -77,7 +79,12 @@ const CARDLESS = [
   // 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' } },
+  // gatewayOnly (owner ruling 2026-08-05, recorded in the v4.6.3 spec): the
+  // openrouter-only route is a deliberate routing choice — OpenAI's direct
+  // namespace does not serve gpt-5.6-sol-pro, so the DERIVED direct form
+  // must never be audited as stale and no direct pairing may be suggested.
+  { alias: 'gpt-pro', gatewayOnly: true,
+    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',
@@ -86,7 +93,11 @@ const CARDLESS = [
                                 anthropic: 'anthropic/claude-sonnet-5' } },
   { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5',
                               anthropic: 'anthropic/claude-haiku-4-5-20251001' } },
-  { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5' } },
+  // fable: direct route authored 2026-08-05 (owner ruling R2, v4.6.3 spec §3).
+  // Anthropic's /v1/models lists claude-fable-5 AND the direct route serves
+  // (live smoke wave 47278069) — the entry was OpenRouter-only at authoring.
+  { alias: 'fable', routes: { openrouter: 'openrouter/anthropic/claude-fable-5',
+                              anthropic: 'anthropic/claude-fable-5' } },
   { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.7-max' } },
   { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
   { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.6-flash' } },
@@ -160,7 +171,8 @@ function listCuratedRoutes() {
  * Vendors whose direct-API ids differ from OpenRouter's (dot vs. dash
  * versioning, distinct model names, etc.). NEVER derive a direct form for
  * these — derivation would emit the wrong (dot) id, or invent a direct id
- * for a model that is OpenRouter-only today (e.g. fable).
+ * for a model the direct API does not serve (fable was that case until its
+ * direct route was verified and authored, 2026-08-05).
  * Frozen so consumers can only read it (`.has()`) — a frozen Set still
  * supports lookups, it just can't be `.add()`/`.delete()`/`.clear()`-ed.
  */
@@ -200,6 +212,28 @@ function gatewayRoutesFor(vendorPath, obj) {
   return routes;
 }
 
+/**
+ * Per-alias provenance of the `direct` form in toGatewayRoutes(), for the
+ * auditors (alias-audit.js / gateway-route-audit.js): an AUTHORED direct
+ * form absent from its namespace is stale; a DERIVED one is a computed
+ * convenience whose absence is a routing fact, not staleness, while the
+ * authoring openrouter route is live. `gatewayOnly` mirrors an entry's
+ * explicit routing-choice annotation (owner-ruled): suppress derived-form
+ * findings unconditionally and never suggest a direct pairing.
+ * @returns {Object<string, {directForm: 'authored'|'derived'|'none', gatewayOnly: boolean}>}
+ */
+function directFormProvenance() {
+  const out = {};
+  const entryProv = (vendorPath, obj, gatewayOnly) => {
+    const direct = directFormFor(vendorPath, obj);
+    const directForm = !direct ? 'none' : (obj[vendorPath] ? 'authored' : 'derived');
+    return { directForm, gatewayOnly: gatewayOnly === true };
+  };
+  for (const f of FAMILIES) { out[f.alias] = entryProv(f.vendorPath, f.fallback, f.gatewayOnly); }
+  for (const e of CARDLESS) { out[e.alias] = entryProv(vendorOf(e.routes.openrouter), e.routes, e.gatewayOnly); }
+  return out;
+}
+
 /**
  * @returns {Object<string,{direct?: string, openrouter: string}>} alias →
  * per-gateway executable ids. Unlike `toDefaultAliases` (a single pinned
@@ -223,8 +257,9 @@ function toGatewayRoutes() {
  * disagree. It previously string-stripped `openrouter/` itself, which emitted
  * OpenRouter's dot ids for divergent vendors (`anthropic/claude-opus-4.8` —
  * the direct API only serves the dash form) and invented a bare direct id for
- * OpenRouter-only models (`fable`). Both made `amicus doctor` and `amicus
- * models --check` warn about the product's own shipped defaults.
+ * then-OpenRouter-only models (`fable`, direct-authored 2026-08-05). Both made
+ * `amicus doctor` and `amicus models --check` warn about the product's own
+ * shipped defaults.
  */
 function toDefaultAliases() {
   const out = {};
@@ -235,5 +270,6 @@ function toDefaultAliases() {
 }
 
 module.exports = {
-  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes, DIVERGENT_VENDORS
+  getFamilies, toDefaultAliases, toCanonicalDefault, listCuratedRoutes, toGatewayRoutes,
+  directFormProvenance, DIVERGENT_VENDORS
 };

package/src/utils/gateway-route-audit.js

@@ -30,7 +30,7 @@
 
 'use strict';
 
-const { toGatewayRoutes } = require('./curated-models');
+const { toGatewayRoutes, directFormProvenance } = require('./curated-models');
 const { classifyModel } = require('./model-classification');
 const { pairAcrossGateways } = require('./gateway-route-catalog');
 const { isDirectProvider } = require('./provider-registry');
@@ -70,19 +70,32 @@ function isAuthoritative(catalogInfo, id) {
  */
 function auditGatewayRoutes(catalogInfo) {
   const routes = toGatewayRoutes();
+  const provenance = directFormProvenance();
   const findings = [];
 
   for (const [alias, forms] of Object.entries(routes)) {
+    const prov = provenance[alias] || { directForm: 'none', gatewayOnly: false };
     for (const gateway of ['direct', 'openrouter']) {
       const id = forms[gateway];
       if (!id) { continue; }
-      if (classifyModel(id, gateway, catalogInfo) === 'invalid') {
-        findings.push({ alias, gateway, kind: 'stale', model: id });
+      if (classifyModel(id, gateway, catalogInfo) !== 'invalid') { continue; }
+      // v4.6.3 PR1 (spec D2): a DERIVED direct form is a computed convenience,
+      // not an authored claim. Its absence from the direct namespace is a
+      // routing fact — not staleness — while the authoring openrouter route
+      // is live, or when the entry declares gatewayOnly (an owner-ruled
+      // routing choice). An AUTHORED direct form absent from its namespace
+      // reports exactly as before.
+      if (gateway === 'direct' && prov.directForm === 'derived' &&
+          (prov.gatewayOnly ||
+           classifyModel(forms.openrouter, 'openrouter', catalogInfo) === 'valid')) {
+        continue;
       }
+      findings.push({ alias, gateway, kind: 'stale', model: id });
     }
 
     const vendor = vendorOf(forms.openrouter);
     if (!vendor || !isDirectProvider(vendor)) { continue; } // gateway-only vendor: no direct route ever possible
+    if (prov.gatewayOnly) { continue; } // declared routing choice: never suggest a direct pairing
     const token = bareSegment(forms.openrouter, vendor);
     if (!token) { continue; }
     const paired = pairAcrossGateways(vendor, token, catalogInfo); // Task-5 contract: bare segment only