amicus 4.9.8 → 4.10.0

package/src/sidecar/aliases-review-gate.js

@@ -0,0 +1,65 @@
+/**
+ * @module sidecar/aliases-review-gate
+ * Pure §5-gate helpers for `amicus aliases --review` (#249 r1 R2/R3), split
+ * into their own module rather than grown onto aliases-review-render.js (it
+ * was already at five exports) or aliases-review.js (it was already at the
+ * 300-line wall). Every export here takes plain data and returns a string or
+ * a classification — no I/O, no config reads/writes, no `ask`.
+ *
+ * #249 r2 C4: a typed id is user input rendered straight to a terminal, so
+ * both line-builders below quote it through `safeFragment` (the house
+ * sanitizer, `utils/text-sanitize.js`) — the fragment, not the composed
+ * line, per `alias-shadow.js :: formatAliasShadow`'s rule.
+ */
+
+'use strict';
+
+const { ageLabel } = require('./aliases-review-render');
+const { safeFragment } = require('../utils/text-sanitize');
+
+/**
+ * Classifies a typed "choose another" model id against the §5 display gate
+ * (R2): a bare/unknown id is a different failure from a real catalog row the
+ * engine would never have offered — `alias-proposals.js :: gatedCatalogIds`
+ * is the same rule the numbered menu's own candidates are built from, so a
+ * typed id can never bypass it.
+ * @param {string} id
+ * @param {Set<string>} allCatalogIds every id the raw catalog carries
+ * @param {Set<string>} gatedIds ids the §5 display gate allows as a candidate
+ * @returns {'unknown'|'ungated'|'ok'}
+ */
+function classifyTypedId(id, allCatalogIds, gatedIds) {
+  if (!id.includes('/') || !allCatalogIds.has(id)) { return 'unknown'; }
+  if (!gatedIds.has(id)) { return 'ungated'; }
+  return 'ok';
+}
+
+/** @returns {string} the line for an id absent from the catalog entirely */
+function notInCatalogLine(id) {
+  return `  not in the catalog — try: amicus models --search ${safeFragment(id).split('/').pop()}\n`;
+}
+
+/** @returns {string} the line for an id present in the catalog but excluded by the §5 display gate */
+function notVerifiedLine(id) {
+  return `  ${safeFragment(id)} is in the catalog but was not verified this run (floor row or rejected provider) — refresh and try again\n`;
+}
+
+/**
+ * The §5 write-gate banner for a not-fresh catalog (R3). Never called with a
+ * fresh one — callers gate on `isFresh` first. A future `fetchedAt` (clock
+ * skew) gets its own line instead of a negative age reaching `ageLabel`.
+ * @param {number|null} fetchedAt
+ * @param {number} now
+ * @returns {string}
+ */
+function staleCatalogBanner(fetchedAt, now) {
+  if (typeof fetchedAt === 'number' && fetchedAt > now) {
+    return '  catalog timestamp is in the future (clock skew?) — proposals are shown, but accepting is disabled until `amicus models --refresh` succeeds\n';
+  }
+  if (typeof fetchedAt === 'number') {
+    return `  catalog is ${ageLabel(fetchedAt, now)} old and could not be refreshed — proposals are shown, but accepting is disabled until \`amicus models --refresh\` succeeds\n`;
+  }
+  return '  no catalog cache and it could not be fetched — proposals are shown, but accepting is disabled until `amicus models --refresh` succeeds\n';
+}
+
+module.exports = { classifyTypedId, notInCatalogLine, notVerifiedLine, staleCatalogBanner };

package/src/sidecar/aliases-review-prompt.js

@@ -0,0 +1,91 @@
+/**
+ * @module sidecar/aliases-review-prompt
+ * The real-readline prompt for `amicus aliases --review`, split out of
+ * aliases-review.js (#249 r2 D1) once that file hit the 300-line wall —
+ * the same reason aliases-review-render.js and aliases-review-gate.js were
+ * split out before it.
+ *
+ * Ctrl-C and Ctrl-D/EOF, MEASURED (Node 24, `terminal: true` over a
+ * `PassThrough`, `input.write('\x03')`/`'\x04'`, `input.end()`): the two
+ * keystrokes are NOT the same event. Ctrl-D/EOF closes the input stream,
+ * which readline surfaces as its own `'close'` event. Ctrl-C in a raw-mode
+ * terminal is readline's own `'SIGINT'` event — NOT the process `SIGINT`
+ * signal — and with no listener attached, readline's default action is to
+ * pause and then close the interface itself, which is why the pre-existing
+ * `'close'` handler already covered Ctrl-C even before this split (the r2
+ * D1 finding's MECHANISM claim — "Ctrl-C is dead" — was refuted). What
+ * had no real-trigger test was that this depended on an inherited default:
+ * the previous M1 test (aliases-review.test.js) injects an `ask` that
+ * throws, and never drives an actual keystroke through readline. Attaching
+ * `rl.on('SIGINT', () => rl.close())` below makes the abort path OURS —
+ * explicit, and still correct if anything else ever attaches its own
+ * `'SIGINT'` listener to this interface, which would otherwise suppress
+ * readline's default close-on-SIGINT behaviour.
+ *
+ * F3 (#249 r2 review): a Ctrl-C with no `ask` PENDING — e.g. during the
+ * caller's inline catalog refresh, which runs after `createPrompt()` and
+ * before the first `ask()` — closes `rl` with nothing to reject; the next
+ * `ask()` then calls `rl.question` on an already-closed interface, which
+ * throws `ERR_USE_AFTER_CLOSE` instead of ever reaching `'close'`'s reject.
+ * `ask` tracks that window itself (a plain closure flag, not the
+ * undocumented `rl.closed`) and short-circuits to the SAME `REVIEW_ABORTED`
+ * error the pending-ask path builds.
+ */
+
+'use strict';
+
+/** @returns {Error} the one `REVIEW_ABORTED` shape both abort paths in `createPrompt` build. */
+function abortedError() {
+  const err = new Error('aliases --review interrupted');
+  err.code = 'REVIEW_ABORTED';
+  return err;
+}
+
+/**
+ * @param {{input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream, terminal?: boolean}} [opts]
+ *   `terminal` is passed through to `readline.createInterface` only when it
+ *   is a boolean; omitted, readline picks its own default (`output.isTTY`).
+ * @returns {{ask: (q: string) => Promise<string>, close: () => void}}
+ *   `ask` resolves the trimmed answer; on an aborted prompt (Ctrl-C,
+ *   Ctrl-D/EOF, or the input stream ending) it rejects with
+ *   `Error('aliases --review interrupted')`, `code: 'REVIEW_ABORTED'`.
+ *   `close` closes the interface; safe to call with no pending `ask` and
+ *   safe to call more than once (readline's own `close` is idempotent).
+ */
+function createPrompt(opts = {}) {
+  const { input = process.stdin, output = process.stdout, terminal } = opts;
+  const readline = require('readline');
+  const rl = readline.createInterface(
+    typeof terminal === 'boolean' ? { input, output, terminal } : { input, output }
+  );
+  let pendingReject = null;
+  let closed = false; // F3: ours, not the undocumented rl.closed -- see module docblock
+  // Ctrl-D/EOF (or the stream simply ending) closes stdin without ever
+  // invoking the `question` callback -- reject any in-flight `ask` so the
+  // caller's loop ends with a summary instead of hanging or exiting silently.
+  rl.on('close', () => {
+    closed = true;
+    if (pendingReject) {
+      const reject = pendingReject;
+      pendingReject = null;
+      reject(abortedError());
+    }
+  });
+  // See the module docblock: this is readline's own 'SIGINT' event (a
+  // raw-mode-terminal Ctrl-C), not the process signal. Closing here makes
+  // the abort path explicit rather than relying on readline's inherited
+  // default, which only fires when nothing else has claimed this event.
+  rl.on('SIGINT', () => rl.close());
+  const ask = (q) => new Promise((resolve, reject) => {
+    // F3: already closed with no pending ask (see module docblock) -- calling
+    // rl.question here would throw ERR_USE_AFTER_CLOSE instead of ever
+    // reaching the 'close' handler's reject above.
+    if (closed) { reject(abortedError()); return; }
+    pendingReject = reject;
+    rl.question(q, (a) => { pendingReject = null; resolve((a || '').trim()); });
+  });
+  const close = () => rl.close();
+  return { ask, close };
+}
+
+module.exports = { createPrompt };

package/src/sidecar/aliases-review-render.js

@@ -0,0 +1,116 @@
+/**
+ * @module sidecar/aliases-review-render
+ * Pure, side-effect-free screen text for `amicus aliases --review` (#238 §4),
+ * split out of aliases-review.js (fix round 1) to keep that file under the
+ * 300-line gate once the round's robustness fixes landed. Every export here
+ * takes plain data and returns a string — no I/O, no config reads/writes, no
+ * `ask`. `reasonPhrase` is an internal helper (only `renderScreen` calls it)
+ * and is deliberately not exported, keeping this module's surface small.
+ *
+ * #249 r2 C4: every alias name, model id and catalog-sourced note this
+ * module interpolates onto the screen rides `safeFragment` (the house
+ * sanitizer, `utils/text-sanitize.js`) FIRST — the fragment, never the
+ * composed line, per `alias-shadow.js :: formatAliasShadow`'s rule.
+ */
+
+'use strict';
+
+const { DEFAULT_MAX_AGE_MS } = require('../utils/model-catalog');
+const { safeFragment } = require('../utils/text-sanitize');
+
+const LABEL_WIDTH = 11; // 'currently' / 'shipped' / 'proposed', each padded flush with the others
+
+/** @returns {string} the reason phrase shown on the 'proposed' line for one candidate */
+function reasonPhrase(c) {
+  if (c.why === 'newer-sibling') { return 'newer sibling, same tier'; }
+  if (c.why === 'replacement') { return 'replacement (current id is gone from the catalog)'; }
+  if (c.why === 'follow') { return 'the shipped recommendation'; }
+  return safeFragment(c.evidence && c.evidence.note) || 'notable model';
+}
+
+/**
+ * @param {number} fetchedAt must be a number (callers gate on `isFresh`/
+ *   `typeof` first — a missing cache gets its own banner, never this)
+ * @param {number} now
+ * @returns {string} e.g. '3 days' / '1 day' / '5 hours' / '1 hour'
+ */
+function ageLabel(fetchedAt, now) {
+  const ms = now - fetchedAt;
+  const days = Math.floor(ms / DEFAULT_MAX_AGE_MS);
+  if (days >= 1) { return `${days} day${days === 1 ? '' : 's'}`; }
+  const hours = Math.max(1, Math.floor(ms / 3600000));
+  return `${hours} hour${hours === 1 ? '' : 's'}`;
+}
+
+/**
+ * Minor (spec §4): "refreshing catalog (3 days old)…" -- printed BEFORE the
+ * picker's own inline refresh, from the last cache on disk, so a stale-cache
+ * wait reads as progress rather than a hang. Pure: takes the pre-refresh
+ * `readCache()` doc and `now`, returns the line or null.
+ * @param {{fetchedAt?: number}|null} cache
+ * @param {number} now
+ * @returns {string|null} the line (with trailing newline), or null when the
+ *   cache is missing or not old enough to be worth naming
+ */
+function refreshingCatalogLine(cache, now) {
+  if (!cache || typeof cache.fetchedAt !== 'number' || (now - cache.fetchedAt) <= DEFAULT_MAX_AGE_MS) { return null; }
+  return `  refreshing catalog (${ageLabel(cache.fetchedAt, now)} old)…\n`;
+}
+
+/**
+ * @param {object} p one proposal
+ * @returns {Array<{label: string, action: 'accept'|'choose'|'skip'|'dismiss', candidate?: object}>}
+ *   one entry per candidate in the engine's order (never re-sorted), then the
+ *   three standing options
+ */
+function menuFor(p) {
+  const alias = safeFragment(p.alias);
+  const items = p.candidates.map(c => {
+    const id = safeFragment(c.id);
+    return {
+      label: c.why === 'follow' ? `follow the shipped pin (${id})` : (c.why === 'notable' ? `add ${alias} → ${id}` : `accept ${id}`),
+      action: 'accept',
+      candidate: c,
+    };
+  });
+  items.push({ label: 'choose another', action: 'choose' });
+  items.push({ label: 'skip', action: 'skip' });
+  items.push({ label: 'never ask again', action: 'dismiss' });
+  return items;
+}
+
+/** @param {Array} items from `menuFor` @returns {string} the numbered menu line alone, no trailing newline */
+function menuLineText(items) {
+  return '    ' + items.map((it, idx) => `[${idx + 1}] ${it.label}`).join('   ');
+}
+
+/**
+ * @param {object} p one proposal
+ * @param {number} i zero-based index
+ * @param {number} n total proposal count
+ * @param {Array} items from `menuFor`
+ * @returns {string} the full screen for one proposal — header, state block and menu — trailing newline included
+ */
+function renderScreen(p, i, n, items) {
+  const lines = [`  [${i + 1}/${n}] ${safeFragment(p.alias)}`];
+  lines.push(p.current
+    ? `    ${'currently'.padEnd(LABEL_WIDTH)}${safeFragment(p.current)}      (pinned)`
+    : '    not mapped yet');
+  if (p.curated) { lines.push(`    ${'shipped'.padEnd(LABEL_WIDTH)}${safeFragment(p.shipped)}`); }
+  const top = p.candidates[0];
+  if (top) {
+    lines.push(`    ${'proposed'.padEnd(LABEL_WIDTH)}${safeFragment(top.id)}   ${reasonPhrase(top)}`);
+  } else if ((p.reasons || []).includes('stale')) {
+    // F3: a stale pin with no same-vendor replacement and no sibling still
+    // has something to say -- silently showing no reason at all read as the
+    // engine finding nothing wrong, when what happened is the opposite.
+    lines.push(`    ${'stale'.padEnd(LABEL_WIDTH)}current id is gone from the catalog — no same-vendor replacement found`);
+  } else {
+    lines.push(`    ${'reason'.padEnd(LABEL_WIDTH)}${(p.reasons || []).join(', ')}`);
+  }
+  lines.push('');
+  lines.push(menuLineText(items));
+  return lines.join('\n') + '\n';
+}
+
+module.exports = { ageLabel, menuFor, menuLineText, renderScreen, refreshingCatalogLine };

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 };