amicus 4.4.0 → 4.5.0

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-spend.js

@@ -50,15 +50,22 @@ function parseSinceDays(since) {
  * the arithmetic actually saw. It exists so the renderers can say "$X plus N
  * unknown" instead of coercing null→0 and printing a measured-looking $0.0000
  * (diagnosis §8, final paragraph).
+ *
+ * v4.4.1 CA-2: `unattributedSubtreeRows` is its sibling for the OTHER way the
+ * figure understates. Such a row is fully priced — it is in `amount`, it is in
+ * the `r` bucket, `unpricedRows` never sees it — but the leg spawned a child
+ * session whose spend the walk could not determine, which is exactly what makes
+ * `council run` report `costExact: false` about the same dollars. Without this
+ * counter `amicus spend` disagreed with `council run` and looked complete.
  * @param {Array<object>} rows
  */
 function aggregateSpend(rows) {
-  const total = { amount: 0, tokens: emptyTokens(), runs: rows.length, unpricedRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } };
+  const total = { amount: 0, tokens: emptyTokens(), runs: rows.length, unpricedRows: 0, unattributedSubtreeRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } };
   const byModelMap = new Map();
   for (const r of rows) {
     const model = r.model || 'unknown';
     if (!byModelMap.has(model)) {
-      byModelMap.set(model, { model, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } });
+      byModelMap.set(model, { model, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } });
     }
     const bucket = byModelMap.get(model);
     bucket.runs += 1;
@@ -68,6 +75,8 @@ function aggregateSpend(rows) {
     const priced = typeof cost.amount === 'number';
     const amount = priced ? cost.amount : 0;
     if (!priced) { bucket.unpricedRows += 1; total.unpricedRows += 1; }
+    // Beside, never instead of: a row can be both unpriced and subtree-unknown.
+    if (r.subtreeUnknown) { bucket.unattributedSubtreeRows += 1; total.unattributedSubtreeRows += 1; }
     bucket.amount += amount;
     total.amount += amount;
     // Any source string outside {reported,estimated} buckets as unknown —
@@ -178,6 +187,15 @@ function renderHuman({ total, byModel, windowDays, credit, wasted }) {
     out += `${total.unpricedRows} unpriced row(s) — cost unknown and NOT in the total; `
       + 'real spend is at least this much.\n';
   }
+  // v4.4.1 CA-2: a DIFFERENT statement from the line above, and deliberately
+  // worded as one. "We could not see this leg at all" (unpriced) vs "we saw this
+  // leg, and its own cost IS in the total, but not what it spawned" — the second
+  // is why `council run` reports costExact:false on a row that looks complete
+  // here. Both lines can appear at once; a row can be in both counts.
+  if (total.unattributedSubtreeRows > 0) {
+    out += `${total.unattributedSubtreeRows} row(s) spawned a subagent whose CHILD session `
+      + 'spend could NOT be determined — real spend is HIGHER than this total.\n';
+  }
   if (wasted && wasted.runs > 0) {
     out += `Wasted (failed runs): ${formatCost({ amount: wasted.amount, source: 'mixed' })} across ${wasted.runs} rows — see amicus spend --failed\n`;
   }

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

package/src/cli-handlers-watch.js

@@ -84,6 +84,17 @@ async function handleWatch(args) {
     // at the wrong directory when a run was launched elsewhere.
     const project = args.project || args.cwd || process.cwd();
     const runId = args._[1] ? String(args._[1]) : '';
+    // ⚠️ v4.4.1 DOC-3: validate HERE, not by moving the branch. The branch's
+    // POSITION above the `id is required` gate is load-bearing (bare `--ui`
+    // opens the run-list landing and must keep working), so the runId check is
+    // pushed inside it and made conditional on a runId actually being supplied.
+    // Without this, `amicus watch <typo> --ui` skipped validateTaskId entirely
+    // and surfaced whatever getRunDetail produced — a vaguer error than the
+    // identical typo gets on the terminal path.
+    if (runId) {
+      const uiCheck = validateTaskId(runId);
+      if (!uiCheck.valid) { process.stderr.write(`${uiCheck.error}\n`); return 1; }
+    }
     const { launchWorkspaceWindow } = require('./sidecar/workspace-window');
     const res = await launchWorkspaceWindow({ project, runId });
     if (res.error) { process.stderr.write(`${res.error}\n`); }

package/src/cli.js

@@ -44,6 +44,7 @@ function parseArgs(argv) {
     _: [],
     ...DEFAULTS
   };
+  result.__explicit = new Set();
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -63,19 +64,22 @@ function parseArgs(argv) {
       // Boolean flags (no value expected)
       if (isBooleanFlag(key)) {
         result[key] = true;
+        result.__explicit.add(key);
         continue;
       }
 
       // If --key=value was used, use the inline value directly
       if (inlineValue !== undefined) {
         result[key] = parseValue(key, inlineValue);
+        result.__explicit.add(key);
         continue;
       }
 
       // Array accumulation flags
-      if (key === 'exclude-mcp' && next && !next.startsWith('--')) {
-        result['exclude-mcp'] = result['exclude-mcp'] || [];
-        result['exclude-mcp'].push(next);
+      if ((key === 'exclude-mcp' || key === 'var') && next && !next.startsWith('--')) {
+        result[key] = result[key] || [];
+        result[key].push(next);
+        result.__explicit.add(key);
         i++;
         continue;
       }
@@ -85,6 +89,7 @@ function parseArgs(argv) {
       // boolean so it can never swallow the following positional as a value.
       if (key.startsWith('no-')) {
         result[key] = true;
+        result.__explicit.add(key);
         continue;
       }
 
@@ -95,6 +100,7 @@ function parseArgs(argv) {
       } else {
         result[key] = true;
       }
+      result.__explicit.add(key);
     } else if (arg === '-o') {
       // Single short-flag alias, scoped to exactly '-o' (council verdict's
       // --out shorthand). No general short-flag support is implemented —
@@ -106,6 +112,7 @@ function parseArgs(argv) {
       } else {
         result.out = true;
       }
+      result.__explicit.add('out');
     } else {
       result._.push(arg);
     }
@@ -428,6 +435,10 @@ Options for 'start':
   --no-validate-model          Skip model-catalog validation before launch
   --gateway <mode>             Routing: auto (direct-first), direct, or openrouter
   --position <pos>             Window position: right (default), left, center
+  --template <name|path>       Render a briefing template ({{prompt}}, {{artifact}}, {{var.*}})
+  --artifact <file>            File whose content fills {{artifact}} (256 KB cap; needs --template)
+  --var <k=v>                  Template variable, repeatable (needs --template)
+  --pack <name|path>           Load a saved pack (model/options/template); explicit flags override it
 `,
   fanout: `
 Options for 'fanout':
@@ -459,6 +470,10 @@ Options for 'fanout':
                                 RESULT_FILE/EVENTS_FILE/COST/PROJECT), never model
                                 text. Child stdout/stderr go to amicus stderr.
                                 Never changes the wave's exit code, docs, or events.
+  --template <name|path>       Render a briefing template ({{prompt}}, {{artifact}}, {{var.*}})
+  --artifact <file>            File whose content fills {{artifact}} (256 KB cap; needs --template)
+  --var <k=v>                  Template variable, repeatable (needs --template)
+  --pack <name|path>           Load a saved pack (bench/options/template); explicit flags override it
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
@@ -545,6 +560,8 @@ Subcommands for 'council':
       [--gateway auto|direct|openrouter] [--no-validate-model]
       [--debate] [--claude-review <file>] [--no-cost-gate] [--follow]
       [--fallback] [--no-fallback] [--on-complete <cmd>]
+      [--template <name|path>] [--artifact <file>] [--var <k=v>]
+      [--pack <name|path>]
                                 Run the full headless council engine (v4.0).
                                 Chair default: deepseek (must NOT be a bench seat).
                                 --critic and --lenses are mutually exclusive.
@@ -567,6 +584,13 @@ Subcommands for 'council':
                                 EVENTS_FILE/COST/PROJECT), never model text. Child
                                 stdout/stderr go to amicus stderr. Never changes
                                 the run's exit code, docs, or events.
+                                --template <name|path> renders a briefing from
+                                {{prompt}}, {{artifact}}, {{var.*}}; --artifact
+                                fills {{artifact}} (256 KB cap); --var sets
+                                {{var.*}} (repeatable). Both require --template.
+                                --pack <name|path> loads a saved pack (bench,
+                                chair, critic/lenses, options, template);
+                                explicit flags always override the pack's values.
                                 Exit: 0 full run, 2 degraded, 1 quorum/cost/validation.
   save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
     --json                     Machine-readable output
@@ -598,12 +622,14 @@ Options for 'spend':
 `,
   watch: `
 Options for 'watch':
-  <id>                          A fan-out wave id, council run id, or session id
+  <id>                          A fan-out wave id, council run id, or session id.
+                                Optional with --ui: bare 'amicus watch --ui' opens the
+                                project's Council Workspace run list
   --project <path>              Project the run was launched in (default cwd)
   --interval <sec>              Refresh interval (default 2, floor 0.5)
   --plain                       Milestone log lines instead of the refresh table
   --json                        NDJSON: tailed events + composed doc on change + final doc
-  --ui                          Open the Council Workspace window (v4.4; interactive-only)
+  --ui                          Open the Council Workspace window (interactive-only)
 `,
   setup: `
 Options for 'setup':
@@ -637,6 +663,43 @@ Options for 'init':
   Runs skill install + MCP registration on demand (for plugin-channel /
   --ignore-scripts installs, a failed postinstall, or repairing deleted
   ~/.claude state). No flags registers both Claude Code and Claude Desktop.
+`,
+  template: `
+Options for 'template':
+  amicus template list [--json]           List templates (built-ins marked)
+  amicus template show <name|path> [--json]  Print a template
+`,
+  pack: `
+Options for 'pack':
+  amicus pack save <name> --kind council|fanout|solo [flags]
+                                Save a pack built from flags:
+                                --bench <a,b,c|name>    council/fanout: comma-
+                                                         separated members, or a
+                                                         saved council name
+                                --model <model>          solo kind only
+                                --chair/--critic/--lenses    council kind only
+                                --timeout/--max-cost/--gateway   shared run
+                                                         options
+                                --agent/--thinking/--summary-length   fanout/
+                                                         solo kind only
+                                --debate / --no-debate   council kind only
+                                --template <name|path>   briefing template
+                                                         reference (not rendered)
+                                --version <semver>       default 1.0.0 (an
+                                                         unchanged re-save is a
+                                                         no-op; a changed one
+                                                         auto-bumps the patch)
+                                --description <text>
+  amicus pack save <name> --from-run <id>
+                                Build a pack from an existing council run /
+                                fanout wave / solo session instead of flags
+                                (models, options, and a template REFERENCE only
+                                — briefing text is never captured)
+  amicus pack list [--json]    List saved packs
+  amicus pack show <name|path> [--json]
+                                Print a pack plus its validation report (never
+                                fails on an invalid pack — see 'validation')
+  amicus pack rm <name> [--json]   Remove a saved pack
 `
 };
 

package/src/council/briefings-debate.js

@@ -110,20 +110,40 @@ function buildRevoteBundle({ findings, date }) {
   return parts.join('\n\n');
 }
 
-function repair(kind, contract, errors) {
+/**
+ * ⚠️ LC-12: same omission as LC-6 one stage earlier — a repair solo is a FRESH
+ * session and cannot see the response it is repairing unless we hand it over.
+ * `prior` is embedded verbatim and uncapped; the absent case is stated rather
+ * than papered over with an empty block, so a model with nothing to correct is
+ * told to say so instead of left to invent a position.
+ * @param {string} kind 'defense' | 're-vote'
+ * @param {string} contract the trailing-JSON contract for that kind
+ * @param {Array<{code:string,detail:string}>} errors
+ * @param {string} [prior] the text that ACTUALLY failed validation
+ */
+function repair(kind, contract, errors, prior) {
   const lines = (errors || []).map(e => `- ${e.code}: ${e.detail}`).join('\n');
+  const text = typeof prior === 'string' ? prior.trim() : '';
+  const block = text
+    ? [`--- YOUR PREVIOUS ${kind.toUpperCase()} (verbatim — this is the text to correct) ---`,
+      text,
+      `--- END OF YOUR PREVIOUS ${kind.toUpperCase()} ---`].join('\n')
+    : `Your previous ${kind} response was empty — there is no prior text to correct. `
+      + 'Do not invent a position to satisfy the schema: say so in your output.';
   return [
-    'Do NOT use any tools or read any files; everything is in this message; begin ' +
-    'immediately with the JSON block.',
-    `Your previous ${kind} response's trailing JSON failed validation with these errors:`,
+    'Do NOT use any tools or read any files; everything is in this message; begin '
+    + 'immediately with the JSON block.',
+    block,
+    `That ${kind} response's trailing JSON failed validation with these errors:`,
     lines,
-    'Re-emit ONLY the corrected JSON block as a single fenced ```json block:',
+    'Re-emit ONLY the corrected JSON block (the same position, fixed — do not change '
+    + 'your votes), as a single fenced ```json block:',
     contract,
   ].join('\n\n');
 }
 
-function buildDefenseRepairPrompt({ errors }) { return repair('defense', DEFENSE_CONTRACT, errors); }
-function buildRevoteRepairPrompt({ errors }) { return repair('re-vote', REVOTE_CONTRACT, errors); }
+function buildDefenseRepairPrompt({ errors, defense }) { return repair('defense', DEFENSE_CONTRACT, errors, defense); }
+function buildRevoteRepairPrompt({ errors, revote }) { return repair('re-vote', REVOTE_CONTRACT, errors, revote); }
 
 /**
  * Chair-packet "Debate round outcomes" section (spec §5.3c). De-anonymized —