amicus 4.6.2 → 4.7.0

package/src/cli-handlers-doctor.js

@@ -80,10 +80,14 @@ function realDeps() {
     now: () => Date.now(),
     listSessionIndexTmpFiles: () => tmpSweep.listSessionIndexTmpFiles(), // B15
     unlinkSessionIndexTmp: (n) => tmpSweep.unlinkSessionIndexTmp(n),
+    listSessionMetadataTmpFiles: () => metaSweep.listSessionMetadataTmpFiles(), // D8
+    unlinkSessionMetadataTmp: (n) => metaSweep.unlinkSessionMetadataTmp(n),
   };
 }
 // B15: sweep logic in utils/session-index-tmp-sweep.js (mirrors mcp-legacy's split).
 const tmpSweep = require('./utils/session-index-tmp-sweep');
+// D8: per-session metadata.json sibling sweep — utils/session-metadata-tmp-sweep.js.
+const metaSweep = require('./utils/session-metadata-tmp-sweep');
 
 /** Run one guarded check; a thrown fn becomes an error line. */
 function guard(id, name, fn) {
@@ -108,10 +112,10 @@ async function runDoctorChecks(depsOverride = {}) {
   const checks = [];
 
   checks.push(guard('node', 'Node.js', () => {
-    const major = parseInt(String(d.nodeVersion).replace(/^v/, '').split('.')[0], 10);
-    return major >= 18
+    const [maj, min] = String(d.nodeVersion).replace(/^v/, '').split('.').map(n => parseInt(n, 10));
+    return (maj > 22 || (maj === 22 && min >= 12))
       ? { id: 'node', name: 'Node.js', status: 'ok', message: d.nodeVersion, hint: null }
-      : { id: 'node', name: 'Node.js', status: 'error', message: `${d.nodeVersion} (need >=18)`, hint: 'Install Node 18 or newer from https://nodejs.org' };
+      : { id: 'node', name: 'Node.js', status: 'error', message: `${d.nodeVersion} (need >=22.12)`, hint: 'Install Node 22.12 or newer from https://nodejs.org' };
   }));
 
   checks.push(guard('config-dir', 'Config directory', () => (
@@ -201,6 +205,8 @@ async function runDoctorChecks(depsOverride = {}) {
 
   checks.push(guard('sessions-index-tmp', 'Session index tmp files', () => tmpSweep.evaluateSessionIndexTmpSweep(d)));
 
+  checks.push(guard('session-metadata-tmp', 'Session metadata tmp files', () => metaSweep.evaluateSessionMetadataTmpSweep(d)));
+
   // #43: OpenRouter credit/free-tier — warns (never errors); skipped when no key.
   checks.push(await guardAsync('openrouter-credit', 'OpenRouter credit', async () => {
     const values = d.readApiKeyValues() || {};

package/src/cli-handlers-fanout.js

@@ -0,0 +1,179 @@
+/**
+ * CLI handler for the fanout command (multi-model parallel runs).
+ *
+ * Extracted verbatim from cli-handlers-run.js (v4.7 PR0) to keep that file
+ * under the 300-line gate before F8 adds --tag forwarding. Whole-handler
+ * split precedent: cli-handlers-resume-continue.js.
+ */
+
+'use strict';
+
+const { validateTaskId, validateTag } = require('./utils/validators');
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
+const { applyTemplateForArgs } = require('./cli-template-args');
+
+/**
+ * Handle 'amicus fanout' command (F4).
+ * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
+ * 130/143 when the wave was signal-aborted.
+ */
+async function handleFanout(args) {
+  const useJson = !!args.json;
+
+  // v4.7 F8 (D13): a retried wave replays each leg's own saved context
+  // byte-identical — there is no fresh session to attach a new --tag to, so
+  // reject the combination before the retry-failed dispatch below.
+  if (args.tag !== undefined && args['retry-failed']) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --tag cannot be combined with --retry-failed' }));
+  }
+
+  // --retry-failed <waveId> (v4.3 Task 19, spec 6.1): a completely different
+  // path from the --prompt/--models launch below (no briefing, no required
+  // --models — the original wave's failed legs supply their own saved
+  // context) — dispatch BEFORE any of that validation runs. --models here is
+  // optional and, when present, filters which failed legs get retried.
+  // --pack is likewise ignored on this path (deliberate, same precedent: retry
+  // replays the wave's recorded per-leg config; flags that reshape a wave don't apply).
+  if (args['retry-failed']) {
+    const { retryFailedWave } = require('./sidecar/fanout-retry');
+    const { parseModelsList } = require('./sidecar/fanout-validate');
+    const { exitCode, errorDoc } = await retryFailedWave(String(args['retry-failed']), args.cwd || process.cwd(), {
+      models: parseModelsList(args.models), json: useJson,
+    });
+    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
+  // value silently fell through to resolveGatewayMode's pass-through instead
+  // of failing fast with a clear error.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
+  }
+
+  const { resolvePromptSource } = require('./utils/prompt-source');
+  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 };
+  }
+  const tpl = applyTemplateForArgs(args, promptRes.prompt, useJson);
+  if (tpl.fail !== undefined) { process.exit(tpl.fail); }
+  if (tpl.applied) { promptRes = { prompt: tpl.prompt, promptMeta: tpl.promptMeta }; }
+  // Council preset: expand a saved council into args.models (mutually exclusive with --models).
+  const hasModels = typeof args.models === 'string' && args.models.trim();
+  const hasCouncil = args.council !== undefined && args.council !== false;
+  if (hasModels && hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pass exactly one of --models / --council, not both' }));
+  }
+  if (!hasModels && !hasCouncil) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs), or use --council <name>' }));
+  }
+  if (hasCouncil) {
+    if (typeof args.council !== 'string' || !args.council.trim()) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --council requires a council name (e.g. --council free)' }));
+    }
+    const { resolveCouncilMembers } = require('./utils/config');
+    const { readCache } = require('./utils/model-catalog');
+    const catalog = (readCache() || {}).models || [];
+    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
+    if (expanded.error) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }));
+    }
+    if (expanded.dropped && expanded.dropped.length && !useJson) {
+      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
+    }
+    args.models = expanded.models.join(',');
+  }
+  if (args['wave-id']) {
+    const check = validateTaskId(String(args['wave-id']));
+    if (!check.valid) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
+    }
+  }
+  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --agent chat is interactive-only; fanout is headless' }));
+  }
+  if (args.timeout !== undefined && args.timeout <= 0) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --timeout must be a positive number' }));
+  }
+  const mc = args['max-cost'];
+  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
+  }
+  // v4.7 F8 (D13): reject-style (unlike sanitizeCouncilName, which cleans) —
+  // a stored tag is a user-chosen search key, so silent truncation/stripping
+  // would make --search/--group-by tag miss it.
+  if (args.tag !== undefined) {
+    const tagCheck = validateTag(args.tag);
+    if (!tagCheck.ok) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: tagCheck.error }));
+    }
+  }
+  const { parseModelsList } = require('./sidecar/fanout');
+  if (parseModelsList(args.models).length === 0) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models must contain at least one non-empty entry' }));
+  }
+
+  // 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');
+  const { readCache } = require('./utils/model-catalog');
+  const cfg = loadConfig() || {};
+  const { exitCode } = await runFanout({
+    models: args.models,
+    prompt: promptRes.prompt,
+    promptMeta: promptRes.promptMeta,
+    waveId: args['wave-id'],
+    project: args.cwd || process.cwd(),
+    agent: args.agent || args.mode,
+    thinking: args.thinking,
+    timeout: args.timeout,
+    summaryLength: args['summary-length'],
+    includeContext: !args['no-context'],
+    sessionId: args['session-id'],
+    contextTurns: args['context-turns'],
+    contextSince: args['context-since'],
+    contextMaxTokens: args['context-max-tokens'],
+    // #10: forward the Cowork parent so MCP-spawned fanout legs pin the right
+    // session (mirrors handleStart's coworkProcess plumbing). Without this the
+    // spawned `--cowork-process` flag is dropped and buildContext gets null.
+    coworkProcess: args['cowork-process'],
+    mcp: args.mcp,
+    mcpConfig: args['mcp-config'],
+    noMcp: args['no-mcp'],
+    excludeMcp: args['exclude-mcp'],
+    noValidateModel: args['no-validate-model'],
+    // #61 Task 7.3: --gateway merged with routing.prefer, applied per leg
+    // by validateFanoutModels' router call.
+    gatewayMode: resolveGatewayMode(args.gateway),
+    json: !!args.json,
+    // v4.7 PR3 rider: `quiet` is a repo-wide known flag, so `fanout --quiet`
+    // parsed and exited 0 while runFanout still printed — forward it.
+    quiet: !!args.quiet,
+    client: args.client,
+    maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,
+    noCostGate: !!args['no-cost-gate'],
+    maxCostPerMtok: cfg.maxCostPerMtok,
+    follow: !!args.follow,
+    onComplete: args['on-complete'],
+    // v4.3 Task 18 (spec §6.2): opt-in cheaper-model substitution. --fallback
+    // forces on, --no-fallback forces off; unset defers to config `fallbacks.enabled`.
+    fallback: resolveFallbackConfig({
+      flagFallback: args.fallback === true ? true : (args['no-fallback'] ? false : undefined),
+      config: cfg,
+    }),
+    catalog: (readCache() || {}).models || [],
+    pack: packRecord, // v4.5 Task 13: null when no --pack; additive on wave metadata.json + wave.json.
+    tag: args.tag, // v4.7 F8: undefined when no --tag; Task 3 stores it on wave metadata.
+  });
+  return exitCode;
+}
+
+module.exports = { handleFanout };

package/src/cli-handlers-pack.js

@@ -23,7 +23,9 @@ 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 };
+  // `--pack-version`, NOT `--version`: the latter is a global BOOLEAN_FLAG that
+  // bin/amicus.js intercepts before dispatch, so it could never arrive here.
+  const pack = { schemaVersion: 1, type: 'pack', name, version: args['pack-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') {
@@ -72,12 +74,18 @@ function packFromCouncilRun(name, version, run) {
   };
 }
 
-/** 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');
-
+/**
+ * wave branch: a fanout wave's metadata.json (type:'wave'), plus its first leg.
+ * `{fs, path, getSessionDir}` is threaded in from buildPackFromRun's own lazy
+ * require (below) rather than required again here — T14-m7: this file's other
+ * lazy requires (session-manager per cli-handlers-abort.js/cli-handlers-watch.js/
+ * mcp-council-awareness.js; pack-store/pack-validate in handlePack below) are
+ * all function-scoped, deferred until the `--from-run` path actually needs
+ * them, so a second copy of the same require triple here would just be
+ * duplication without buying back any additional laziness — buildPackFromRun
+ * already pays that cost once, on the only branch that reaches this function.
+ */
+function packFromWave(name, version, project, meta, { fs, path, getSessionDir }) {
   const opts = {};
   const firstLeg = Array.isArray(meta.legs) ? meta.legs[0] : null;
   if (firstLeg) {
@@ -114,7 +122,7 @@ function packFromSolo(name, version, meta) {
  */
 function buildPackFromRun(name, id, project, args) {
   const runState = require('./council/run-state');
-  const version = args.version || '1.0.0';
+  const version = args['pack-version'] || '1.0.0'; // see buildPackFromFlags — never args.version
 
   const ptr = runState.readPointer(project, id); // {runId, runDir}|null (run-state.js:156)
   const run = ptr ? runState.readRun(ptr.runDir) : null;
@@ -128,7 +136,9 @@ function buildPackFromRun(name, id, project, args) {
     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);
+    pack = meta.type === 'wave'
+      ? packFromWave(name, version, project, meta, { fs, path, getSessionDir })
+      : 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
@@ -152,7 +162,6 @@ function renderPackList(doc) {
     });
     text = 'Packs:\n' + lines.join('\n') + '\n';
   }
-  for (const w of doc.warnings) { text += `Warning: ${w}\n`; }
   return text;
 }
 
@@ -201,6 +210,11 @@ async function handlePack(args) {
     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));
+    // T14-m1: warnings are diagnostics, not data — keep them off stdout so
+    // `amicus pack list | grep`/`--json` consumers never see them mixed into
+    // the list itself. `pack save` already writes this identical string to
+    // stderr (above); `--json` is untouched: `warnings` stays a field on doc.
+    if (!useJson) { for (const w of warnings) { process.stderr.write(`Warning: ${w}\n`); } }
     return 0;
   }
 

package/src/cli-handlers-run.js

@@ -13,11 +13,12 @@
 'use strict';
 
 const { validateStartArgs } = require('./cli');
-const { validateTaskId } = require('./utils/validators');
+const { validateTaskId, validateTag } = require('./utils/validators');
 const { resolveLaunchModel, maybeOfferProviderDefaults } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson } = require('./utils/cli-preflight');
-const { GATEWAY_MODES } = require('./utils/model-descriptor');
+const { handleFanout } = require('./cli-handlers-fanout');
+const { applyTemplateForArgs } = require('./cli-template-args');
 
 /**
  * Handle 'sidecar start' command
@@ -37,17 +38,9 @@ async function handleStart(args) {
     // 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)' }));
-  }
+  const tpl = applyTemplateForArgs(args, args.prompt, useJson);
+  if (tpl.fail !== undefined) { process.exit(tpl.fail); }
+  if (tpl.applied) { args.prompt = tpl.prompt; templateMeta = tpl.templateMeta; }
   requireNoUiForJson(args, useJson);
 
   const mc = args['max-cost'];
@@ -55,6 +48,18 @@ async function handleStart(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
   }
 
+  // v4.7 F8 (D13): --tag rejects (unlike sanitizeCouncilName, which cleans) —
+  // a stored tag is a user-chosen search key, so silent truncation/stripping
+  // would make --search/--group-by tag miss it. Checked here, beside the other
+  // pre-flight arg checks, so a bad tag exits before model resolution / the
+  // one-time onboarding tip (T2-m1: was previously after resolveLaunchModel).
+  if (args.tag !== undefined) {
+    const tagCheck = validateTag(args.tag);
+    if (!tagCheck.ok) {
+      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: tagCheck.error }));
+    }
+  }
+
   const { model, alias } = await resolveLaunchModel(args);
   args.model = model;
 
@@ -118,157 +123,10 @@ async function handleStart(args) {
     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.
+    tag: args.tag, // v4.7 F8: undefined when no --tag; Task 3 stores it on session metadata.
   });
 }
 
-/**
- * Handle 'amicus fanout' command (F4).
- * Returns the wave exit code: 0 all complete, 2 partial, 1 none/hard failure,
- * 130/143 when the wave was signal-aborted.
- */
-async function handleFanout(args) {
-  const useJson = !!args.json;
-
-  // --retry-failed <waveId> (v4.3 Task 19, spec 6.1): a completely different
-  // path from the --prompt/--models launch below (no briefing, no required
-  // --models — the original wave's failed legs supply their own saved
-  // context) — dispatch BEFORE any of that validation runs. --models here is
-  // optional and, when present, filters which failed legs get retried.
-  if (args['retry-failed']) {
-    const { retryFailedWave } = require('./sidecar/fanout-retry');
-    const { parseModelsList } = require('./sidecar/fanout-validate');
-    const { exitCode, errorDoc } = await retryFailedWave(String(args['retry-failed']), args.cwd || process.cwd(), {
-      models: parseModelsList(args.models), json: useJson,
-    });
-    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
-  // value silently fell through to resolveGatewayMode's pass-through instead
-  // of failing fast with a clear error.
-  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
-  }
-
-  const { resolvePromptSource } = require('./utils/prompt-source');
-  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();
-  const hasCouncil = args.council !== undefined && args.council !== false;
-  if (hasModels && hasCouncil) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: pass exactly one of --models / --council, not both' }));
-  }
-  if (!hasModels && !hasCouncil) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models is required (comma-separated aliases or provider/model IDs), or use --council <name>' }));
-  }
-  if (hasCouncil) {
-    if (typeof args.council !== 'string' || !args.council.trim()) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --council requires a council name (e.g. --council free)' }));
-    }
-    const { resolveCouncilMembers } = require('./utils/config');
-    const { readCache } = require('./utils/model-catalog');
-    const catalog = (readCache() || {}).models || [];
-    const expanded = resolveCouncilMembers(args.council.trim(), catalog);
-    if (expanded.error) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: ${expanded.error}` }));
-    }
-    if (expanded.dropped && expanded.dropped.length && !useJson) {
-      process.stderr.write(`Notice: dropped unavailable council member(s): ${expanded.dropped.join(', ')}\n`);
-    }
-    args.models = expanded.models.join(',');
-  }
-  if (args['wave-id']) {
-    const check = validateTaskId(String(args['wave-id']));
-    if (!check.valid) {
-      process.exit(failJson(useJson, { code: ERROR_CODES.BAD_SESSION, message: check.error }));
-    }
-  }
-  if (args.agent && String(args.agent).toLowerCase() === 'chat') {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --agent chat is interactive-only; fanout is headless' }));
-  }
-  if (args.timeout !== undefined && args.timeout <= 0) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --timeout must be a positive number' }));
-  }
-  const mc = args['max-cost'];
-  if (mc !== undefined && (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0)) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
-  }
-  const { parseModelsList } = require('./sidecar/fanout');
-  if (parseModelsList(args.models).length === 0) {
-    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --models must contain at least one non-empty entry' }));
-  }
-
-  // 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');
-  const { readCache } = require('./utils/model-catalog');
-  const cfg = loadConfig() || {};
-  const { exitCode } = await runFanout({
-    models: args.models,
-    prompt: promptRes.prompt,
-    promptMeta: promptRes.promptMeta,
-    waveId: args['wave-id'],
-    project: args.cwd || process.cwd(),
-    agent: args.agent || args.mode,
-    thinking: args.thinking,
-    timeout: args.timeout,
-    summaryLength: args['summary-length'],
-    includeContext: !args['no-context'],
-    sessionId: args['session-id'],
-    contextTurns: args['context-turns'],
-    contextSince: args['context-since'],
-    contextMaxTokens: args['context-max-tokens'],
-    // #10: forward the Cowork parent so MCP-spawned fanout legs pin the right
-    // session (mirrors handleStart's coworkProcess plumbing). Without this the
-    // spawned `--cowork-process` flag is dropped and buildContext gets null.
-    coworkProcess: args['cowork-process'],
-    mcp: args.mcp,
-    mcpConfig: args['mcp-config'],
-    noMcp: args['no-mcp'],
-    excludeMcp: args['exclude-mcp'],
-    noValidateModel: args['no-validate-model'],
-    // #61 Task 7.3: --gateway merged with routing.prefer, applied per leg
-    // by validateFanoutModels' router call.
-    gatewayMode: resolveGatewayMode(args.gateway),
-    json: !!args.json,
-    client: args.client,
-    maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,
-    noCostGate: !!args['no-cost-gate'],
-    maxCostPerMtok: cfg.maxCostPerMtok,
-    follow: !!args.follow,
-    onComplete: args['on-complete'],
-    // v4.3 Task 18 (spec §6.2): opt-in cheaper-model substitution. --fallback
-    // forces on, --no-fallback forces off; unset defers to config `fallbacks.enabled`.
-    fallback: resolveFallbackConfig({
-      flagFallback: args.fallback === true ? true : (args['no-fallback'] ? false : undefined),
-      config: cfg,
-    }),
-    catalog: (readCache() || {}).models || [],
-    pack: packRecord, // v4.5 Task 13: null when no --pack; additive on wave metadata.json + wave.json.
-  });
-  return exitCode;
-}
-
 /**
  * Handle 'sidecar read' command
  * Spec Reference: §4.5

package/src/cli-template-args.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * @module cli-template-args
+ * v4.7 PR6 sweep: the single application point for --template/--artifact/--var,
+ * shared by the three CLI handlers (handleStart, handleFanout, handleCouncilRun)
+ * that used to carry this block verbatim-triplicated.
+ *
+ * NEVER calls process.exit: handleStart and handleFanout exit on failure, but
+ * handleCouncilRun RETURNS its exit code (its whole handler contract is
+ * return-the-code) — so the decision belongs to the caller, not this helper.
+ */
+
+const { failJson, ERROR_CODES } = require('./utils/error-doc');
+
+const NEEDS_TEMPLATE_MSG =
+  'Error: --artifact/--var require --template (expansion happens only in template files)';
+
+/**
+ * @param {object} args parsed argv
+ * @param {string|undefined} prompt pre-template prompt text
+ * @param {boolean} useJson
+ * @returns {{applied:false}
+ *   | {applied:true, prompt:string, promptMeta:object, templateMeta:object}
+ *   | {fail:number}}
+ */
+function applyTemplateForArgs(args, prompt, useJson) {
+  if (args.template !== undefined) {
+    const { applyTemplate } = require('./template/apply');
+    const t = applyTemplate({
+      templateRef: args.template, prompt,
+      artifactFile: args.artifact, varList: args.var,
+      project: args.cwd || process.cwd(),
+    });
+    if (t.error) { return { fail: failJson(useJson, t.error) }; }
+    for (const n of t.notices) { process.stderr.write(n + '\n'); }
+    return {
+      applied: true, prompt: t.prompt, promptMeta: t.promptMeta,
+      templateMeta: t.promptMeta.template,
+    };
+  }
+  if (args.artifact !== undefined || args.var !== undefined) {
+    return { fail: failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: NEEDS_TEMPLATE_MSG }) };
+  }
+  return { applied: false };
+}
+
+module.exports = { applyTemplateForArgs, NEEDS_TEMPLATE_MSG };