amicus 4.4.1 → 4.5.1

package/skills/second-opinion/SKILL.md

@@ -211,6 +211,11 @@ mangled alias (instant arg-parse failure). For a free council, swap `--models "<
 `--council free`. Run it in the background (`run_in_background: true`); you are notified on
 completion — do not poll.
 
+**Saved run configs (v4.5).** Every flag above this line can also come from a saved
+[policy pack](../../docs/usage.md#policy-packs) — `--pack <name>` loads its bench/chair/critic/
+lenses/options/template as defaults (an explicit flag still overrides it), the same on the
+`amicus_council_run`/`amicus_fanout`/`amicus_start` MCP tools' `pack` param.
+
 **Budget gate — one flag for the whole run.** By default the gate refuses any leg whose price
 exceeds the per-$/Mtok threshold (the o3/o3-pro guard). To run an intentionally expensive model the
 user asked for by name, pass `--no-cost-gate`; to raise only the total ceiling, pass

package/src/cli-handlers-council-run.js

@@ -71,9 +71,11 @@ function resolveBench(args, useJson) {
     if (expanded.dropped && expanded.dropped.length && !useJson) {
       process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
     }
-    return { bench: expanded.models, presetName };
+    // v4.5 Wave 2: threaded into runCouncil's options — the ONLY prior signal
+    // was the stderr-only Notice above, which --json mode never even prints.
+    return { bench: expanded.models, presetName, droppedMembers: expanded.droppedMembers || [] };
   }
-  return { bench: parseList(args.models), presetName: null };
+  return { bench: parseList(args.models), presetName: null, droppedMembers: [] };
 }
 
 function renderRunHuman(run) {
@@ -115,6 +117,27 @@ function renderRunHuman(run) {
 async function handleCouncilRun(args) {
   const useJson = !!args.json;
 
+  // v4.5 Task 12 (B7/F5): resolve --pack FIRST, above the Task-5 template
+  // block, so a pack-filled args.template renders through that single
+  // existing application point exactly like a typed --template.
+  let packRecord = null;
+  const explicitKeys = args.__explicit || new Set();
+  if (args.pack !== undefined) {
+    const { applyPackToArgs } = require('./pack/pack-resolve');
+    const pr = applyPackToArgs({
+      packRef: args.pack, expectedKind: 'council', args,
+      explicit: explicitKeys, useJson,
+    });
+    if (pr.error) { return failJson(useJson, pr.error); }
+    for (const n of pr.notices) { process.stderr.write(n + '\n'); }
+    packRecord = pr.packRecord;
+  }
+  // 2026-07-28 ruling (Task-11 review): attribute a pre-flight failure to the
+  // pack that supplied the failing value — ONLY when the pack filled it (an
+  // explicit flag always wins and is never "blamed" on the pack).
+  const packSuffix = (key) => (packRecord && args[key] !== undefined && !explicitKeys.has(key))
+    ? ` (set by pack '${packRecord.name}')` : '';
+
   // --prompt-file required; inline --prompt rejected (councils always have
   // real briefings — same rationale as MCP fanout's briefing-via-file).
   if (args.prompt !== undefined) {
@@ -123,9 +146,26 @@ async function handleCouncilRun(args) {
       hint: 'write the briefing to a file and pass --prompt-file <path>' });
   }
   const { resolvePromptSource } = require('./utils/prompt-source');
-  const promptRes = resolvePromptSource(args);
-  if (promptRes.error) {
-    return failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error });
+  // F9 (v4.5): with --template and no {{prompt}} slot, --prompt-file may be
+  // absent (mirrors handleFanout's guard); byte-identical without --template.
+  let promptRes;
+  if (args.prompt !== undefined || args['prompt-file'] !== undefined || args.template === undefined) {
+    promptRes = resolvePromptSource(args);
+    if (promptRes.error) { return failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error }); }
+  } else {
+    promptRes = { prompt: undefined, promptMeta: null };
+  }
+  let templateMeta = null;
+  if (args.template !== undefined) {
+    const { applyTemplate } = require('./template/apply');
+    const t = applyTemplate({ templateRef: args.template, prompt: promptRes.prompt,
+      artifactFile: args.artifact, varList: args.var, project: args.cwd || process.cwd() });
+    if (t.error) { return failJson(useJson, t.error); }
+    for (const n of t.notices) { process.stderr.write(n + '\n'); }
+    promptRes = { prompt: t.prompt, promptMeta: t.promptMeta };
+    templateMeta = t.promptMeta.template;
+  } else if (args.artifact !== undefined || args.var !== undefined) {
+    return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --artifact/--var require --template (expansion happens only in template files)' });
   }
 
   const benchRes = resolveBench(args, useJson);
@@ -153,19 +193,19 @@ async function handleCouncilRun(args) {
     ? args.chair.trim() : CHAIR_DEFAULT;
   if (bench.includes(chair)) {
     return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-      message: `Error: chair '${chair}' is a bench seat — the chair must not review`,
+      message: `Error: chair '${chair}' is a bench seat — the chair must not review${packSuffix('chair')}`,
       hint: `pick a chair outside --models (default: ${CHAIR_DEFAULT}), or remove '${chair}' from the bench` });
   }
   const critic = (typeof args.critic === 'string' && args.critic.trim()) ? args.critic.trim() : null;
   if (critic && !bench.includes(critic)) {
     return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-      message: `Error: critic '${critic}' must be one of the bench seats`,
+      message: `Error: critic '${critic}' must be one of the bench seats${packSuffix('critic')}`,
       hint: `--critic swaps one seat's brief; pass one of: ${bench.join(', ')}` });
   }
   const lenses = (typeof args.lenses === 'string' && args.lenses.trim()) ? parseList(args.lenses) : null;
   if (critic && lenses) {
     return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
-      message: 'Error: --critic and --lenses are mutually exclusive in v4.0' });
+      message: `Error: --critic and --lenses are mutually exclusive in v4.0${packSuffix('critic') || packSuffix('lenses')}` });
   }
   if (lenses && lenses.length !== bench.length) {
     return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
@@ -211,6 +251,9 @@ async function handleCouncilRun(args) {
     noValidateModel: !!args['no-validate-model'],
     date: new Date().toISOString().slice(0, 10),
     councilName,
+    template: templateMeta, // F9 (v4.5): null when no --template; additive on the run.json seed (run-state.js).
+    pack: packRecord, // v4.5 Task 12 (B7/F5): null when no --pack; additive on the run.json seed (run-state.js).
+    droppedMembers: benchRes.droppedMembers, // v4.5 Wave 2: [] when nothing dropped; additive on the run.json seed (run-state.js).
     // v4.1 §4.5b/§4.5d. `--claude-review` is resolved here but VALIDATED by the
     // engine's preflightClaudeReview (run-assemble.js): the reserved-seat and
     // 'claude may not chair' guards live there on purpose so MCP, the GitHub

package/src/cli-handlers-doctor.js

@@ -7,6 +7,8 @@ const mcpChecks = require('./utils/doctor-mcp-checks');
 // engine-mcp check body — verifies the engine in the npx-cache copies the MCP
 // actually launches (bug report #1). Split out to keep this file under the gate.
 const engineCheck = require('./utils/doctor-engine-check');
+// electron-mcp check body (#76) — same blind spot, electron-flavored.
+const electronMcpCheck = require('./utils/doctor-electron-mcp-check');
 // local-providers check body (v4.2 §4.7 C8) — split out to keep this file
 // under the gate (mirrors the engineCheck/mcpChecks split above).
 const localProvidersCheck = require('./utils/doctor-local-providers-check');
@@ -47,6 +49,8 @@ function realDeps() {
     scanEngineInstalls: () => require('./utils/engine-install-scan').scanEngineInstalls(),
     // report #2: copy-from-sibling self-heal for `doctor --fix`.
     repairEngine: (o) => require('./utils/engine-repair').repairEngine(o),
+    // electron-mcp check (#76): same enumeration, electron probed per copy.
+    scanElectronInstalls: () => electronMcpCheck.scanElectronInstalls(),
     getElectronPath: () => require('./sidecar/interactive-process').getElectronPath(),
     // #56: self-heal primitive for `doctor --fix`. Pure probe (getElectronPath)
     // stays separate; repair only runs when fix is requested.
@@ -161,6 +165,12 @@ async function runDoctorChecks(depsOverride = {}) {
   // install) can't hide a broken copy the MCP would spawn (bug report #1/#4).
   checks.push(await guardAsync('engine-mcp', 'OpenCode engine (MCP launch path)', () => engineCheck.evaluateEngineMcp(d)));
 
+  // #76: same green-while-broken blind spot for Electron — probe the npx-cache
+  // copies `ui: true` actually depends on. fixTimeoutMs forwards the #56
+  // never-hang guard to the per-copy repairElectron calls.
+  checks.push(await guardAsync('electron-mcp', 'Electron (MCP launch path)',
+    () => electronMcpCheck.evaluateElectronMcp({ ...d, fixTimeoutMs: FIX_TIMEOUT_MS })));
+
   checks.push(await guardAsync('electron', 'Electron (interactive GUI)', async () => {
     if (d.getElectronPath()) {
       return { id: 'electron', name: 'Electron (interactive GUI)', status: 'ok', message: 'installed', hint: null };

package/src/cli-handlers-pack.js

@@ -0,0 +1,238 @@
+// src/cli-handlers-pack.js
+'use strict';
+
+/**
+ * @module cli-handlers-pack
+ * F5/B7 (v4.5), Task 14: `amicus pack save|list|show|rm` + `--from-run`. The
+ * user-facing management CLI on top of the pack subsystem built by Tasks 7-13
+ * (pack-store, pack-validate, pack-resolve, --pack on the three run commands).
+ * Idiom donor: src/cli-handlers-template.js (doc object -> useJson ?
+ * JSON.stringify : render) and src/council/presets-cli.js (list/show render
+ * shape, `amicus council show`'s diagnostic-mirror style for `pack show`).
+ *
+ * `pack save <name> --from-run <id>` builds a pack from an existing council
+ * run / fanout wave / solo session instead of flags (buildPackFromRun below).
+ * Resolution order: council pointer (run-state.js) -> wave metadata.json ->
+ * solo metadata.json. Briefing TEXT is never captured, only a template
+ * reference when the source run recorded one.
+ */
+
+const { SCHEMA_VERSION } = require('./utils/result-schema');
+const { ERROR_CODES, failJson } = require('./utils/error-doc');
+
+/** Build a pack object from `pack save <name> --kind ... <flags>`. */
+function buildPackFromFlags(name, args) {
+  const kind = args.kind;
+  const pack = { schemaVersion: 1, type: 'pack', name, version: args.version || '1.0.0', kind };
+  if (args.description) { pack.description = String(args.description); }
+  if (kind === 'solo') { pack.model = args.model; }
+  else if (typeof args.bench === 'string') {
+    // A comma present means an explicit member list; a single comma-less
+    // value is a council/bench NAME string (validatePack {mode:'save'} is
+    // the net that catches an unresolvable one of either form).
+    pack.bench = args.bench.includes(',')
+      ? args.bench.split(',').map((s) => s.trim()).filter(Boolean)
+      : args.bench.trim();
+  }
+  if (kind === 'council') {
+    if (args.chair) { pack.chair = args.chair; }
+    if (args.critic) { pack.critic = args.critic; }
+    if (typeof args.lenses === 'string') { pack.lenses = args.lenses.split(',').map((s) => s.trim()).filter(Boolean); }
+  }
+  const opts = {};
+  if (args.__explicit.has('timeout')) { opts.timeout = args.timeout; }
+  if (args['max-cost'] !== undefined) { opts.maxCost = args['max-cost']; }
+  if (args.gateway) { opts.gateway = args.gateway; }
+  if (args.agent) { opts.agent = args.agent; }
+  if (args.thinking) { opts.thinking = args.thinking; }
+  if (args.__explicit.has('summary-length')) { opts.summaryLength = args['summary-length']; }
+  // Task-10 ruling (pack-resolve.js:116): a negatable boolean's "was this
+  // explicit" check must test BOTH forms, since __explicit only records the
+  // literal typed key (--no-debate never sets args.debate to anything).
+  if (args.__explicit.has('debate') || args.__explicit.has('no-debate')) { opts.debate = !!args.debate; }
+  if (Object.keys(opts).length) { pack.options = opts; }
+  if (args.template) { pack.briefing = { template: String(args.template) }; }
+  return pack;
+}
+
+/** council branch of buildPackFromRun: a run.json reached via the council pointer. */
+function packFromCouncilRun(name, version, run) {
+  const opts = {};
+  if (run.options && run.options.timeout) { opts.timeout = run.options.timeout; }
+  if (run.options && run.options.maxCost !== undefined && run.options.maxCost !== null) { opts.maxCost = run.options.maxCost; }
+  if (run.options && run.options.gateway) { opts.gateway = run.options.gateway; }
+  if (run.debate && run.debate.enabled) { opts.debate = true; }
+  return {
+    schemaVersion: 1, type: 'pack', name, version, kind: 'council',
+    bench: run.bench.slice(), chair: run.chair,
+    ...(run.critic ? { critic: run.critic } : {}),
+    ...(run.lenses ? { lenses: run.lenses.slice() } : {}),
+    ...(Object.keys(opts).length ? { options: opts } : {}),
+    ...(run.template ? { briefing: { template: run.template.name } } : {}),
+  };
+}
+
+/** wave branch: a fanout wave's metadata.json (type:'wave'), plus its first leg. */
+function packFromWave(name, version, project, meta) {
+  const fs = require('fs');
+  const path = require('path');
+  const { getSessionDir } = require('./session-manager');
+
+  const opts = {};
+  const firstLeg = Array.isArray(meta.legs) ? meta.legs[0] : null;
+  if (firstLeg) {
+    try {
+      const legMeta = JSON.parse(fs.readFileSync(path.join(getSessionDir(project, firstLeg), 'metadata.json'), 'utf-8'));
+      if (legMeta.agent) { opts.agent = legMeta.agent; }
+      if (legMeta.thinking) { opts.thinking = legMeta.thinking; }
+    } catch { /* leg metadata unreadable/absent — omit, never null-stuff */ }
+  }
+  return {
+    schemaVersion: 1, type: 'pack', name, version, kind: 'fanout',
+    bench: meta.models.slice(),
+    ...(Object.keys(opts).length ? { options: opts } : {}),
+    ...(meta.promptMeta && meta.promptMeta.template ? { briefing: { template: meta.promptMeta.template.name } } : {}),
+  };
+}
+
+/** solo branch: an ordinary (non-wave) session's metadata.json. */
+function packFromSolo(name, version, meta) {
+  const opts = {};
+  if (meta.agent) { opts.agent = meta.agent; }
+  if (meta.thinking) { opts.thinking = meta.thinking; }
+  return {
+    schemaVersion: 1, type: 'pack', name, version, kind: 'solo',
+    model: meta.model,
+    ...(Object.keys(opts).length ? { options: opts } : {}),
+  };
+}
+
+/**
+ * Build a pack object from `pack save <name> --from-run <id>`. Resolution
+ * order: council pointer/run.json -> wave metadata.json -> solo metadata.json.
+ * @returns {object} a pack object, or `{error: string}` when `id` resolves to nothing.
+ */
+function buildPackFromRun(name, id, project, args) {
+  const runState = require('./council/run-state');
+  const version = args.version || '1.0.0';
+
+  const ptr = runState.readPointer(project, id); // {runId, runDir}|null (run-state.js:156)
+  const run = ptr ? runState.readRun(ptr.runDir) : null;
+  let pack;
+  if (run && run.type === 'council-run') {
+    pack = packFromCouncilRun(name, version, run);
+  } else {
+    const fs = require('fs');
+    const path = require('path');
+    const { getSessionDir } = require('./session-manager');
+    let meta = null;
+    try { meta = JSON.parse(fs.readFileSync(path.join(getSessionDir(project, id), 'metadata.json'), 'utf-8')); }
+    catch { return { error: `Session ${id} not found` }; }
+    pack = meta.type === 'wave' ? packFromWave(name, version, project, meta) : packFromSolo(name, version, meta);
+  }
+  // T14-m4 (final-review): buildPackFromFlags honors --description (line ~27
+  // above); this --from-run path threaded `version` the same way but silently
+  // dropped --description. Honor it here too, regardless of which branch
+  // (council/wave/solo) produced the pack.
+  if (args.description) { pack.description = String(args.description); }
+  return pack;
+}
+
+function renderPackList(doc) {
+  let text = '';
+  if (doc.packs.length === 0) {
+    text = 'No packs.\n';
+  } else {
+    const lines = doc.packs.map((p) => {
+      const name = String(p.name || '(unnamed)').padEnd(20);
+      const kind = String(p.kind || '(unknown)');
+      const version = String(p.version || '0.0.0');
+      const desc = p.description ? ` — ${p.description}` : '';
+      return `  ${name} [${kind}] v${version}${desc}`;
+    });
+    text = 'Packs:\n' + lines.join('\n') + '\n';
+  }
+  for (const w of doc.warnings) { text += `Warning: ${w}\n`; }
+  return text;
+}
+
+function renderPackShow(doc) {
+  const { pack, path: file, source, hash, validation } = doc;
+  const lines = [`Pack '${pack.name}' v${pack.version} [${pack.kind}] (${source}: ${file})`, `  hash: ${hash}`];
+  if (pack.description) { lines.push(`  description: ${pack.description}`); }
+  if (pack.kind === 'solo') { lines.push(`  model: ${pack.model}`); }
+  else { lines.push(`  bench: ${Array.isArray(pack.bench) ? pack.bench.join(', ') : pack.bench}`); }
+  if (pack.chair) { lines.push(`  chair: ${pack.chair}`); }
+  if (pack.critic) { lines.push(`  critic: ${pack.critic}`); }
+  if (pack.lenses) { lines.push(`  lenses: ${pack.lenses.join(', ')}`); }
+  if (pack.options && Object.keys(pack.options).length) { lines.push(`  options: ${JSON.stringify(pack.options)}`); }
+  if (pack.briefing && pack.briefing.template) { lines.push(`  briefing.template: ${pack.briefing.template}`); }
+  lines.push(validation.ok ? '  validation: ok' : `  validation: INVALID — ${validation.errors.join('; ')}`);
+  if (validation.ok && validation.warnings.length) { lines.push(`  warnings: ${validation.warnings.join('; ')}`); }
+  return lines.join('\n') + '\n';
+}
+
+/** @param {object} args parsed CLI args @returns {Promise<number>} exit code */
+async function handlePack(args) {
+  const useJson = !!args.json;
+  const sub = args._[1];
+  const { readPack, writePack, listPacks, rmPack, packsDir } = require('./pack/pack-store');
+  const { validatePack } = require('./pack/pack-validate');
+
+  if (sub === 'save') {
+    const name = args._[2];
+    if (!name) { return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pack save needs a <name>' }); }
+    const pack = args['from-run']
+      ? buildPackFromRun(name, String(args['from-run']), args.cwd || process.cwd(), args)
+      : buildPackFromFlags(name, args);
+    if (pack.error) { return failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: `Error: ${pack.error}` }); }
+    const v = validatePack(pack, { mode: 'save' });
+    if (!v.ok) { return failJson(useJson, { code: ERROR_CODES.PACK_INVALID, message: `Error: invalid pack: ${v.errors.join('; ')}` }); }
+    for (const w of v.warnings) { process.stderr.write(`Warning: ${w}\n`); }
+    const res = writePack(pack);
+    const doc = { schemaVersion: SCHEMA_VERSION, type: 'pack-save', name, ...res };
+    process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n'
+      : (res.noop ? `Pack '${name}' unchanged (no-op).\n`
+        : `Saved pack '${name}' v${res.version}${res.bumped ? ' (version auto-bumped)' : ''} → ${res.path}\n`));
+    return 0;
+  }
+
+  if (sub === 'list') {
+    const { packs, warnings } = listPacks();
+    const doc = { schemaVersion: SCHEMA_VERSION, type: 'pack-list', dir: packsDir(), packs, warnings };
+    process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderPackList(doc));
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const ref = args._[2];
+    if (!ref) { return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pack show needs a <name|path>' }); }
+    const r = readPack(ref);
+    if (r.error) { return failJson(useJson, { code: ERROR_CODES.PACK_NOT_FOUND, message: r.error, hint: 'amicus pack list' }); }
+    // {mode:'save'} semantics per spec §5.3: reports, never fails — the
+    // `council show` diagnostic mirror. Run-time-only checks (e.g. an
+    // unresolvable briefing.template) are demoted to a warning in this mode.
+    const validation = validatePack(r.pack, { mode: 'save' });
+    const doc = { schemaVersion: SCHEMA_VERSION, type: 'pack-show', ...r, validation };
+    process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : renderPackShow(doc));
+    return 0;
+  }
+
+  if (sub === 'rm') {
+    const name = args._[2];
+    if (!name) { return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pack rm needs a <name>' }); }
+    const res = rmPack(name);
+    // v4.5 HOLD-gate decision 3: unified with `pack show`'s missing-pack code
+    // (same hint idiom) — was BAD_ARGS, so a script switching on error.code got
+    // two different answers for the identical "no such pack" condition.
+    if (!res.removed) { return failJson(useJson, { code: ERROR_CODES.PACK_NOT_FOUND, message: `Error: pack '${name}' not found`, hint: 'amicus pack list' }); }
+    const doc = { schemaVersion: SCHEMA_VERSION, type: 'pack-rm', name, removed: true };
+    process.stdout.write(useJson ? JSON.stringify(doc, null, 2) + '\n' : `Removed pack '${name}'.\n`);
+    return 0;
+  }
+
+  return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+    message: `Error: unknown pack subcommand '${sub || ''}'`, hint: 'amicus pack save|list|show|rm' });
+}
+
+module.exports = { handlePack };

package/src/cli-handlers-run.js

@@ -25,18 +25,29 @@ const { GATEWAY_MODES } = require('./utils/model-descriptor');
  */
 async function handleStart(args) {
   const useJson = !!args.json;
-
+  const packRecord = require('./pack/pack-cli').applyPackOrExit(args, 'solo', useJson);
   // F4: --prompt-file support (XOR --prompt) and --json gating
+  // F9 (v4.5): --template renders {{prompt}}/{{artifact}}/{{var.*}} into the prompt; byte-identical without it.
+  let templateMeta = null;
   if (args.prompt !== undefined || args['prompt-file'] !== undefined) {
     const { resolvePromptSource } = require('./utils/prompt-source');
     const promptRes = resolvePromptSource(args);
     if (promptRes.error) { process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error })); }
     args.prompt = promptRes.prompt;
-    // Drop --prompt-file now that it's resolved: validateStartArgs' self-contained
-    // guard would otherwise re-run resolvePromptSource with both prompt and
-    // prompt-file set and trip its mutually-exclusive branch.
+    // Drop --prompt-file post-resolve or validateStartArgs re-trips its XOR guard.
     delete args['prompt-file'];
   }
+  if (args.template !== undefined) {
+    const { applyTemplate } = require('./template/apply');
+    const t = applyTemplate({ templateRef: args.template, prompt: args.prompt,
+      artifactFile: args.artifact, varList: args.var, project: args.cwd || process.cwd() });
+    if (t.error) { process.exit(failJson(useJson, t.error)); }
+    for (const n of t.notices) { process.stderr.write(n + '\n'); }
+    args.prompt = t.prompt;
+    templateMeta = t.promptMeta.template;
+  } else if (args.artifact !== undefined || args.var !== undefined) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --artifact/--var require --template (expansion happens only in template files)' }));
+  }
   requireNoUiForJson(args, useJson);
 
   const mc = args['max-cost'];
@@ -105,6 +116,8 @@ async function handleStart(args) {
     position: args.position,
     json: !!args.json,
     modelInput: alias || null,
+    template: templateMeta, // F9 (v4.5): startSidecar ignores unknown keys; inert until a future task reads it.
+    pack: packRecord, // v4.5 Task 13: null when no --pack; additively recorded on solo session metadata.
   });
 }
 
@@ -130,6 +143,7 @@ async function handleFanout(args) {
     if (errorDoc && useJson) { process.stdout.write(JSON.stringify(errorDoc) + '\n'); }
     return exitCode;
   }
+  const packRecord = require('./pack/pack-cli').applyPackOrExit(args, 'fanout', useJson);
 
   // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
   // --gateway via validateStartArgs (cli.js) — fanout never did, so a typo'd
@@ -140,9 +154,22 @@ async function handleFanout(args) {
   }
 
   const { resolvePromptSource } = require('./utils/prompt-source');
-  const promptRes = resolvePromptSource(args);
-  if (promptRes.error) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error }));
+  let promptRes;
+  if (args.prompt !== undefined || args['prompt-file'] !== undefined || args.template === undefined) {
+    promptRes = resolvePromptSource(args);
+    if (promptRes.error) { process.exit(failJson(useJson, { code: ERROR_CODES.MISSING_PROMPT, message: promptRes.error })); }
+  } else {
+    promptRes = { prompt: undefined, promptMeta: null };
+  }
+  if (args.template !== undefined) {
+    const { applyTemplate } = require('./template/apply');
+    const t = applyTemplate({ templateRef: args.template, prompt: promptRes.prompt,
+      artifactFile: args.artifact, varList: args.var, project: args.cwd || process.cwd() });
+    if (t.error) { process.exit(failJson(useJson, t.error)); }
+    for (const n of t.notices) { process.stderr.write(n + '\n'); }
+    promptRes = { prompt: t.prompt, promptMeta: t.promptMeta };
+  } else if (args.artifact !== undefined || args.var !== undefined) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --artifact/--var require --template (expansion happens only in template files)' }));
   }
   // Council preset: expand a saved council into args.models (mutually exclusive with --models).
   const hasModels = typeof args.models === 'string' && args.models.trim();
@@ -190,7 +217,7 @@ async function handleFanout(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models must contain at least one non-empty entry' }));
   }
 
-  // Direct require — the src/index.js public re-export is added later (Task 13)
+  // Direct require (fanout stays internal — no src/index.js public re-export).
   const { runFanout } = require('./sidecar/fanout');
   const { loadConfig, resolveGatewayMode } = require('./utils/config');
   const { resolveFallbackConfig } = require('./sidecar/fallback-chains');
@@ -237,6 +264,7 @@ async function handleFanout(args) {
       config: cfg,
     }),
     catalog: (readCache() || {}).models || [],
+    pack: packRecord, // v4.5 Task 13: null when no --pack; additive on wave metadata.json + wave.json.
   });
   return exitCode;
 }

package/src/cli-handlers-template.js

@@ -0,0 +1,53 @@
+// src/cli-handlers-template.js
+'use strict';
+
+/**
+ * @module cli-handlers-template
+ * F9 (v4.5): `amicus template list|show`. No save/rm — templates are a folder
+ * of Markdown files; your editor is the manager.
+ */
+
+const { SCHEMA_VERSION } = require('./utils/result-schema');
+const { ERROR_CODES, failJson } = require('./utils/error-doc');
+const { listTemplates, resolveTemplate, templatesDir } = require('./template/store');
+
+async function handleTemplate(args) {
+  const useJson = !!args.json;
+  const sub = args._[1];
+
+  if (sub === 'list') {
+    const templates = listTemplates();
+    if (useJson) {
+      process.stdout.write(JSON.stringify({ schemaVersion: SCHEMA_VERSION, type: 'template-list', dir: templatesDir(), templates }, null, 2) + '\n');
+      return 0;
+    }
+    if (templates.length === 0) { process.stdout.write('No templates.\n'); return 0; }
+    for (const t of templates) {
+      const marker = t.builtin ? ' [built-in]' : (t.shadowed ? ' [shadows built-in]' : '');
+      process.stdout.write(`${t.name}${marker}\n`);
+    }
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const ref = args._[2];
+    if (!ref) {
+      return failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: template show requires a <name|path>' });
+    }
+    const t = resolveTemplate(ref);
+    if (t.error) {
+      return failJson(useJson, { code: ERROR_CODES.TEMPLATE_NOT_FOUND, message: t.error, hint: 'amicus template list' });
+    }
+    if (useJson) {
+      process.stdout.write(JSON.stringify({ schemaVersion: SCHEMA_VERSION, type: 'template', name: t.name, path: t.path, hash: t.hash, builtin: t.builtin, text: t.text }, null, 2) + '\n');
+      return 0;
+    }
+    process.stdout.write(t.text + (t.text.endsWith('\n') ? '' : '\n'));
+    return 0;
+  }
+
+  return failJson(useJson, { code: ERROR_CODES.BAD_ARGS,
+    message: `Error: unknown template subcommand '${sub || ''}'`, hint: 'amicus template list | amicus template show <name|path>' });
+}
+
+module.exports = { handleTemplate };