amicus 4.9.7 → 4.10.0

package/src/mcp-council-run.js

@@ -27,21 +27,11 @@ function textResult(text, isError) {
   return result;
 }
 
-/**
- * v4.5 Task 15 (B7/F5): maps amicus_council_run's MCP input keys to the CLI
- * arg-key names applyPackToArgs's knob tables use (pack-resolve.js), so
- * applyPackToMcpInput can reuse those tables unchanged. `template` has no
- * Zod-declared counterpart on this tool (MCP has no template param of its
- * own — template/apply.js's own docblock: "MCP has no template params of its
- * own") — a pack's briefing.template is the ONLY way a template reaches this
- * handler, carried through as a plain (non-schema) `input.template` property
- * consumed by the render step below.
- */
-const COUNCIL_PACK_PARAM_MAP = {
-  models: 'models', council: 'council', chair: 'chair', critic: 'critic', lenses: 'lenses',
-  debate: 'debate', timeoutMinutes: 'timeout', maxCost: 'max-cost', gateway: 'gateway',
-  template: 'template',
-};
+// COUNCIL_PACK_PARAM_MAP lives in its own leaf (P2-R16, the 300-line size
+// gate: this file was at 298 with no room for Task 6's tools/agent block) —
+// re-exported below unchanged so tests/pack/mcp-pack-params.test.js's
+// existing `require('../../src/mcp-council-run')` import keeps working.
+const { COUNCIL_PACK_PARAM_MAP } = require('./mcp-council-pack-map');
 
 /**
  * amicus_council_run: validate → prep run dir → spawn CLI child → return
@@ -131,6 +121,14 @@ async function handleCouncilRunTool(input, project, helpers) {
       (typeof input.maxCost !== 'number' || !Number.isFinite(input.maxCost) || input.maxCost <= 0)) {
     return textResult('maxCost must be a positive number.', true);
   }
+  // Spec 2026-09-11 §4 (P2-R28 supersedes P2-R25): --tools/--agent are refused together, before either is consulted, on every door. Tools that never touch the tree (webfetch, websearch, todowrite) ride through; local tools are refused naming the CLI.
+  const toolsIn = (input.tools === undefined || input.tools === null) ? undefined : (Array.isArray(input.tools) ? input.tools : [String(input.tools)]);
+  const mcpWording = (m) => m.replace(/^--tools:/, 'tools:').replace(/--agent Build/g, 'agent: "Build"').replace(/(?<!run )--tools/g, 'tools').replace(/--agent/g, 'agent'); // C6 (P2-R35): rewrites flag wording EXCEPT inside an actual `council run --tools ...` CLI suggestion (resolveRemoteOnlyTools's local-tool message), which stays literal.
+  const conflict = require('./council/seat-tools').agentToolsConflict(input.agent, toolsIn);
+  if (conflict) { return textResult(mcpWording(conflict), true); }
+  const mt = (toolsIn !== undefined)
+    ? require('./council/seat-tools').resolveRemoteOnlyTools(toolsIn) : { ok: true, ids: [] };
+  if (!mt.ok) { return textResult(mcpWording(mt.message), true); }
 
   const { generateTaskId } = require('./sidecar/start');
   const runId = generateTaskId();
@@ -207,6 +205,10 @@ async function handleCouncilRunTool(input, project, helpers) {
   // v4.9 W5.2: emit-when-'task' — 'review' (the zod-declared default spelled
   // out) never reaches the child's argv; review-run argv stays byte-identical.
   if (input.intent === 'task') { args.push('--intent', 'task'); }
+  // Spec 2026-09-11 §4: remote tools + the Plan|Build override ride to the child as argv (the CLI door and runCouncil validate them again).
+  // Named mutant TOOLSEMITALWAYS: `mt.ids` (an array) is always truthy even when empty — swapping `.length` for a bare `mt.ids` check pushes `--tools ''` on every run; reddens 'absent tools/agent leave the argv byte-identical' in tests/mcp-council-run.test.js.
+  if (mt.ids.length) { args.push('--tools', mt.ids.join(',')); }
+  if (input.agent) { args.push('--agent', input.agent); }
 
   let child;
   try { child = helpers.spawnFn(args, runDir); } catch (err) {

package/src/mcp-server.js

@@ -229,8 +229,8 @@ const HEADLESS_STATUS_REMINDER = '<system-reminder>Preferred: call amicus_wait w
  * v4.5 Task 15 (B7/F5): map amicus_fanout / amicus_start's MCP input keys to
  * the CLI arg-key names applyPackToArgs's knob tables use (pack-resolve.js),
  * so applyPackToMcpInput can reuse those tables unchanged — see
- * src/mcp-council-run.js's COUNCIL_PACK_PARAM_MAP for the sibling map and its
- * fuller docblock. `includeContext` is the one inverted-polarity knob: the
+ * src/mcp-council-pack-map.js's COUNCIL_PACK_PARAM_MAP for the sibling map and
+ * its fuller docblock. `includeContext` is the one inverted-polarity knob: the
  * pack/CLI side is `no-context` (true = drop context), the MCP side is
  * `includeContext` (true = keep context, default true).
  */

package/src/mcp-tools.js

@@ -73,8 +73,8 @@ function getTools() {
       agent: z.enum(['Chat', 'Plan', 'Build']).optional()
         .describe(
           'Agent mode. Chat (interactive default; headless runs auto-convert ' +
-          'to Build): reads auto, writes ask permission. Plan: read-only ' +
-          'analysis. Build: full auto (all operations approved).'
+          'to Build): reads auto, writes ask permission. Plan: analysis without ' +
+          'edits (reads, searches and shell allowed). Build: full auto (all operations approved).'
         ),
       noUi: z.boolean().optional().describe(
         'Run headless without GUI. Default false (opens Electron window).'
@@ -345,7 +345,7 @@ function getTools() {
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
       ),
       agent: z.enum(['Plan', 'Build']).optional().describe(
-        'Agent mode for every leg. Build (default): full tool access. Plan: read-only analysis. Chat is not supported headless.'
+        'Agent mode for every leg. Build (default): full tool access. Plan: analysis without edits (reads, searches and shell allowed). Chat is not supported headless.'
       ),
       thinking: z.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']).optional().describe(
         'Reasoning effort for every leg. Omitted: nothing is sent and each provider\'s own default effort governs. A leg whose model does not declare the level is refused before anything is spent; the other legs run. A leg whose model the engine\'s catalogue does not know in time is sent the level unverified.'
@@ -622,6 +622,17 @@ function getTools() {
         "run.json/verdict.json and kept out of the reliability ledger; 'review' is the " +
         'default and is never stored.'
       ),
+      tools: z.array(z.string().min(1)).max(12).optional().describe(
+        'Tool ids stage-1 seats may use, by the engine\'s own ids (task mode defaults to webfetch, review to none). ' +
+        'Over MCP only tools that never touch the tree (webfetch, websearch, todowrite) can be opted in: the MCP run ' +
+        'directory stays inside the project, and a seat with local tools must not run there — use the CLI with ' +
+        '--out-dir outside the project for read/grep/glob/bash. task, skill, question, invalid, edit, write and ' +
+        'apply_patch are always refused. Cannot be combined with agent.'
+      ),
+      agent: z.enum(['Plan', 'Build']).optional().describe(
+        'Escape hatch: run every leg on the engine\'s own agent instead of the council agents (no tool allowlist). ' +
+        'Cannot be combined with tools.'
+      ),
       ui: z.boolean().optional().describe(
         'Auto-open the Council Workspace window on this run. Default: opens when the client is ' +
         'Claude Code (local), Electron is installed, a display exists, and config workspace.autoOpen is ' +
@@ -742,7 +753,7 @@ Each leg is an ordinary session: read/resume/continue it by taskId.
 | Agent | Reads | Writes | Bash | Use When |
 |-------|-------|--------|------|----------|
 | Chat (interactive default*) | auto | asks | asks | Questions, analysis |
-| Plan | auto | denied | denied | Read-only analysis |
+| Plan | auto | denied | auto | Analysis without edits |
 | Build | auto | auto | auto | Implementation tasks |
 
 * Headless (\`noUi\`) runs auto-convert Chat to Build — Chat would otherwise stall waiting on write/bash approval with no UI to approve it.

package/src/opencode-client.js

@@ -530,6 +530,7 @@ function resolveServerStartTimeoutMs(options = {}, env, platform) {
  * @param {string} [options.agentName] - Agent to set systemPrompt on (default: 'chat')
  * @param {number|null} [options.outputBudget] - #218 PR 3: the per-leg output budget startServer
  *   already read; omitted means buildProviderModels reads config itself
+ * @param {Object<string, object>} [options.agents] - Extra agent configs to register (council seat agents, spec 2026-09-11 §4)
  * @returns {object} Server options ready for createOpencodeServer
  */
 function buildServerOptions(options = {}) {
@@ -655,6 +656,31 @@ function buildServerOptions(options = {}) {
     chat: chatAgent
   };
 
+  // Council seat agents (spec 2026-09-11 §4, PR 2): a per-run map of extra agents
+  // the caller already computed (council/seat-tools.js :: buildCouncilAgents).
+  // Merged AFTER `chat`, and a `chat` key is skipped outright (fix round 1 nit)
+  // so a caller genuinely can never displace the chat registration — without
+  // the skip, `agents: { chat: {...} }` would replace `config.agent.chat`
+  // with a brand-new object, detaching it from the `chatAgent` object the
+  // systemPrompt branch below still mutates by reference; seat-tools.js never
+  // emits a `chat` key, but the guard holds regardless of the caller. Absent,
+  // or not a plain object (arrays rejected too), this block is a no-op and
+  // every non-council server's config is byte-identical to today.
+  //
+  // council #247 round 6 (P2-R53): a council agent REPLACES any pre-existing
+  // same-name entry outright, rather than merging onto it — measured
+  // 2026-09-13 (probe-r6.js) that the old shallow merge below let a
+  // pre-existing entry's `prompt`/`temperature` survive and render on the
+  // seat. Named mutant AGENTMERGE: restoring the spread
+  // (`{ ...(config.agent[name] || {}), ...agentConfig }`) lets `prompt`
+  // survive again.
+  if (options.agents && typeof options.agents === 'object' && !Array.isArray(options.agents)) {
+    for (const [name, agentConfig] of Object.entries(options.agents)) {
+      if (name === 'chat') { continue; }
+      config.agent[name] = { ...agentConfig };
+    }
+  }
+
   // Set system prompt on the target agent's config (hidden from UI).
   // The promptAsync `system` field is rendered as a visible chat message,
   // but agent.prompt is injected as the system instruction invisibly.

package/src/pack/pack-validate.js

@@ -16,7 +16,9 @@ const KINDS = ['council', 'fanout', 'solo'];
 /** Per-kind allowed `options` keys (spec §5.1; solo UI-suppression key per Task 0's verified flag set).
  * v4.5 HOLD-gate decision 2 (final-review F1): `agent`/`thinking`/`summaryLength`
  * are inert on EVERY council surface — handleCouncilRun never reads a pack-filled
- * one, and the engine hardcodes agent 'Plan'/summaryLength 'verbose' regardless.
+ * one; `--agent` (CLI) / the MCP `agent` param are a council run's only agent
+ * setters (spec 2026-09-11 §4, v4.9.8), and summaryLength stays hardcoded
+ * 'verbose' on every council launch regardless of what a pack sets.
  * Dropped from `council` pre-release rather than shipped as dead weight a pack
  * author would reasonably expect to work; a council pack that still sets one now
  * fails save/run validation (PACK_INVALID) like any other unknown option for the

package/src/prompt-builder.js

@@ -234,7 +234,7 @@ ${context}`;
  * Note: Tool restrictions are now handled by OpenCode's native agent framework.
  * The agent parameter passed to OpenCode API controls permissions:
  *   - Build: Full tool access (default)
- *   - Plan: Read-only access
+ *   - Plan: Edits denied; reads, searches and shell allowed (measured, opencode 1.18.15)
  *   - Explore: Read-only subagent
  *   - General: Full-access subagent
  *
@@ -258,7 +258,7 @@ Tool permissions are managed by the OpenCode agent framework based on your agent
 // buildPlanModeEnvironment) have been removed. OpenCode's native agent framework now handles
 // tool permissions based on the agent type:
 //   - Build: Full tool access (default)
-//   - Plan: Read-only access
+//   - Plan: Edits denied; reads, searches and shell allowed
 //   - Explore: Read-only subagent
 //   - General: Full-access subagent
 // See: https://opencode.ai/docs/agents/

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