amicus 4.9.7 → 4.10.0

package/src/sidecar/aliases-review.js

@@ -0,0 +1,298 @@
+/**
+ * @module sidecar/aliases-review
+ * `amicus aliases --review` (#238 §4): a numbered readline picker over the
+ * engine's proposals — no copy-paste anywhere. Accept writes the chosen id and
+ * the encoding decides the state (Q4): the shipped pin → `removeAlias`
+ * (follows); anything else → `addAlias` (pinned). Without a TTY it refuses
+ * loudly (Q2): the list, one reason line, exit 1. The §5 WRITE gate lives
+ * here: accepting a catalog-vouched id needs a fresh catalog (24 h); `follow`
+ * is exempt because it removes a key. Screen text is aliases-review-render.js
+ * and the readline prompt is aliases-review-prompt.js (both split out to hold
+ * the 300-line gate). Every alias/id/key written to the terminal — including
+ * a caught `err.message`, via `collapseExcerpt` (a sentence, not an id) —
+ * rides the house sanitizer first (`utils/text-sanitize.js`, #249 r2 C4).
+ *
+ * Fix round 1: a missing cache reads as its own banner, never a bogus
+ * multi-thousand-day `ageLabel`; an aborted prompt — Ctrl-D/EOF (readline's
+ * `close`) or, IN A RAW-MODE TERMINAL (stdout a TTY), Ctrl-C (readline's own
+ * `SIGINT`, #249 r2 D1) — rejects the pending `ask` with a `REVIEW_ABORTED`
+ * sentinel rather than silently exiting 0 (piped stdout: `terminal` defaults
+ * false, so Ctrl-C is then the ordinary process signal — #249 r2 review
+ * F6/F9); every config write is caught per-call so a failure reports and
+ * re-shows the menu; typing the shipped id into "choose another" follows unconditionally
+ * (Q4's encoding, #249 r2 A1/C2) rather than pinning a redundant copy or
+ * consulting either gate; a taken notable name gets a numeric suffix
+ * (`freeSuffix`), deliberately not `deriveFreeAlias`'s `free-` naming,
+ * which is for free-tier council seeds.
+ * Fix round 2 (#249 r1) gate helpers (§5-gated "choose another", clock-skew
+ * freshness, a throwing `readCache`) live in aliases-review-gate.js.
+ */
+
+'use strict';
+
+const { DEFAULT_MAX_AGE_MS } = require('../utils/model-catalog');
+const { stripGatewayPrefix } = require('../utils/curated-models');
+const { gatedCatalogIds } = require('../utils/alias-proposals');
+const { safeFragment, collapseExcerpt } = require('../utils/text-sanitize');
+const { menuFor, menuLineText, renderScreen, refreshingCatalogLine } = require('./aliases-review-render');
+const { classifyTypedId, notInCatalogLine, notVerifiedLine, staleCatalogBanner } = require('./aliases-review-gate');
+
+/**
+ * Real-CLI collaborators. Requires are lazy/function-scoped (not top-level)
+ * because `aliases.js :: handleAliases` requires THIS module to dispatch
+ * `--review` — a top-level `require('./aliases')` here would be a load-time
+ * cycle.
+ * @returns {object} collaborators for `runReview` when the caller supplies none
+ */
+function defaultDeps() {
+  const base = require('./aliases');
+  const d = base.loadDeps();
+  return {
+    ...d,
+    isTTY: !!process.stdin.isTTY,
+    write: (s) => process.stdout.write(s),
+    stderr: (s) => process.stderr.write(s),
+    collectAliasView: (opts) => base.collectAliasView(opts, d),
+    renderAliasList: (view) => base.renderAliasList(view, d.groupAliases),
+    addAlias: require('./setup').addAlias,
+    removeAlias: require('../utils/alias-store').removeAlias,
+    recordDismissal: require('../utils/alias-store').recordDismissal,
+    effectiveAliasNames: () => new Set(Object.keys(d.config.getEffectiveAliases())),
+    now: () => Date.now(),
+  };
+}
+
+/**
+ * The §5 WRITE gate (mirrors doctor-alias-check.js's unexported
+ * `isCatalogFresh`). R3: `age >= 0` is required too, so a future `fetchedAt`
+ * (clock skew) is explicitly not fresh rather than indefinitely so.
+ * @returns {boolean} true when `fetchedAt` is a number, not in the future, and no older than 24h
+ */
+function isFresh(fetchedAt, now) {
+  return typeof fetchedAt === 'number' && (now - fetchedAt) >= 0 && (now - fetchedAt) <= DEFAULT_MAX_AGE_MS;
+}
+
+/** @returns {boolean} true when two ids name the same model once gateway prefixes are normalized */
+function sameModel(a, b) {
+  return typeof a === 'string' && typeof b === 'string' && stripGatewayPrefix(a) === stripGatewayPrefix(b);
+}
+
+/** @returns {string} `base`, or the first `${base}-2`, `${base}-3`, … not already in `taken` */
+function freeSuffix(base, taken) {
+  if (!taken.has(base)) { return base; }
+  let n = 2;
+  while (taken.has(`${base}-${n}`)) { n += 1; }
+  return `${base}-${n}`;
+}
+
+/**
+ * Accept one candidate. `follow` unpins (`removeAlias` — the encoding IS the
+ * state, Q4); `notable` pins under a numeric-suffixed name when its suggested
+ * alias is already taken; anything else pins the alias straight to the
+ * candidate id. Any write failure is caught here (M2) so the caller can
+ * re-show the menu instead of crashing the review.
+ * @returns {boolean} true on a successful write
+ */
+function acceptCandidate(p, c, d) {
+  try {
+    if (c.why === 'follow') {
+      d.removeAlias(p.alias);
+      d.write(`  ✓ ${safeFragment(p.alias)} now follows the shipped recommendation (${safeFragment(c.id)})\n`);
+      return true;
+    }
+    if (c.why === 'notable') {
+      const name = freeSuffix(p.alias, d.effectiveAliasNames());
+      d.addAlias(name, c.id);
+      d.write(`  ✓ ${safeFragment(name)} → ${safeFragment(c.id)} (pinned)\n`);
+      return true;
+    }
+    d.addAlias(p.alias, c.id);
+    d.write(`  ✓ ${safeFragment(p.alias)} → ${safeFragment(c.id)} (pinned)\n`);
+    return true;
+  } catch (err) {
+    d.write(`  could not write: ${collapseExcerpt(err.message)}\n`);
+    return false;
+  }
+}
+
+/**
+ * The "choose another" sub-flow: a free-text model id. Typing the shipped id
+ * (M3, #249 r2 A1/C2) IS the menu's `follow` action, checked FIRST and exempt
+ * from BOTH gates below, even when the catalog is stale or lacks the shipped
+ * id -- the numbered `follow` item is offered regardless of the catalog.
+ * Anything else is checked against the §5 display gate (R2 — the SAME
+ * `gatedCatalogIds` the menu's own candidates come from) then the freshness
+ * gate; a write failure (M2) is a cancel/refusal.
+ * @returns {Promise<'accepted'|'cancel'|'refused'|'error'>}
+ */
+async function chooseAnother(p, ctx) {
+  const { d, fresh, allCatalogIds, gatedIds, ask } = ctx;
+  for (;;) {
+    const raw = await ask('  model id (provider/model), blank to cancel: ');
+    const ans = String(raw || '').trim();
+    if (!ans) { return 'cancel'; }
+    // Mutant GATEFIRST: move this below the two gates and the R1 tests go red.
+    const follows = !!(p.shipped && sameModel(ans, p.shipped));
+    if (!follows) {
+      const status = classifyTypedId(ans, allCatalogIds, gatedIds);
+      if (status === 'unknown') { d.write(notInCatalogLine(ans)); continue; }
+      if (status === 'ungated') { d.write(notVerifiedLine(ans)); continue; }
+      if (!fresh) {
+        d.write('  cannot accept: the catalog is not fresh (see above)\n');
+        return 'refused';
+      }
+    }
+    try {
+      if (follows) {
+        d.removeAlias(p.alias);
+        d.write(`  ✓ ${safeFragment(p.alias)} now follows the shipped recommendation (${safeFragment(ans)})\n`);
+      } else {
+        d.addAlias(p.alias, ans);
+        d.write(`  ✓ ${safeFragment(p.alias)} → ${safeFragment(ans)} (pinned)\n`);
+      }
+      return 'accepted';
+    } catch (err) {
+      d.write(`  could not write: ${collapseExcerpt(err.message)}\n`);
+      return 'error';
+    }
+  }
+}
+
+/**
+ * Drive one proposal's screen + menu loop until it is accepted, skipped, or
+ * dismissed. A refused accept (stale catalog), a write failure, or a
+ * cancelled/refused "choose another" redisplays this SAME proposal's menu
+ * rather than advancing. A menu answer must be all-digits before it is ever
+ * handed to `Number` (M6).
+ * @returns {Promise<'accepted'|'skipped'|'dismissed'>}
+ */
+async function reviewOne(p, i, n, ctx) {
+  const { d, fresh, ask } = ctx;
+  const items = menuFor(p);
+  d.write(renderScreen(p, i, n, items));
+  for (;;) {
+    const raw = await ask('  > ');
+    const trimmed = String(raw || '').trim();
+    const choice = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+    if (!Number.isInteger(choice) || choice < 1 || choice > items.length) {
+      d.write(`  choose 1-${items.length}\n`);
+      continue;
+    }
+    const item = items[choice - 1];
+    if (item.action === 'skip') { return 'skipped'; }
+    if (item.action === 'dismiss') {
+      try {
+        d.recordDismissal(p.dismissKey);
+        d.write(`  dismissed ${safeFragment(p.dismissKey)}\n`);
+        return 'dismissed';
+      } catch (err) {
+        d.write(`  could not write: ${collapseExcerpt(err.message)}\n`);
+        d.write(menuLineText(items) + '\n');
+        continue;
+      }
+    }
+    if (item.action === 'choose') {
+      const outcome = await chooseAnother(p, ctx);
+      if (outcome === 'accepted') { return 'accepted'; }
+      d.write(menuLineText(items) + '\n'); // 'cancel', 'refused' or 'error': same proposal's menu again
+      continue;
+    }
+    if (!fresh && item.candidate.why !== 'follow') {
+      d.write('  cannot accept: the catalog is not fresh (see above)\n');
+      d.write(menuLineText(items) + '\n');
+      continue;
+    }
+    if (acceptCandidate(p, item.candidate, d)) { return 'accepted'; }
+    d.write(menuLineText(items) + '\n');
+  }
+}
+
+/**
+ * `amicus aliases --review` entry point.
+ * @param {object} args parsed CLI args (the --json/--quiet argument-error
+ *   check happens in aliases.js before this is ever called)
+ * @param {object} [deps] injectable collaborators — see the module docblock;
+ *   defaults to real I/O (readline over stdin/stdout) when omitted
+ * @returns {Promise<number>} 1 when refused for lacking a TTY or interrupted, else 0
+ */
+async function runReview(args, deps) {
+  // F4b: merge (not replace), so a test can inject only the members it cares
+  // about and let every other collaborator run for real against the hermetic
+  // scratch config -- additive, so every existing deps-object test still works.
+  const d = { ...defaultDeps(), ...(deps || {}) };
+  let prompt = null;
+  let ask = d.ask; // M6: kept local, never written back onto `d`
+  try {
+    const isTTY = d.isTTY ?? !!process.stdin.isTTY;
+    if (!isTTY) {
+      const view = await d.collectAliasView({ maxAgeMs: Number.POSITIVE_INFINITY });
+      d.write(d.renderAliasList(view));
+      d.stderr('aliases --review is interactive: run it in a terminal, or use `amicus aliases --json` for machine output\n');
+      return 1;
+    }
+    if (!ask) {
+      // Lazy require, same as `./aliases` above -- but for locality, not a
+      // cycle: aliases-review-prompt.js has no require edge back to this
+      // file, so a top-level require would be equally safe here.
+      const { createPrompt } = require('./aliases-review-prompt');
+      prompt = createPrompt();
+      ask = prompt.ask;
+    }
+    // Minor (spec §4): name the inline refresh wait so it doesn't read as a
+    // hang. R7: a throwing readCache (disk error, corrupt cache) drops this
+    // best-effort banner rather than crashing the review.
+    if (typeof d.readCache === 'function') {
+      try { const line = refreshingCatalogLine(d.readCache(), Date.now()); if (line) { d.write(line); } }
+      catch { /* best-effort banner only */ }
+    }
+    const view = await d.collectAliasView({});
+    // F1: no catalog at all means no proposal was ever judged -- that is not
+    // the same fact as "judged them all, nothing to review" (below), so it
+    // gets its own refusal, before that check ever runs.
+    if (!view.catalogAvailable) {
+      d.write('  no catalog — cannot review; run amicus models --refresh\n');
+      return 1;
+    }
+    const now = (d.now || Date.now)();
+    const fetchedAt = view.catalogInfo && view.catalogInfo.fetchedAt;
+    const fresh = isFresh(fetchedAt, now);
+    const proposals = Array.isArray(view.proposals) ? view.proposals : [];
+    if (proposals.length === 0) {
+      d.write(`  Nothing to review — ${(view.rows || []).length} aliases, all following or up to date.\n`);
+      return 0;
+    }
+    // M5: the stale/no-cache/clock-skew banner only ever prints once there is
+    // something to act on — a "nothing to review" run never mentions the catalog.
+    if (!fresh) { d.write(staleCatalogBanner(fetchedAt, now)); }
+    let accepted = 0;
+    let skipped = 0;
+    let dismissed = 0;
+    // R2: computed once for the whole run (the catalog view is fixed for the
+    // session) so `chooseAnother` never re-derives them per keystroke.
+    const catalogModels = Array.isArray(view.catalogInfo && view.catalogInfo.models) ? view.catalogInfo.models : [];
+    const allCatalogIds = new Set(catalogModels.map(m => m && m.id).filter(Boolean));
+    const gatedIds = new Set(gatedCatalogIds(view.catalogInfo));
+    const ctx = { d, fresh, ask, allCatalogIds, gatedIds };
+    try {
+      for (let i = 0; i < proposals.length; i++) {
+        const outcome = await reviewOne(proposals[i], i, proposals.length, ctx);
+        if (outcome === 'accepted') { accepted++; }
+        else if (outcome === 'dismissed') { dismissed++; }
+        else { skipped++; }
+      }
+    } catch (err) {
+      if (err && err.code === 'REVIEW_ABORTED') {
+        d.write(`  review interrupted — ${accepted} accepted, ${skipped} skipped, ${dismissed} dismissed so far\n`);
+        return 1;
+      }
+      throw err;
+    }
+    const n = proposals.length;
+    d.write(`  Reviewed ${n} proposal${n === 1 ? '' : 's'}: ${accepted} accepted, ${skipped} skipped, ${dismissed} dismissed.\n`);
+    return 0;
+  } finally {
+    if (prompt) { prompt.close(); }
+  }
+}
+
+module.exports = { runReview };

package/src/sidecar/aliases.js

@@ -0,0 +1,279 @@
+/**
+ * @module sidecar/aliases
+ * `amicus aliases` (#238 D4) — the user's alias map as a standing command.
+ *
+ *   amicus aliases            list: following / pinned, grouped by vendor
+ *   amicus aliases --review   picker over every proposal (aliases-review.js)
+ *   amicus aliases --json     versioned document: rows + proposals
+ *
+ * The LIST reads the catalog CACHE at any age and never networks (§5 display
+ * gate); the picker refreshes inline when the cache is stale (write gate).
+ * Every form normalizes the config on entry (D6), best-effort.
+ *
+ * #249 r2 C4: `renderAliasList`'s alias names, ids and vendor-group labels
+ * (an unmapped vendor's label is `titleCaseVendor` of a config VALUE's
+ * segment — still third-party, per review F1), and the typed name in
+ * `handleUnpin`'s messages, are quoted onto a terminal and ride `safeFragment`
+ * (the house sanitizer, `utils/text-sanitize.js`) — the fragment, never the
+ * composed line, per `alias-shadow.js :: formatAliasShadow`'s rule. A caught
+ * `err.message` is a sentence, not an id, so it rides `collapseExcerpt` at
+ * the house default cap instead (the `describeThrown` precedent).
+ */
+
+'use strict';
+
+const { SCHEMA_VERSION } = require('../utils/result-schema-version');
+const { DEFAULT_MAX_AGE_MS } = require('../utils/model-catalog');
+const { stripGatewayPrefix } = require('../utils/curated-models');
+const { safeFragment, collapseExcerpt } = require('../utils/text-sanitize');
+
+/** @returns {object} this module's collaborators, gathered so a caller can override them in tests */
+function loadDeps() {
+  const config = require('../utils/config');
+  return {
+    config,
+    normalizeAliases: require('../utils/alias-state').normalizeAliases,
+    listAliasRows: require('../utils/alias-state').listAliasRows,
+    buildAliasProposals: require('../utils/alias-proposals').buildAliasProposals,
+    readDismissals: require('../utils/alias-store').readDismissals,
+    getCatalogInfo: require('../utils/model-catalog').getCatalogInfo,
+    readCache: require('../utils/model-catalog').readCache,
+    groupAliases: require('../utils/alias-groups').groupAliases,
+  };
+}
+
+/** @returns {boolean} true when an own value of `aliases` is not a non-empty string -- saveConfig's own stripper would remove it */
+function hasStrippableAliasValue(aliases) {
+  return Object.keys(aliases).some(k => typeof aliases[k] !== 'string' || aliases[k].length === 0);
+}
+
+/**
+ * Normalize on entry (D6), best-effort: a read-only config dir never blocks a
+ * listing — the in-memory normalized view is used and the failure announced.
+ * Also fires on a non-string value (#249 r1 R8a): `normalizeAliases` only
+ * drops a value equal to the shipped default, so a garbage value would
+ * otherwise sit on disk forever -- `saveConfig`'s own stripper removes it,
+ * with its own Notice.
+ * @returns {object} the user alias map after normalization
+ */
+function normalizeOnEntry(d) {
+  const cfg = d.config.loadConfig();
+  const defaults = d.config.getDefaultAliases();
+  if (!cfg || !cfg.aliases || typeof cfg.aliases !== 'object') { return {}; }
+  const probe = d.normalizeAliases(cfg.aliases, defaults);
+  if (probe.removed.length > 0 || hasStrippableAliasValue(cfg.aliases)) {
+    try { d.config.saveConfig(cfg); }                              // saveConfig prints the Notices
+    catch (err) { process.stderr.write(`Notice: could not normalize aliases (${collapseExcerpt(err.message)}) — keys left on disk; every alias still resolves to the same id\n`); }
+  }
+  return probe.aliases;
+}
+
+/**
+ * @param {{maxAgeMs?: number}} [opts] `Number.POSITIVE_INFINITY` = cache only
+ * @returns {Promise<{rows: Array, proposals: Array, catalogInfo: object, catalogAvailable: boolean}>}
+ */
+async function collectAliasView(opts = {}, d = loadDeps()) {
+  const userAliases = normalizeOnEntry(d);
+  const defaults = d.config.getDefaultAliases();
+  let catalogInfo = { models: [], fetchedAt: null, providerFailures: [] };
+  try {
+    if (opts.maxAgeMs === Number.POSITIVE_INFINITY) {
+      // Display gate (§5): the LIST never networks, even to fill an empty or
+      // v1 cache — read whatever is on disk, verbatim, with no freshness
+      // check at all. `getCatalogInfo` cannot be reused here: it always
+      // calls `getCatalog`, which refreshes (a real fetch) the moment
+      // `readCache()` returns null, regardless of `maxAgeMs`.
+      const c = d.readCache();
+      catalogInfo = {
+        models: (c && Array.isArray(c.models)) ? c.models : [],
+        fetchedAt: c && typeof c.fetchedAt === 'number' ? c.fetchedAt : null,
+        providerFailures: (c && Array.isArray(c.providerFailures)) ? c.providerFailures : [],
+      };
+    } else {
+      // The picker's default-age path (Task 8): a stale cache refreshes inline.
+      catalogInfo = await d.getCatalogInfo(opts.maxAgeMs === undefined ? {} : { maxAgeMs: opts.maxAgeMs });
+    }
+  } catch (err) { process.stderr.write(`Notice: catalog unavailable (${collapseExcerpt(err.message)}) — no proposals\n`); }
+  const rows = d.listAliasRows(userAliases, defaults);
+  const proposals = d.buildAliasProposals({ userAliases, defaults, catalogInfo, dismissed: d.readDismissals() });
+  return { rows, proposals, catalogInfo, catalogAvailable: (catalogInfo.models || []).length > 0 };
+}
+
+/**
+ * F2: the per-row flag names the SPECIFIC reason a proposal exists, instead
+ * of a blanket "newer available" that was wrong for two of the three kinds —
+ * an ahead-of-shipped pin with no sibling only differs from the shipped pin,
+ * and a stale pin with no catalog match at all is gone from the catalog
+ * outright, neither of which is "newer available".
+ * @param {string[]} reasons a proposal's `reasons` array
+ * @returns {string} the row suffix, or '' when called with no reasons
+ */
+function rowFlag(reasons) {
+  if (!reasons || reasons.length === 0) { return ''; }
+  if (reasons.includes('newer-sibling')) { return '   ⚠ newer available'; }
+  if (reasons.includes('stale')) { return '   ⚠ gone from catalog'; }
+  return '   differs from shipped';
+}
+
+/**
+ * R4 (#249 r1 C1): a pinned curated row that names the shipped model under a
+ * DIFFERENT gateway form gets no proposal at all -- alias-proposals.js's own
+ * `sameModel` already treats it as identical to the shipped pin, so it is
+ * neither stale nor "differing". Without this note it renders identically
+ * to an arbitrary custom pin, losing the fact that it is the shipped
+ * recommendation in a different form. Truthful transparency, not a warning.
+ * @param {{state:string, curated:boolean, id:string, shipped:string|null}} r
+ * @returns {string} the row suffix, or '' when the note does not apply
+ */
+function sameGatewayNote(r) {
+  if (r.state !== 'pinned' || !r.curated || typeof r.id !== 'string' || typeof r.shipped !== 'string') { return ''; }
+  if (r.id === r.shipped) { return ''; }
+  return stripGatewayPrefix(r.id) === stripGatewayPrefix(r.shipped) ? '   same model as shipped, other gateway' : '';
+}
+
+/** @param {{rows: Array, proposals: Array}} view @param {Function} [groupAliases] injectable for tests; defaults to loadDeps().groupAliases so the published `(view) => string` signature works standalone @returns {string} */
+function renderAliasList(view, groupAliases = loadDeps().groupAliases) {
+  const byAlias = new Map(view.rows.map(r => [r.alias, r]));
+  const proposalByAlias = new Map(view.proposals.map(p => [p.alias, p]));
+  const map = { __proto__: null };
+  for (const r of view.rows) { map[r.alias] = r.id; }
+  // #249 r2 C4: width is computed from the SANITIZED name -- a bidi/ANSI
+  // fragment stripped at render time must not skew the column alignment of
+  // every other row's padding.
+  const width = Math.max(6, ...view.rows.map(r => safeFragment(r.alias).length));
+  const lines = [];
+  for (const g of groupAliases(map)) {
+    // F1 (#249 r2 review, C4 residual): for a vendor NOT in ALIAS_VENDOR_LABELS,
+    // `alias-groups.js :: vendorLabel` title-cases the raw vendor segment of a
+    // config VALUE (`aliasVendorOf`) rather than mapping it to house text --
+    // that is still third-party data, unlike the ~30 mapped labels. Sanitized
+    // HERE, not inside `vendorLabel`: that helper also renders into the
+    // Electron setup UI's HTML context (`electron/setup-ui-alias-groups.js`),
+    // out of scope for this terminal-only house rule.
+    lines.push(`  ${safeFragment(g.label)}`);
+    for (const key of g.keys) {
+      const r = byAlias.get(key);
+      const p = proposalByAlias.get(key);
+      const flag = p ? rowFlag(p.reasons) : sameGatewayNote(r);
+      lines.push(`    ${safeFragment(key).padEnd(width)}  → ${safeFragment(r.id).padEnd(44)} ${r.state}${flag}`);
+    }
+  }
+  lines.push('');
+  // F1: an unavailable catalog cannot be checked for updates at all -- that is
+  // a different fact from "checked, nothing found" and must not print the
+  // reassuring "nothing to review" line.
+  if (!view.catalogAvailable) {
+    lines.push('  catalog unavailable — cannot check for updates (amicus models --refresh)');
+    return lines.join('\n') + '\n';
+  }
+  const n = view.proposals.length;
+  lines.push(n === 0
+    ? '  nothing to review — amicus aliases --review'
+    : `  ${n} to review — amicus aliases --review`);
+  // F1: the catalog is available but stale -- name its age so a user who
+  // never runs --review still learns the background refresh isn't keeping up.
+  const fetchedAt = view.catalogInfo && view.catalogInfo.fetchedAt;
+  if (typeof fetchedAt === 'number' && (Date.now() - fetchedAt) > DEFAULT_MAX_AGE_MS) {
+    const days = Math.floor((Date.now() - fetchedAt) / DEFAULT_MAX_AGE_MS);
+    lines.push(`  (catalog is ${days} day${days === 1 ? '' : 's'} old — amicus models --refresh)`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** @returns {object} the `--json` document (fields only ever ADDED within SCHEMA_VERSION) */
+function buildAliasesDoc(view) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'aliases',
+    catalogAvailable: view.catalogAvailable,
+    catalogFetchedAt: view.catalogInfo.fetchedAt || null,
+    aliasCount: view.rows.length,
+    aliases: view.rows,
+    proposalCount: view.proposals.length,
+    proposals: view.proposals,
+  };
+}
+
+/**
+ * `amicus aliases --unpin <name>` (#238 F6, R1): "unpin" and "delete" are one
+ * operation -- remove the key -- whose meaning is decided by whether the
+ * name is curated (D1). The name is trimmed before every use -- for the
+ * `removeAlias` lookup, the `isCurated` check and both success messages --
+ * so a padded name neither crashes nor mis-reports which branch fired
+ * (#249 r1 R1). Blank/whitespace/literal-'null' names are refused here, and
+ * `removeAlias` is called under try/catch so any other throw (its own name
+ * guard included) becomes a clean exit 1, never an uncaught crash.
+ *
+ * R4 (#249 r2 D2): refused BEFORE any write when `name` is also
+ * `config.default` and NOT curated -- deleting it would leave the default
+ * dangling on a key that no longer resolves (`resolveModel` throws), and
+ * silently doing that fails the product principle (never a silent dangling
+ * default) as hard as a crash. Precedent: `cli-handlers-provider.js ::
+ * doRemove` re-points `config.default` when a provider goes away; here the
+ * user is deleting one alias on purpose, so refusing and naming the fix is
+ * the transparent choice instead. A CURATED default is unaffected -- it
+ * keeps resolving from the shipped table after the unpin, same as any other
+ * curated unpin. `config.default` may also be a bare model id rather than
+ * an alias name (`start-helpers.js` resolves either); the guard compares
+ * against the literal `name` argument, so a default that merely happens to
+ * RESOLVE to the same id as this alias is not what it's checking.
+ * @param {*} rawName whatever `args.unpin` parsed to
+ * @returns {number} exit code
+ */
+function handleUnpin(rawName) {
+  const name = typeof rawName === 'string' ? rawName.trim() : '';
+  if (!name || name === 'null') {
+    process.stderr.write('Error: --unpin requires an alias name\n');
+    return 1;
+  }
+  const { removeAlias } = require('../utils/alias-store');
+  const { isCurated } = require('../utils/alias-state');
+  const config = require('../utils/config');
+  const defaults = config.getDefaultAliases();
+  const cfg = config.loadConfig();
+  if (cfg && cfg.default === name && !isCurated(name, defaults)) {
+    process.stderr.write(`Error: '${safeFragment(name)}' is your default model (config.default) — pick another default first (amicus setup)\n`);
+    return 1;
+  }
+  let removed;
+  try {
+    removed = removeAlias(name);
+  } catch (err) {
+    process.stderr.write(`Error: ${collapseExcerpt(err.message)}\n`);
+    return 1;
+  }
+  if (!removed) {
+    process.stderr.write(`Error: '${safeFragment(name)}' is not pinned (see: amicus aliases)\n`);
+    return 1;
+  }
+  process.stdout.write(isCurated(name, defaults)
+    ? `✓ ${safeFragment(name)} now follows the shipped recommendation (${defaults[name]})\n`
+    : `✓ ${safeFragment(name)} removed\n`);
+  return 0;
+}
+
+/** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
+async function handleAliases(args) {
+  if (args.review && (args.json || args.quiet)) {
+    process.stderr.write('Error: --review is interactive; use `amicus aliases --json` for machine output\n');
+    return 1;
+  }
+  if (args.unpin !== undefined) {
+    if (args.review || args.json) {
+      process.stderr.write('Error: --unpin cannot be combined with --review or --json\n');
+      return 1;
+    }
+    return handleUnpin(args.unpin);           // handleUnpin trims/validates (R1): true, 42, '', '  ', 'null' all land the same error
+  }
+  if (args.review) { return require('./aliases-review').runReview(args); }
+  const d = loadDeps();
+  const view = await collectAliasView({ maxAgeMs: Number.POSITIVE_INFINITY }, d);
+  if (args.json) {
+    process.stdout.write(JSON.stringify(buildAliasesDoc(view), null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(renderAliasList(view, d.groupAliases));
+  return 0;
+}
+
+module.exports = { handleAliases, collectAliasView, renderAliasList, buildAliasesDoc, loadDeps };

package/src/sidecar/fanout.js

@@ -46,6 +46,7 @@ const { deriveLegIds } = require('./leg-ids');
  *     to run this wave's legs on. Both or neither. When supplied this wave never
  *     starts a server and never closes one — see the seam comment in step 4.
  *     NOT `client`, which is the client TYPE string on this function.)
+ *   serverAgents? (spec 2026-09-11 §4: agents to register if this wave starts its own server)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -218,7 +219,12 @@ async function runFanout(options) {
     logger.debug('Using external server (shared server mode)', { waveId, url: server.url });
   } else {
     try {
-      ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
+      ({ client, server } = await startOpenCodeServer(mcpServers, {
+        models: validated.serverModels || okLegs.map(l => l.model),
+        // Spec 2026-09-11 §4: a wave that starts its own server still needs the
+        // council agents registered on it. Spread-guarded: byte-identical otherwise.
+        ...(options.serverAgents ? { agents: options.serverAgents } : {}),
+      }));
     } catch (err) {
       writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
       return errorWave(waveId, `Failed to start server: ${err.message}`, waveDir);

package/src/sidecar/heartbeat.js

@@ -0,0 +1,46 @@
+// src/sidecar/heartbeat.js
+'use strict';
+// HEARTBEAT_INTERVAL + createHeartbeat — moved verbatim from session-utils.js
+// (size-gate split, spec 2026-09-11 §4 PR 2: that file was already at the
+// 300-line ceiling before this task's additions). Zero behavior change; both
+// re-exported from session-utils.js's existing module.exports, so no caller
+// (start.js, resume.js, continue.js, fanout.js, index.js, and their tests)
+// needs to change — see tests/sidecar/session-utils.test.js and
+// tests/sidecar/start.test.js, which exercise these through that re-export.
+
+/** Standard heartbeat interval in milliseconds */
+const HEARTBEAT_INTERVAL = 15000;
+
+/**
+ * Create a heartbeat that writes status to stderr periodically.
+ * When sessionDir is provided, includes message count and latest activity.
+ *
+ * @param {number} [interval=HEARTBEAT_INTERVAL] - Interval in milliseconds
+ * @param {string} [sessionDir] - Session directory to read progress from
+ * @returns {{ stop: () => void }}
+ */
+function createHeartbeat(interval = HEARTBEAT_INTERVAL, sessionDir) {
+  const startTime = Date.now();
+  const intervalId = setInterval(() => {
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    const mins = Math.floor(elapsed / 60);
+    const secs = elapsed % 60;
+    const ts = mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
+
+    if (sessionDir) {
+      const { readProgress } = require('./progress');
+      const progress = readProgress(sessionDir);
+      process.stderr.write(`[amicus] ${ts} | ${progress.messages} messages | ${progress.latest}\n`);
+    } else {
+      process.stderr.write(`[amicus] still running... ${ts} elapsed\n`);
+    }
+  }, interval);
+
+  return {
+    stop() {
+      clearInterval(intervalId);
+    }
+  };
+}
+
+module.exports = { HEARTBEAT_INTERVAL, createHeartbeat };