amicus 4.4.1 → 4.5.1

package/src/pack/pack-resolve.js

@@ -0,0 +1,297 @@
+// src/pack/pack-resolve.js
+'use strict';
+
+/**
+ * @module pack/pack-resolve
+ * B7/F5 (v4.5), Task 11. The pack→args merge engine: the single place that
+ * turns a resolved, validated pack into filled-in CLI arg values. Precedence
+ * is explicit flag > pack > config default > built-in, achieved by filling
+ * `args` ONLY for keys the caller did not type (`explicit`, from parseArgs'
+ * `__explicit` — Task 10) — everything else (config defaults, built-in
+ * fallbacks, cross-field validation) is left to the handler that calls this,
+ * unchanged, so v4.0 pre-flight validation runs on the merged, effective
+ * values automatically (spec §5.4).
+ *
+ * Deliberately does NOT call applyTemplate: a pack's `briefing.template` is
+ * just another knob that fills `args.template` (a ref, not rendered text).
+ * Rendering stays a single-application-point concern of the CLI handlers
+ * (Task 12/13), so a pack-filled --template and a typed --template take
+ * exactly the same downstream code path.
+ */
+
+const { readPack } = require('./pack-store');
+const { validatePack } = require('./pack-validate');
+const { ERROR_CODES } = require('../utils/error-doc');
+
+/** `options.*` knobs shared by every kind that defines them (council/fanout/solo).
+ * `agent` is deliberately NOT in this table — see the dedicated fill below. */
+const COMMON_OPTION_KNOBS = [
+  ['timeout', 'timeout'], ['maxCost', 'max-cost'], ['gateway', 'gateway'],
+  ['thinking', 'thinking'], ['summaryLength', 'summary-length'],
+];
+/** `options.*` knobs shared by fanout + solo only (v4.5 F4 context controls). */
+const CONTEXT_OPTION_KNOBS = [
+  ['noContext', 'no-context'], ['contextTurns', 'context-turns'], ['contextMaxTokens', 'context-max-tokens'],
+];
+/** Concrete command name per pack kind, for the KIND_MISMATCH message (never "this command"). */
+const COMMAND_NAME_BY_KIND = { council: 'council run', fanout: 'fanout', solo: 'start' };
+/** MCP tool name per pack kind, for the Finding-2 (Task 15 review) orphan-knob notice below. */
+const MCP_TOOL_NAME_BY_KIND = { council: 'amicus_council_run', fanout: 'amicus_fanout', solo: 'amicus_start' };
+
+/**
+ * council/fanout only: `bench` fills `args.council` (by-name) or `args.models`
+ * (csv), unless the caller already typed one of the two — then it is never
+ * silently dropped, it becomes a notice instead.
+ * @returns {string|null} a notice string, or null when the bench was applied cleanly.
+ */
+function resolveBenchKnob(pack, args, explicit) {
+  const bench = pack.bench;
+  if (bench === undefined || bench === null) { return null; }
+  const modelsExplicit = explicit.has('models');
+  const councilExplicit = explicit.has('council');
+  if (!modelsExplicit && !councilExplicit) {
+    if (typeof bench === 'string') { args.council = bench; }
+    else if (Array.isArray(bench)) { args.models = bench.join(','); }
+    return null;
+  }
+  const flag = modelsExplicit ? '--models' : '--council';
+  return `Notice: ${flag} overrides the bench from pack '${pack.name}'`;
+}
+
+/**
+ * @param {{packRef: string, expectedKind: 'council'|'fanout'|'solo', args: object,
+ *   explicit: Set<string>, useJson?: boolean}} opts `useJson` is accepted for
+ *   call-site symmetry with sibling resolvers (e.g. applyTemplate) but unused
+ *   here: this module never writes to stdout/stderr itself — notices are
+ *   returned as plain strings and the caller alone decides how to print them.
+ * @returns {{packRecord: {name, version, hash, source}, notices: string[]}
+ *   | {error: {code, message, hint}}}
+ */
+function applyPackToArgs({ packRef, expectedKind, args, explicit }) {
+  const rp = readPack(packRef);
+  if (rp.error) {
+    return { error: { code: ERROR_CODES.PACK_NOT_FOUND, message: rp.error, hint: 'amicus pack list' } };
+  }
+  const { pack, source, hash } = rp;
+
+  if (pack.kind !== expectedKind) {
+    return {
+      error: {
+        code: ERROR_CODES.PACK_KIND_MISMATCH,
+        message: `Error: pack '${pack.name}' is kind '${pack.kind}' — ${COMMAND_NAME_BY_KIND[expectedKind] || 'this command'} accepts kind '${expectedKind}'; make two packs if you want both shapes`,
+        hint: null,
+      },
+    };
+  }
+
+  const validation = validatePack(pack, { mode: 'run' });
+  if (!validation.ok) {
+    return {
+      error: {
+        code: ERROR_CODES.PACK_INVALID,
+        message: `Error: pack '${pack.name}' failed validation: ${validation.errors.join('; ')}`,
+        hint: null,
+      },
+    };
+  }
+
+  const opts = pack.options || {};
+  const notices = [];
+  const fill = (argKey, value) => {
+    if (!explicit.has(argKey) && value !== undefined && value !== null) {
+      args[argKey] = value;
+    }
+  };
+
+  if (pack.kind === 'council') {
+    fill('chair', pack.chair);
+  }
+  if (pack.kind === 'solo') {
+    fill('model', pack.model);
+    fill('no-ui', opts.noUi);
+  }
+
+  for (const [optKey, argKey] of COMMON_OPTION_KNOBS) { fill(argKey, opts[optKey]); }
+
+  // v4.5 final-review F4: cli-handlers-run.js normalizes a legacy --mode flag
+  // into args.agent AFTER this merge runs (`args.agent = args.agent ||
+  // args.mode`, handleStart/handleFanout only — council has no --mode flag).
+  // A typed --mode with no --agent lands 'mode' in `explicit` but not 'agent',
+  // so the generic fill() above would silently overwrite a pack's
+  // options.agent onto args.agent before that fallback ever sees args.mode —
+  // the user's typed value loses to the pack, invisibly. Count --mode as
+  // agent-explicit too (same shape as the debate/no-debate negation check
+  // below, which also treats an alternate typed form as full explicitness).
+  const agentExplicit = explicit.has('agent') || explicit.has('mode');
+  if (!agentExplicit && opts.agent !== undefined && opts.agent !== null) { args.agent = opts.agent; }
+
+  if (pack.kind === 'council') {
+    // Task 10 ruling: negations record only the literal typed key, so a
+    // negatable boolean's "was this explicit" check must test both forms.
+    const debateExplicit = explicit.has('debate') || explicit.has('no-debate');
+    if (!debateExplicit && opts.debate !== undefined && opts.debate !== null) {
+      args.debate = opts.debate;
+    }
+    // 2026-07-28 ruling: skip filling pack critic when --lenses is explicit —
+    // it would trip the handler's critic/lenses mutual-exclusion pre-flight.
+    if (!explicit.has('lenses')) { fill('critic', pack.critic); }
+    // 2026-07-28 ruling: skip filling pack lenses when --critic is explicit —
+    // same mutual-exclusion pre-flight, mirrored direction.
+    if (!explicit.has('critic')) {
+      fill('lenses', Array.isArray(pack.lenses) ? pack.lenses.join(',') : pack.lenses);
+    }
+  }
+
+  if (pack.kind === 'fanout' || pack.kind === 'solo') {
+    for (const [optKey, argKey] of CONTEXT_OPTION_KNOBS) { fill(argKey, opts[optKey]); }
+  }
+
+  if (pack.kind === 'council' || pack.kind === 'fanout') {
+    const notice = resolveBenchKnob(pack, args, explicit);
+    if (notice) { notices.push(notice); }
+  }
+
+  fill('template', pack.briefing && pack.briefing.template);
+
+  return {
+    packRecord: { name: pack.name, version: pack.version, hash, source },
+    notices,
+  };
+}
+
+/** argKeys whose CLI-side value is a comma-joined string but whose MCP-side
+ * value is an array (`models`, `lenses`) — the two shapes multi-value knobs
+ * have always used on their respective sides, round-tripped by the bridge
+ * below so `applyPackToArgs`'s tables never need to know about MCP shapes. */
+const CSV_ARG_KEYS = new Set(['models', 'lenses']);
+
+/** Reverse of the knob tables above (argKey -> pack's own camelCase option
+ * key), used ONLY in notice text (v4.5 decision 1b, T15-m10) — naming a
+ * pack's own key is less confusing than the CLI's kebab-case arg-key. Most
+ * bespoke (non-table) knobs — chair/critic/lenses/agent/debate — share their
+ * argKey/option-key spelling, so the plain-argKey fallback is correct for
+ * them; `no-ui` does NOT (pack-side `noUi`) and is listed explicitly. `bench`
+ * fills EITHER args.council or args.models (never an argKey of its own) —
+ * accepted because both always have a real MCP destination, so a
+ * bench-derived value never actually reaches the notice path. */
+const ARG_KEY_TO_OPT_KEY = Object.assign(
+  Object.fromEntries([...COMMON_OPTION_KNOBS, ...CONTEXT_OPTION_KNOBS].map(([optKey, argKey]) => [argKey, optKey])),
+  { 'no-ui': 'noUi' },
+);
+
+/** argKeys forwarded instead of notice'd when a tool's paramMap has no
+ * destination for them (v4.5 decision 1): a pack's maxCost/template must
+ * still apply on `amicus_fanout`/`amicus_start` for CLI parity, even with no
+ * schema param for either. `amicus_council_run` already has real destinations
+ * for both (COUNCIL_PACK_PARAM_MAP), so it never reaches this path. Context
+ * knobs are deliberately excluded — ruled notice-only, out of scope. */
+const FORWARDABLE_ARG_KEYS = new Set(['max-cost', 'template']);
+
+function toArgValue(argKey, value) {
+  return (CSV_ARG_KEYS.has(argKey) && Array.isArray(value)) ? value.join(',') : value;
+}
+function fromArgValue(argKey, value) {
+  return (CSV_ARG_KEYS.has(argKey) && typeof value === 'string')
+    ? value.split(',').map((s) => s.trim()).filter(Boolean)
+    : value;
+}
+
+/**
+ * MCP entry point (Task 15, B7/F5): the same merge as `applyPackToArgs`, for a
+ * caller whose knobs live on an `input` object with MCP-shaped key names
+ * (camelCase, some renamed/inverted vs. the CLI's kebab-case arg keys) rather
+ * than parsed CLI `args`. Builds an args-shaped bridge object via `paramMap`,
+ * reuses `applyPackToArgs` UNCHANGED (same knob tables, same precedence, same
+ * notices), then copies pack-filled values back onto `input` under their
+ * MCP-facing names. An mcpKey already present on `input` is never touched
+ * (explicit wins) — `explicit` is built from the caller's OWN `Object.keys(input)`,
+ * mapped through `paramMap`, mirroring `args.__explicit` on the CLI side.
+ *
+ * Deliberately contains NO pack-domain knowledge (no knob names, no bench/chair/
+ * timeout logic) beyond the key-renaming in `paramMap` — that stays entirely in
+ * `applyPackToArgs`'s tables above. Re-deriving "is this pack-filled" outside
+ * pack-resolve is exactly the mistake a prior review caught (progress.md,
+ * Task-12 entry: "packSuffix is council-local; if fanout/solo need attribution,
+ * centralize 'pack-filled' in pack-resolve rather than re-deriving").
+ *
+ * Fix wave 2 (Task 15 review, Finding 2): a pack knob `applyPackToArgs` fills
+ * but `paramMap` has no MCP destination for (e.g. fanout's `contextTurns`/
+ * `contextMaxTokens`) would otherwise be a silent dead-fill — written into the
+ * local `args` bridge, then dropped on the floor because the write-back loop
+ * below only ever visits `paramMap` entries. Made loud instead: every `args`
+ * key with no `paramMap` destination becomes one notice, naming the pack, the
+ * knob (by the pack's own camelCase option key — v4.5 HOLD-gate decision 1b,
+ * T15-m10), and the MCP tool.
+ *
+ * v4.5 decision 1: two otherwise-orphaned knobs — maxCost/template — are NOT
+ * turned into a notice on `amicus_fanout`/`amicus_start` (no schema param for
+ * either); CLI parity requires them to still apply, so their pack-filled
+ * values come back on `forward` instead, for the caller (mcp-server.js) to
+ * apply itself: forwarded to a spawned child's argv as plain flags, or (the
+ * in-process shared-server path) via the same budget-gate/template-render
+ * code the CLI uses. `amicus_council_run` already has real destinations for
+ * both, so `forward` is always `{}` there.
+ * @param {{packRef: string, expectedKind: 'council'|'fanout'|'solo',
+ *   input: object, paramMap: Object<string, string|{argKey: string, invert: true}>}} opts
+ *   `paramMap` maps each MCP input key a tool exposes to the CLI arg-key name
+ *   the same knob uses in the tables above (e.g. council's `timeoutMinutes` →
+ *   `'timeout'`, plain string = same-polarity rename/identity). An
+ *   `{argKey, invert: true}` entry flips a boolean both ways (fanout/solo's
+ *   `includeContext` vs. the CLI/pack-side `no-context` polarity). An MCP key
+ *   with no pack-fillable knob (e.g. `briefingFile`, `project`) is simply
+ *   omitted from `paramMap` and left untouched by this function.
+ * @returns {{packRecord: {name, version, hash, source}, notices: string[],
+ *   forward: {maxCost?: number, template?: string}} | {error: {code, message, hint}}}
+ */
+function applyPackToMcpInput({ packRef, expectedKind, input, paramMap }) {
+  const args = {};
+  const explicit = new Set();
+  for (const mcpKey of Object.keys(input)) {
+    const entry = paramMap[mcpKey];
+    if (!entry) { continue; }
+    const argKey = typeof entry === 'string' ? entry : entry.argKey;
+    const invert = typeof entry === 'object' && !!entry.invert;
+    args[argKey] = invert ? !input[mcpKey] : toArgValue(argKey, input[mcpKey]);
+    explicit.add(argKey);
+  }
+
+  const pr = applyPackToArgs({ packRef, expectedKind, args, explicit });
+  if (pr.error) { return { error: pr.error }; }
+
+  // Finding 2: diff every key applyPackToArgs touched (explicit bridge seeds +
+  // pack fills) against paramMap's own destination argKeys. The bridging loop
+  // above only ever seeds `args` from a paramMap destination, so anything left
+  // over here was added by a pack fill, never a caller value — always a
+  // genuine dead-fill, never a false positive on an explicit param.
+  const destArgKeys = new Set(
+    Object.values(paramMap).map((entry) => (typeof entry === 'string' ? entry : entry.argKey))
+  );
+  const notices = [...pr.notices];
+  const toolName = MCP_TOOL_NAME_BY_KIND[expectedKind] || `amicus (${expectedKind})`;
+  // v4.5 HOLD-gate decision 1: maxCost/template have no MCP schema destination
+  // on fanout/start, but must still apply (CLI parity) — collected here for the
+  // caller to apply itself, instead of turned into an ignore-notice. Council
+  // already has real destinations for both (destArgKeys.has(argKey) is true
+  // there), so this loop never adds to `forward` for council calls.
+  const forward = {};
+  for (const argKey of Object.keys(args)) {
+    if (destArgKeys.has(argKey)) { continue; }
+    if (FORWARDABLE_ARG_KEYS.has(argKey)) {
+      forward[ARG_KEY_TO_OPT_KEY[argKey] || argKey] = args[argKey];
+      continue;
+    }
+    const optKey = ARG_KEY_TO_OPT_KEY[argKey] || argKey;
+    notices.push(`Notice: pack '${pr.packRecord.name}' sets ${optKey}, which ${toolName} does not support over MCP — ignored.`);
+  }
+
+  for (const [mcpKey, entry] of Object.entries(paramMap)) {
+    const argKey = typeof entry === 'string' ? entry : entry.argKey;
+    if (explicit.has(argKey) || !(argKey in args)) { continue; }
+    const invert = typeof entry === 'object' && !!entry.invert;
+    input[mcpKey] = invert ? !args[argKey] : fromArgValue(argKey, args[argKey]);
+  }
+
+  return { packRecord: pr.packRecord, notices, forward };
+}
+
+module.exports = { applyPackToArgs, applyPackToMcpInput };

package/src/pack/pack-store.js

@@ -0,0 +1,130 @@
+// src/pack/pack-store.js
+'use strict';
+
+/**
+ * @module pack/pack-store
+ * B7/F5 (v4.5): packs are ONE JSON file per pack in <configDir>/packs/ (spec
+ * carried decision 2 — shareability wins: send or commit the file). The
+ * CONTENT HASH is the truth anchor: sha256 over the canonical form (recursively
+ * sorted keys), first 12 hex chars, recorded on every run — a hand-edited pack
+ * whose version wasn't bumped still gets a distinct recorded hash.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { writeFileAtomic } = require('../utils/atomic-write');
+
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function _getConfigDir() { return require('../utils/config').getConfigDir(); }
+
+/** @returns {string} the packs directory (peer of templates/) */
+function packsDir() { return path.join(_getConfigDir(), 'packs'); }
+
+function sortKeysDeep(v) {
+  if (Array.isArray(v)) { return v.map(sortKeysDeep); }
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) { out[k] = sortKeysDeep(v[k]); }
+    return out;
+  }
+  return v;
+}
+
+/** sha256 of the canonical (sorted-keys) JSON form, first 12 hex chars. */
+function canonicalHash(pack) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(sortKeysDeep(pack)), 'utf-8').digest('hex').slice(0, 12);
+}
+
+/** @returns {{kind:'path',path}|{kind:'name',name}|{error}} */
+function resolvePackRef(ref) {
+  const v = String(ref);
+  if (v.endsWith('.json') || v.includes('/') || v.includes(path.sep)) {
+    return { kind: 'path', path: path.resolve(v) };
+  }
+  if (!NAME_RE.test(v)) {
+    return { error: `Error: invalid pack name '${v}' — pack names are 1-64 chars of [a-z0-9._-] starting alphanumeric` };
+  }
+  return { kind: 'name', name: v };
+}
+
+function stripBom(text) { return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text; }
+
+/** @returns {{pack, path, source:'dir'|'path', hash}|{error}} */
+function readPack(ref) {
+  const r = resolvePackRef(ref);
+  if (r.error) { return r; }
+  const file = r.kind === 'path' ? r.path : path.join(packsDir(), `${r.name}.json`);
+  let raw;
+  try { raw = stripBom(fs.readFileSync(file, 'utf-8')); }
+  catch (err) {
+    if (r.kind === 'name') { return { error: `Error: Pack '${r.name}' not found in ${packsDir()}` }; }
+    return { error: `Error: cannot read pack ${ref}: ${err.message}` };
+  }
+  let pack;
+  try { pack = JSON.parse(raw); }
+  catch (err) { return { error: `Error: pack ${file} is not valid JSON: ${err.message}` }; }
+  if (r.kind === 'name' && pack && pack.name !== r.name) {
+    return { error: `Error: pack file ${file} declares name '${pack && pack.name}' which does not match its filename — rename one of them` };
+  }
+  return { pack, path: file, source: r.kind === 'name' ? 'dir' : 'path', hash: canonicalHash(pack) };
+}
+
+function bumpPatch(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(.*)$/.exec(String(version));
+  if (!m) { return '0.0.1'; }
+  return `${m[1]}.${m[2]}.${Number(m[3]) + 1}`;
+}
+
+/**
+ * Write <packsDir>/<pack.name>.json. Existing name: unchanged canonical hash →
+ * {noop:true}; changed with the same version string → auto-bump patch (spec
+ * carried decision 6). Caller validates the pack first (pack-validate).
+ * @returns {{path, hash, overwritten, bumped}|{noop:true, path}}
+ */
+function writePack(pack) {
+  fs.mkdirSync(packsDir(), { recursive: true, mode: 0o700 });
+  const file = path.join(packsDir(), `${pack.name}.json`);
+  let existing = null;
+  try { existing = JSON.parse(stripBom(fs.readFileSync(file, 'utf-8'))); } catch { /* new pack */ }
+  const toWrite = { ...pack };
+  let bumped = false;
+  if (existing) {
+    if (canonicalHash(existing) === canonicalHash(toWrite)) { return { noop: true, path: file }; }
+    if (existing.version === toWrite.version) {
+      toWrite.version = bumpPatch(toWrite.version);
+      bumped = true;
+    }
+  }
+  writeFileAtomic(file, JSON.stringify(toWrite, null, 2), { mode: 0o600 });
+  return { path: file, hash: canonicalHash(toWrite), overwritten: !!existing, bumped, version: toWrite.version };
+}
+
+/** @returns {{packs: Array<{name,kind,version,description}>, warnings: string[]}} name-sorted */
+function listPacks() {
+  let entries = [];
+  try { entries = fs.readdirSync(packsDir()); } catch { /* no dir yet */ }
+  const packs = [];
+  const warnings = [];
+  for (const f of entries) {
+    if (!f.endsWith('.json')) { continue; }
+    try {
+      const p = JSON.parse(stripBom(fs.readFileSync(path.join(packsDir(), f), 'utf-8')));
+      packs.push({ name: p.name, kind: p.kind, version: p.version, description: p.description || '' });
+    } catch (err) { warnings.push(`${f}: ${err.message}`); }
+  }
+  packs.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  return { packs, warnings };
+}
+
+/** @returns {{removed: boolean}} */
+function rmPack(name) {
+  const r = resolvePackRef(name);
+  if (r.error || r.kind !== 'name') { return { removed: false }; }
+  try { fs.unlinkSync(path.join(packsDir(), `${r.name}.json`)); return { removed: true }; }
+  catch { return { removed: false }; }
+}
+
+module.exports = { packsDir, canonicalHash, resolvePackRef, readPack, writePack, listPacks, rmPack };

package/src/pack/pack-validate.js

@@ -0,0 +1,113 @@
+// src/pack/pack-validate.js
+'use strict';
+
+/**
+ * @module pack/pack-validate
+ * Spec §5.6. Runs at `pack save` (hard-fail), `pack show` (reports, never
+ * fails), and run-time resolve (hard-fail through the envelope, pre-spend).
+ * Kind matching itself (PACK_KIND_MISMATCH) is the caller's check — this
+ * module validates a pack's internal consistency.
+ */
+
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const SEMVER_RE = /^\d+\.\d+\.\d+/;
+const KINDS = ['council', 'fanout', 'solo'];
+
+/** Per-kind allowed `options` keys (spec §5.1; solo UI-suppression key per Task 0's verified flag set).
+ * v4.5 HOLD-gate decision 2 (final-review F1): `agent`/`thinking`/`summaryLength`
+ * are inert on EVERY council surface — handleCouncilRun never reads a pack-filled
+ * one, and the engine hardcodes agent 'Plan'/summaryLength 'verbose' regardless.
+ * Dropped from `council` pre-release rather than shipped as dead weight a pack
+ * author would reasonably expect to work; a council pack that still sets one now
+ * fails save/run validation (PACK_INVALID) like any other unknown option for the
+ * kind. They remain valid (and functional) on `fanout`/`solo`. */
+const KIND_OPTIONS = Object.freeze({
+  council: ['timeout', 'maxCost', 'gateway', 'debate'],
+  fanout: ['timeout', 'maxCost', 'gateway', 'agent', 'thinking', 'summaryLength',
+    'noContext', 'contextTurns', 'contextMaxTokens'],
+  solo: ['timeout', 'maxCost', 'gateway', 'agent', 'thinking', 'summaryLength',
+    'noUi', 'noContext', 'contextTurns', 'contextMaxTokens'],
+});
+
+/** Fields allowed per kind beyond the common set. */
+const COMMON_FIELDS = ['schemaVersion', 'type', 'name', 'version', 'kind', 'description', 'options', 'briefing'];
+const KIND_FIELDS = Object.freeze({
+  council: [...COMMON_FIELDS, 'bench', 'chair', 'critic', 'lenses'],
+  fanout: [...COMMON_FIELDS, 'bench'],
+  solo: [...COMMON_FIELDS, 'model'],
+});
+
+/**
+ * @param {object} pack
+ * @param {{mode: 'save'|'run'}} opts
+ * @returns {{ok:true, warnings:string[]} | {ok:false, errors:string[]}}
+ */
+function validatePack(pack, { mode } = { mode: 'run' }) {
+  const errors = [];
+  const warnings = [];
+  if (!pack || typeof pack !== 'object') { return { ok: false, errors: ['pack is not an object'] }; }
+  if (pack.schemaVersion !== 1) { errors.push(`schemaVersion must be 1 (got ${pack.schemaVersion})`); }
+  if (pack.type !== 'pack') { errors.push(`type must be 'pack' (got '${pack.type}')`); }
+  if (typeof pack.name !== 'string' || !NAME_RE.test(pack.name)) { errors.push(`invalid pack name '${pack.name}'`); }
+  if (typeof pack.version !== 'string' || !SEMVER_RE.test(pack.version)) { errors.push(`version must be semver-shaped (got '${pack.version}')`); }
+  if (!KINDS.includes(pack.kind)) {
+    errors.push(`kind must be one of ${KINDS.join('|')} (got '${pack.kind}')`);
+    return { ok: false, errors };
+  }
+
+  for (const key of Object.keys(pack)) {
+    if (!KIND_FIELDS[pack.kind].includes(key)) { errors.push(`field '${key}' is not valid for kind '${pack.kind}'`); }
+  }
+  const opts = pack.options || {};
+  if (typeof opts !== 'object' || Array.isArray(opts)) { errors.push('options must be an object'); }
+  else {
+    for (const key of Object.keys(opts)) {
+      if (!KIND_OPTIONS[pack.kind].includes(key)) { errors.push(`unknown option '${key}' for kind '${pack.kind}'`); }
+    }
+  }
+
+  const { getEffectiveAliases, getCouncilWithSource } = require('../utils/config');
+  const aliases = getEffectiveAliases();
+  const seatOk = (m) => typeof m === 'string' && (m.includes('/') || !!aliases[m]);
+
+  if (pack.kind === 'solo') {
+    if (typeof pack.model !== 'string' || !pack.model.trim()) { errors.push('solo pack requires model'); }
+    else if (!seatOk(pack.model)) { errors.push(`unresolvable model '${pack.model}'`); }
+  } else {
+    const bench = pack.bench;
+    if (typeof bench === 'string') {
+      const { members } = getCouncilWithSource(bench, []);
+      if (!members) { errors.push(`bench names unknown council '${bench}'`); }
+      else if (pack.kind === 'council' && (pack.lenses || pack.chair || pack.critic)) {
+        warnings.push('bench is by-name: member-level checks (chair/critic/lenses vs seats) deferred to run time');
+      }
+    } else if (Array.isArray(bench) && bench.length >= 2) {
+      const bad = bench.filter((m) => !seatOk(m));
+      if (bad.length) { errors.push(`unresolvable bench member(s): ${bad.join(', ')}`); }
+      if (pack.kind === 'council') {
+        if (pack.chair && bench.includes(pack.chair)) { errors.push(`chair '${pack.chair}' is a bench seat — the chair must not review`); }
+        if (pack.critic && !bench.includes(pack.critic)) { errors.push(`critic '${pack.critic}' must be one of the bench seats`); }
+        if (pack.critic && pack.lenses) { errors.push('critic and lenses are mutually exclusive'); }
+        if (Array.isArray(pack.lenses) && pack.lenses.length !== bench.length) {
+          errors.push(`lenses needs exactly one lens per seat (${bench.length} seats, got ${pack.lenses.length})`);
+        }
+      }
+    } else {
+      errors.push('bench must be a council name or an array of 2+ members');
+    }
+  }
+
+  const tplRef = pack.briefing && pack.briefing.template;
+  if (tplRef !== undefined && tplRef !== null) {
+    const { resolveTemplate } = require('../template/store');
+    const t = resolveTemplate(tplRef);
+    if (t.error) {
+      if (mode === 'save') { warnings.push(`briefing.template '${tplRef}' does not resolve on this machine (packs travel; it may exist where the pack is used)`); }
+      else { errors.push(`briefing.template '${tplRef}' does not resolve`); }
+    }
+  }
+
+  return errors.length ? { ok: false, errors } : { ok: true, warnings };
+}
+
+module.exports = { validatePack, KIND_OPTIONS, KINDS };

package/src/sidecar/electron-state.js

@@ -0,0 +1,61 @@
+/**
+ * Electron install-state probes (#76).
+ *
+ * Distinguishes the two states isElectronUsable() collapses into one boolean:
+ *   'package-missing' — the electron optionalDependency was never installed
+ *                       (possibly deliberate: headless-only install)
+ *   'binary-missing'  — package present but dist/<exe> absent (interrupted
+ *                       postinstall, AV quarantine) — repairElectron territory
+ *   'ok'              — the resolved exe exists on disk
+ *
+ * Also owns electronDirFor(): the per-install dual-root layout probe. npm
+ * NESTS electron under amicus/node_modules in a global install but HOISTS it
+ * to a sibling in the npx cache — the same layout asymmetry that broke the
+ * engine probe (#69). In-process require.resolve handles hoisting via walk-up,
+ * which is why the running copy probes itself fine; only CROSS-install probing
+ * (doctor) needs this explicit dual-root check.
+ */
+
+'use strict';
+
+const path = require('path');
+const fsDefault = require('fs');
+const { isElectronUsable, defaultElectronDir } = require('./electron-install');
+
+/**
+ * Locate the electron package dir serving a given amicus install. Checks the
+ * nested root first (require.resolve walk-up order), then the hoisted sibling.
+ * @param {string} pkgDir amicus package root
+ * @param {{fs?:object}} [deps]
+ * @returns {string|null} electron package dir, or null when not installed
+ */
+function electronDirFor(pkgDir, { fs = fsDefault } = {}) {
+  const candidates = [
+    path.join(pkgDir, 'node_modules', 'electron'),
+    path.join(path.dirname(pkgDir), 'electron'),
+  ];
+  for (const dir of candidates) {
+    try { if (fs.existsSync(dir)) { return dir; } } catch { /* unreadable root */ }
+  }
+  return null;
+}
+
+/**
+ * Probe one electron package dir into the 3-state verdict.
+ * `electronDir: null` (electronDirFor found nothing) short-circuits to
+ * package-missing; an explicit dir without package.json reports the same.
+ * @param {{electronDir?:string|null, fs?:object, platform?:string, env?:object}} [opts]
+ * @returns {{state:'ok'|'package-missing'|'binary-missing', electronDir:string|null}}
+ */
+function probeElectronState({
+  electronDir = defaultElectronDir(), fs = fsDefault, platform = process.platform, env = process.env,
+} = {}) {
+  if (!electronDir) { return { state: 'package-missing', electronDir: null }; }
+  let hasPkg = false;
+  try { hasPkg = fs.existsSync(path.join(electronDir, 'package.json')); } catch { /* unreadable */ }
+  if (!hasPkg) { return { state: 'package-missing', electronDir }; }
+  const usable = isElectronUsable({ electronDir, fs, platform, env });
+  return { state: usable ? 'ok' : 'binary-missing', electronDir };
+}
+
+module.exports = { electronDirFor, probeElectronState };

package/src/sidecar/fanout.js

@@ -42,6 +42,12 @@ function deriveLegIds(waveId, count) {
  *   stdout — tests), councilRunId? / councilName? (v4.3 §7.2: stamped onto legs),
  *   fallback? / catalog? (v4.3 Task 18 §6.2: opt-in substitution; off/absent unchanged),
  *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical),
+ *   pack? (v4.5 Task 13: {name,version,hash,source} record when launched via
+ *     --pack; absent/null -> omitted from wave metadata.json/wave.json, not stored as null.
+ *     v4.5 final-review F2: when absent, wave.json still inherits a pack the caller
+ *     pre-seeded onto this wave dir's metadata.json before calling runFanout — see
+ *     `metaPack` below. That is how an MCP-spawned child, which never receives
+ *     --pack itself, still ends up with the pack on its wave.json),
  *   server? + serverClient? (v4.4.1 Task 0.5: an ALREADY-STARTED OpenCode server
  *     to run this wave's legs on. Both or neither. When supplied this wave never
  *     starts a server and never closes one — see the seam comment in step 4.
@@ -80,7 +86,7 @@ async function runFanout(options) {
   // `reason` in metadata.json, no wave.json, and stage1 recorded 'complete'.
   // waveDir is optional (only the post-creation caller has one).
   const errorWave = (waveId, message, waveDir) => {
-    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, createdAt, completedAt: new Date().toISOString(), status: 'error' });
+    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, pack: options.pack, createdAt, completedAt: new Date().toISOString(), status: 'error' });
     doc.error = message;
     doc.reason = message; // classifier alias, same as fanout-leg.js's run docs
     // best-effort: an unwritable wave dir must not mask the real error
@@ -137,13 +143,24 @@ async function runFanout(options) {
   const waveDir = getSessionDir(project, waveId);
   fs.mkdirSync(waveDir, { recursive: true, mode: 0o700 });
   fs.writeFileSync(path.join(waveDir, 'briefing.md'), options.prompt, { mode: 0o600 });
-  writeWaveMetadata(waveDir, {
+  const waveMeta = writeWaveMetadata(waveDir, {
     taskId: waveId, type: 'wave', status: 'running', mode: 'headless',
     models: legs.map(l => (l.ok ? l.model : l.modelInput)), legs: legIds,
     briefing: String(options.prompt).slice(0, 200),
     promptMeta: options.promptMeta || null,
+    ...(options.pack ? { pack: options.pack } : {}), // v4.5 Task 13: absent-not-null.
     pid: process.pid, project, createdAt,
   });
+  // v4.5 final-review F2: an MCP-spawned child never gets --pack (single-
+  // resolution rule), but mcp-server.js pre-seeds THIS wave dir's
+  // metadata.json with the pack it already resolved in-process before
+  // spawning the child. writeWaveMetadata read-merges (fanout-wave-io.js),
+  // so its RETURN VALUE already carries that pre-seeded pack when
+  // options.pack is absent here — inherit from it below rather than
+  // re-reading the file (mirrors the inherit idiom in
+  // result-schema-rebuild.js:93, which reads meta.pack off a metadata.json
+  // it loaded for an unrelated reason).
+  const metaPack = waveMeta.pack;
   emitWaveStarted(waveDir, waveId, legs.map(l => (l.ok ? l.model : l.modelInput)), legIds, follow);
 
   // 2b. All legs failed to route (#61 perf): no leg will ever touch the
@@ -154,7 +171,7 @@ async function runFanout(options) {
     const legDocs = legs.map((leg, i) => buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }));
     const completedAt = new Date().toISOString();
     const wave = buildWaveResult({
-      waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt, notices,
+      waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt, notices,
     });
     return finishWave({ wave, waveDir, waveId, project, completedAt, follow, emit,
       exitCode: waveExitCode(wave.status),
@@ -265,7 +282,7 @@ async function runFanout(options) {
   const completedAt = new Date().toISOString();
   const signalled = waveAbort.signal();
   const wave = buildWaveResult({
-    waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
+    waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt,
     status: signalled ? 'aborted' : null, notices,
   });
   const exitCode = signalled