amicus 4.4.0 → 4.5.0

package/src/pack/pack-forward.js

@@ -0,0 +1,96 @@
+// src/pack/pack-forward.js
+'use strict';
+
+/**
+ * @module pack/pack-forward
+ * Wave-1 review fix wave (I1/I2/I3): validates a pack-forwarded `maxCost`/
+ * `template` (pack-resolve.js's `applyPackToMcpInput(...).forward` — see that
+ * module's own docblock; only ever `maxCost`/`template`, both optional)
+ * BEFORE any spawn or state write, on every MCP path that forwards them
+ * (amicus_fanout; amicus_start's spawn-fallback AND in-process paths).
+ * Extracted out of mcp-server.js (grandfathered/size-exempt) because this is
+ * genuine new logic — pack-content validation and template rendering, not
+ * wiring — and needs direct unit tests a source-text grep can't provide.
+ *
+ * Two independent defects, one call:
+ *  - I2 (maxCost): `checkBudget` (sidecar/budget.js) only enforces
+ *    `typeof === 'number' && > 0`; a hand-edited pack with a string/zero/
+ *    negative maxCost silently runs UNCAPPED on the in-process path (the
+ *    type check just falls through, so no ceiling is ever applied), while a
+ *    spawned CLI child re-validates its own --max-cost and refuses it
+ *    (BAD_ARGS) — but only AFTER the tool already returned success and (on
+ *    amicus_fanout) already wrote a 'running' wave record. Caught here,
+ *    pre-spend, on every path, instead.
+ *  - I1 (template): the built-in `review` template needs {{artifact}}/
+ *    {{artifact_path}}, which fanout/start can never supply (neither passes
+ *    an --artifact-equivalent through pack forwarding). A naive blind forward
+ *    lets the CHILD's render fail via process.exit AFTER the tool already
+ *    returned success — on amicus_fanout the pre-seeded wave record has no
+ *    `pid`, so crash-detection (which only probes pid-bearing records) never
+ *    notices, and the wave is stuck 'running' forever. Fixed by dry-running
+ *    applyTemplate here, in-process, with EXACTLY the inputs the child will
+ *    use (no artifact, no --var — a pack's forwarded template carries only
+ *    its name). applyTemplate is a pure function of those inputs ({{date}}
+ *    is day-granular), so a success here guarantees the child's own later
+ *    (real) re-render succeeds identically — the child still does its own
+ *    render, so template provenance (`promptMeta.template`) is still
+ *    recorded exactly as Wave 1 built it.
+ *
+ * Callers that only need the pre-spend validation (the two spawn paths)
+ * ignore the returned `renderedPrompt`; amicus_start's in-process path
+ * (which never spawns a child, so nothing else would render it) reuses it
+ * as the actual prompt instead of rendering a second time.
+ */
+
+const { ERROR_CODES } = require('../utils/error-doc');
+
+/**
+ * @param {{forward: {maxCost?: number, template?: string}, packRef: string,
+ *   prompt: string, project: string}} opts `forward` is pack-resolve.js's
+ *   `applyPackToMcpInput(...).forward`; `packRef` names the pack in error
+ *   text — pass the RESOLVED pack's name (`packRecord.name`), not necessarily
+ *   the caller's raw `--pack`/`pack` ref (which may be a path).
+ * @returns {{maxCost?: number, templateName?: string, renderedPrompt?: string,
+ *   notices: string[]} | {error: {code, message, hint}}}
+ */
+function prepareForward({ forward, packRef, prompt, project }) {
+  const notices = [];
+  const result = { notices };
+
+  if (forward.maxCost !== undefined) {
+    const mc = forward.maxCost;
+    // Same validity rule cli-handlers-run.js applies to a typed --max-cost
+    // (handleStart/handleFanout): only a positive finite JS number passes. A
+    // pack is JSON, so a hand-edited "maxCost": "2.00" (string) is exactly
+    // the kind of mistake this must catch — it would otherwise reach
+    // checkBudget's `typeof === 'number'` check, fail it silently, and run
+    // with no ceiling at all.
+    if (typeof mc !== 'number' || !Number.isFinite(mc) || mc <= 0) {
+      return {
+        error: {
+          code: ERROR_CODES.PACK_INVALID,
+          message: `Error: pack '${packRef}' sets an invalid max-cost (${JSON.stringify(mc)}) — must be a positive number`,
+          hint: null,
+        },
+      };
+    }
+    result.maxCost = mc;
+  }
+
+  if (forward.template !== undefined) {
+    // Same call shape the child process makes (cli-handlers-run.js's
+    // handleStart :40-43 / handleFanout :164-167): no artifactFile, no
+    // varList — a pack's forwarded template carries only its name, never
+    // --artifact/--var (pack-resolve.js only ever forwards `template`).
+    const { applyTemplate } = require('../template/apply');
+    const t = applyTemplate({ templateRef: forward.template, prompt, project });
+    if (t.error) { return { error: t.error }; }
+    result.templateName = forward.template;
+    result.renderedPrompt = t.prompt;
+    notices.push(...t.notices);
+  }
+
+  return result;
+}
+
+module.exports = { prepareForward };

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/child-sessions.js

@@ -42,7 +42,7 @@
 
 const { getChildren, getMessages } = require('../opencode-client');
 const { createMirrorState, mirrorUsageOnly } = require('./conversation-mirror');
-const { sumPerMessageUsage, hasObservedTokens } = require('../utils/pricing');
+const { sumPerMessageUsage } = require('../utils/pricing');
 
 /**
  * Bounds. Hard constants rather than env knobs: they exist to stop a pathological
@@ -88,7 +88,6 @@ function usageOfSession(messages) {
     // what they are. A session with neither tokens nor cost is not free either:
     // we saw nothing, and nothing is not zero.
     priced: totals.costReported > 0,
-    observed: hasObservedTokens(totals.tokens),
   };
 }