amicus 4.4.0 → 4.5.0

package/src/mcp-server.js

@@ -225,6 +225,27 @@ function computeNextPoll() {
 const HEADLESS_START_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): before calling amicus_status, you MUST run `sleep 25` in your shell first. This enforces the polling interval and prevents token waste. Do other useful work while waiting, or run `sleep 25` to block until the next poll window.</system-reminder>';
 const HEADLESS_STATUS_REMINDER = '<system-reminder>Preferred: call amicus_wait with this task ID instead — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): this session is still running. Before calling amicus_status again, you MUST run `sleep 25` in your shell first. Each premature poll wastes context tokens for zero benefit. Run `sleep 25` now, then check again.</system-reminder>';
 
+/**
+ * v4.5 Task 15 (B7/F5): map amicus_fanout / amicus_start's MCP input keys to
+ * the CLI arg-key names applyPackToArgs's knob tables use (pack-resolve.js),
+ * so applyPackToMcpInput can reuse those tables unchanged — see
+ * src/mcp-council-run.js's COUNCIL_PACK_PARAM_MAP for the sibling map and its
+ * fuller docblock. `includeContext` is the one inverted-polarity knob: the
+ * pack/CLI side is `no-context` (true = drop context), the MCP side is
+ * `includeContext` (true = keep context, default true).
+ */
+const FANOUT_PACK_PARAM_MAP = {
+  models: 'models', council: 'council', gateway: 'gateway', agent: 'agent', thinking: 'thinking',
+  timeout: 'timeout', summaryLength: 'summary-length',
+  includeContext: { argKey: 'no-context', invert: true },
+};
+const SOLO_PACK_PARAM_MAP = {
+  model: 'model', gateway: 'gateway', agent: 'agent', noUi: 'no-ui', thinking: 'thinking',
+  timeout: 'timeout', contextTurns: 'context-turns', contextMaxTokens: 'context-max-tokens',
+  summaryLength: 'summary-length',
+  includeContext: { argKey: 'no-context', invert: true },
+};
+
 /** Spawn an Amicus CLI process (fire-and-forget) */
 function spawnSidecarProcess(args, sessionDir) {
   const sidecarBin = path.join(__dirname, '..', 'bin', 'amicus.js');
@@ -250,9 +271,49 @@ function spawnSidecarProcess(args, sessionDir) {
   return child;
 }
 
+/** v4.5 Wave-1 review fix (I1/I2): validates/dry-runs a pack-forwarded
+ * maxCost/template (see src/pack/pack-forward.js) — a no-op when the pack
+ * forwarded neither knob. Shared by amicus_fanout and amicus_start (both
+ * build their OWN error response below; the two tools use different shapes). */
+function checkPackForward(packForward, packRecord, prompt, project) {
+  if (packForward.maxCost === undefined && packForward.template === undefined) {
+    return { notices: [] };
+  }
+  return require('./pack/pack-forward').prepareForward({
+    forward: packForward, packRef: packRecord.name, prompt, project,
+  });
+}
+
 /** Tool handler implementations */
 const handlers = {
   async amicus_start(input, project, mcpServer) {
+    // v4.5 Task 15 (B7/F5): resolve `pack` IN-PROCESS before any validation —
+    // mirrors handleStart's own ordering (cli-handlers-run.js resolves --pack
+    // before validateStartArgs), so a pack-filled value gets the SAME
+    // validation pass a typed one does. Single-resolution rule: never spawn
+    // --pack — this is the only place the pack is resolved.
+    let packRecord = null;
+    const packNotices = [];
+    // v4.5 HOLD-gate decision 1: pack-filled maxCost/template have no MCP
+    // schema param of their own (see SOLO_PACK_PARAM_MAP above) but must still
+    // apply for CLI parity, on BOTH of this handler's paths (spawn-fallback
+    // below; the in-process shared-server branch further down) — a pack must
+    // not behave differently depending on which path fired.
+    let packForward = {};
+    if (input.pack !== undefined) {
+      const { applyPackToMcpInput } = require('./pack/pack-resolve');
+      const pr = applyPackToMcpInput({
+        packRef: input.pack, expectedKind: 'solo', input, paramMap: SOLO_PACK_PARAM_MAP,
+      });
+      if (pr.error) {
+        const { buildErrorDoc } = require('./utils/error-doc');
+        return { isError: true, content: [{ type: 'text', text: JSON.stringify(buildErrorDoc(pr.error)) }] };
+      }
+      packRecord = pr.packRecord;
+      packNotices.push(...pr.notices);
+      packForward = pr.forward;
+    }
+
     // Validate non-model inputs (prompt/timeout/agent) before any session creation.
     const { validateStartInputs } = require('./utils/input-validators');
     const validation = validateStartInputs(input);
@@ -307,6 +368,15 @@ const handlers = {
     const resolvedModel = routeResult.executableId;
 
     const cwd = project || getProjectDir(input.project);
+
+    // v4.5 Wave-1 review fix (I1/I2): validated ONCE, before EITHER downstream
+    // path does anything spend-adjacent — parity holds BY CONSTRUCTION.
+    const fwd = checkPackForward(packForward, packRecord, input.prompt, cwd);
+    if (fwd.error) {
+      const { buildErrorDoc } = require('./utils/error-doc');
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify(buildErrorDoc(fwd.error)) }] };
+    }
+
     const { generateTaskId } = require('./sidecar/start');
     const taskId = generateTaskId();
 
@@ -325,8 +395,14 @@ const handlers = {
     // resolvedModel is always defined here — a routing failure already
     // returned above — and is the router's executableId, not the raw alias.
     args.push('--model', resolvedModel);
-    const agent = (input.noUi && (!input.agent || input.agent.toLowerCase() === 'chat'))
-      ? 'build' : input.agent;
+    // v4.5 Task 15 fix wave 2 (Finding 1): agent/noUi no longer carry a Zod
+    // .default() (see mcp-tools.js) — an omitted key is now genuinely absent
+    // here, so a pack can fill it. Preserve today's effective default ('Chat')
+    // at this READ site instead: the resolved value is identical whether the
+    // key was never set, or a caller/pack explicitly wrote 'Chat'.
+    const agentInput = input.agent || 'Chat';
+    const agent = (input.noUi && agentInput.toLowerCase() === 'chat')
+      ? 'build' : agentInput;
     if (agent) { args.push('--agent', agent); }
     if (input.noUi) { args.push('--no-ui'); }
     if (input.thinking) { args.push('--thinking', input.thinking); }
@@ -339,12 +415,50 @@ const handlers = {
     if (input.coworkProcess)    { args.push('--cowork-process', input.coworkProcess); }
     if (input.parentSession)    { args.push('--session-id', input.parentSession); }
     if (input.windowPosition)   { args.push('--position', input.windowPosition); }
+    // v4.5 HOLD-gate decision 1: forward a pack-filled maxCost/template as
+    // plain CLI flags on the spawn-fallback path — neither has an MCP schema
+    // param of its own, but CLI parity requires them to apply anyway. Never
+    // pushed when the pack didn't fill them. The in-process shared-server
+    // branch below applies the SAME two knobs via its own mechanism (budget
+    // gate / template pre-render) for parity between the two paths.
+    if (packForward.maxCost !== undefined) { args.push('--max-cost', String(packForward.maxCost)); }
+    if (packForward.template !== undefined) { args.push('--template', packForward.template); }
     args.push('--cwd', cwd);
 
     if (sharedServer.enabled && input.noUi) {
       // Shared server path: headless only, delegates to runHeadless()
       let sessionId;
       try {
+        // v4.5 decision 1 + Wave-1 fix (I1/I2): the template was already
+        // rendered by the shared prepareForward call above — reuse its text
+        // instead of rendering again. Notices stay LOCAL (not packNotices):
+        // a fall-through to the spawn-fallback catch must never leak one.
+        const inProcessNotices = [...fwd.notices];
+        const renderedPrompt = fwd.renderedPrompt !== undefined ? fwd.renderedPrompt : input.prompt;
+        if (packForward.maxCost !== undefined) {
+          // fwd.maxCost is already validated (I2); the ceiling gate itself
+          // stays here (needs resolvedModel/pricing, unavailable to pack-forward.js).
+          const { lookupPricing } = require('./utils/pricing');
+          const { checkBudget, formatBudgetError } = require('./sidecar/budget');
+          const { loadConfig } = require('./utils/config');
+          const cfg = loadConfig() || {};
+          const soloLeg = { modelInput: input.model || resolvedModel, model: resolvedModel, pricing: lookupPricing(resolvedModel) };
+          const budget = checkBudget([soloLeg], {
+            maxCostPerMtok: cfg.maxCostPerMtok, maxCost: fwd.maxCost,
+            promptChars: (renderedPrompt && renderedPrompt.length) || 0,
+          });
+          if (!budget.ok) {
+            const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+            return {
+              isError: true,
+              content: [{ type: 'text', text: JSON.stringify(buildErrorDoc({
+                code: ERROR_CODES.BUDGET_EXCEEDED, message: 'Error: budget gate refused the run',
+                hint: formatBudgetError(budget),
+              })) }],
+            };
+          }
+        }
+
         const { server, client } = await sharedServer.ensureServer();
         const { createSession } = require('./opencode-client');
         const { buildContext } = require('./sidecar/context-builder');
@@ -380,7 +494,12 @@ const handlers = {
           // so without them status/list/read show a briefing-less, mode-less run.
           mode: 'headless',
           agent: agent || 'build',
-          briefing: input.prompt,
+          // v4.5 HOLD-gate decision 1: the RENDERED prompt (byte-identical to
+          // input.prompt when no pack template applied) — parity with the CLI,
+          // whose briefing.md on disk is always the rendered text (spec §4).
+          briefing: renderedPrompt,
+          // v4.5 Task 15: additive-only — absent (not null) without a pack.
+          ...(packRecord ? { pack: packRecord } : {}),
         }, null, 2), { mode: 0o600 });
 
         // Build context from parent conversation (unless --no-context)
@@ -402,9 +521,13 @@ const handlers = {
         // 15b.3: one nonce per run, generated before prompt construction.
         const foldNonce = generateFoldNonce();
 
-        // Build prompts (same as CLI path in start.js)
+        // Build prompts (same as CLI path in start.js). renderedPrompt is the
+        // pack-template-rendered text when packForward.template was set above
+        // (byte-identical to input.prompt otherwise) — this is the ONE place
+        // the built prompt reaches the model, so rendering has no effect
+        // unless it is threaded in here.
         const { system: systemPrompt, userMessage } = buildPrompts(
-          input.prompt, context, cwd, true, agent, input.summaryLength, undefined, foldNonce
+          renderedPrompt, context, cwd, true, agent, input.summaryLength, undefined, foldNonce
         );
 
         // Register session with idle eviction
@@ -505,6 +628,14 @@ const handlers = {
         // shared-server path (no CLI stderr exists for an MCP caller).
         const sharedServerContent = [{ type: 'text', text: body }];
         if (routeResult.notice) { sharedServerContent.push({ type: 'text', text: routeResult.notice }); }
+        // v4.5 Task 15: pack notices (e.g. a bench-override) are non-fatal —
+        // surfaced as extra content blocks, same precedent as routeResult.notice above.
+        for (const n of packNotices) { sharedServerContent.push({ type: 'text', text: n }); }
+        // v4.5 HOLD-gate decision 1: template-render notices (e.g. an unused
+        // --var-equivalent), merged only now that the in-process path has
+        // actually succeeded — see the try block's opening comment for why
+        // these are not in the shared packNotices array.
+        for (const n of inProcessNotices) { sharedServerContent.push({ type: 'text', text: n }); }
         sharedServerContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
         return { content: sharedServerContent };
       } catch (err) {
@@ -542,6 +673,8 @@ const handlers = {
           // CLI child's createSessionMetadata overwrite (or if it crashes first).
           mode: input.noUi ? 'headless' : 'interactive',
           briefing: input.prompt,
+          // v4.5 Task 15: additive-only — absent (not null) without a pack.
+          ...(packRecord ? { pack: packRecord } : {}),
         }, null, 2), { mode: 0o600 });
       }
     }
@@ -560,6 +693,7 @@ const handlers = {
     // resolved the route in-process above, so surface its notice here.
     const spawnContent = [{ type: 'text', text: body }];
     if (routeResult.notice) { spawnContent.push({ type: 'text', text: routeResult.notice }); }
+    for (const n of packNotices) { spawnContent.push({ type: 'text', text: n }); }
     if (isHeadless) {
       spawnContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
       return { content: spawnContent };
@@ -1068,6 +1202,41 @@ const handlers = {
     const { generateTaskId } = require('./sidecar/start');
     const { deriveLegIds, DEFAULT_MAX_LEGS } = require('./sidecar/fanout');
 
+    // v4.5 Task 15 (B7/F5): resolve `pack` IN-PROCESS before the models/council
+    // validation below, same single-resolution rule as amicus_start/
+    // amicus_council_run — never spawn --pack; this is the only place the
+    // pack is resolved.
+    let packRecord = null;
+    const packNotices = [];
+    // v4.5 HOLD-gate decision 1: pack-filled maxCost/template have no MCP
+    // schema param of their own (see FANOUT_PACK_PARAM_MAP above) but must
+    // still apply for CLI parity — applyPackToMcpInput hands them back here
+    // instead of turning them into an ignore-notice; this handler forwards
+    // them to the spawned CLI child's argv below.
+    let packForward = {};
+    if (input.pack !== undefined) {
+      const { applyPackToMcpInput } = require('./pack/pack-resolve');
+      const pr = applyPackToMcpInput({
+        packRef: input.pack, expectedKind: 'fanout', input, paramMap: FANOUT_PACK_PARAM_MAP,
+      });
+      // v4.5 final-review T15-m1: amicus_start's own pack-error branch above
+      // keeps code+hint via buildErrorDoc's JSON envelope; amicus_fanout's
+      // error surface is plain text, so the hint (e.g. PACK_NOT_FOUND's
+      // 'amicus pack list') is appended to the message instead of being
+      // converted into a JSON envelope, which would change this tool's
+      // established response shape.
+      if (pr.error) { return textResult(pr.error.message + (pr.error.hint ? `\n${pr.error.hint}` : ''), true); }
+      packRecord = pr.packRecord;
+      packNotices.push(...pr.notices);
+      packForward = pr.forward;
+    }
+    // v4.5 Wave-1 review fix (I1/I2): validated HERE, before any wave dir /
+    // metadata write — never blind. Same posture as the pack-error branch
+    // above (plain text + appended hint; this handler is born-fenced, not JSON).
+    const fwd = checkPackForward(packForward, packRecord, input.prompt, cwd);
+    if (fwd.error) { return textResult(fwd.error.message + (fwd.error.hint ? `\n${fwd.error.hint}` : ''), true); }
+    packNotices.push(...fwd.notices);
+
     // Resolve a single effective models list (council OR models), validated
     // BEFORE any wave dir / metadata is written so a bad request never strands
     // a pid-less 'running' orphan wave.
@@ -1110,6 +1279,8 @@ const handlers = {
       writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify({
         taskId: waveId, type: 'wave', status: 'running', legs: legIds,
         models: effectiveModels, headless: true, createdAt: new Date().toISOString(),
+        // v4.5 Task 15: additive-only — absent (not null) without a pack.
+        ...(packRecord ? { pack: packRecord } : {}),
       }, null, 2), { mode: 0o600 });
       // #40: index the wave AND each leg so status/read of any leg resolves the
       // project even when the default later defaults to a different one.
@@ -1138,8 +1309,17 @@ const handlers = {
     // so context-inheriting fanout launched from Cowork resolves the right parent.
     if (input.coworkProcess) { args.push('--cowork-process', input.coworkProcess); }
     if (input.parentSession) { args.push('--session-id', input.parentSession); }
+    // v4.5 HOLD-gate decision 1: forward a pack-filled maxCost/template as
+    // plain CLI flags — neither has an MCP schema param of its own, but CLI
+    // parity requires them to apply anyway (a shared pack's spend cap and
+    // briefing template must not silently vanish over MCP). Never pushed when
+    // the pack didn't fill them; single-resolution rule unaffected (--pack
+    // itself is never forwarded, only the two knobs it resolved to).
+    if (packForward.maxCost !== undefined) { args.push('--max-cost', String(packForward.maxCost)); }
+    if (packForward.template !== undefined) { args.push('--template', packForward.template); }
 
-    try { spawnSidecarProcess(args, waveDir); } catch (err) {
+    let child;
+    try { child = spawnSidecarProcess(args, waveDir); } catch (err) {
       // Best-effort: never leave a pid-less wave record claiming 'running'
       // forever (crash detection only probes records WITH a pid).
       try {
@@ -1149,6 +1329,16 @@ const handlers = {
       } catch { /* best-effort */ }
       return textResult(`Failed to start fan-out: ${err.message}`, true);
     }
+
+    // v4.5 Wave-1 fix (I4): merge the child pid into the pre-seeded wave metadata
+    // so crash detection can probe pid-bearing records (absent pid = unreapable phantom).
+    if (child && child.pid) {
+      try {
+        const m = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8'));
+        Object.assign(m, { pid: child.pid });
+        writeFileAtomic(path.join(waveDir, 'metadata.json'), JSON.stringify(m, null, 2), { mode: 0o600 });
+      } catch { /* best-effort: metadata already has no pid */ }
+    }
     // Task 15 (spec §5.3): the run is now known-launched under waveId — mark
     // it for a best-effort terminal notify. runWait's poll loop (mcp-wait.js)
     // is the only code that later sees this wave reach terminal state.
@@ -1160,7 +1350,13 @@ const handlers = {
         'replaces polling; re-call it while it returns timedOut: true. Fallback: poll amicus_status ' +
         'with the waveId. Either way, amicus_read the waveId when complete.',
     }));
-    return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
+    const waveContent = [{ type: 'text', text: body }];
+    // v4.5 Task 15: pack notices (e.g. a bench-override) are non-fatal —
+    // surfaced as extra content blocks, same precedent as amicus_start's
+    // routeResult.notice handling above.
+    for (const n of packNotices) { waveContent.push({ type: 'text', text: n }); }
+    waveContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
+    return { content: waveContent };
   },
 
   async amicus_council_tally(input) {

package/src/mcp-tools.js

@@ -71,12 +71,12 @@ function getTools() {
         'files of interest, success criteria.'
       ),
       agent: z.enum(['Chat', 'Plan', 'Build']).optional()
-        .default('Chat').describe(
+        .describe(
           'Agent mode. Chat (interactive default; headless runs auto-convert ' +
           'to Build): reads auto, writes ask permission. Plan: read-only ' +
           'analysis. Build: full auto (all operations approved).'
         ),
-      noUi: z.boolean().optional().default(false).describe(
+      noUi: z.boolean().optional().describe(
         'Run headless without GUI. Default false (opens Electron window).'
       ),
       thinking: z.enum([
@@ -101,7 +101,7 @@ function getTools() {
         'Fold summary verbosity. brief: key findings only. normal (default): full ' +
         'structured output. verbose: maximum detail.'
       ),
-      includeContext: z.boolean().optional().default(true).describe(
+      includeContext: z.boolean().optional().describe(
         'Whether to include parent conversation history as context. '
         + 'Default: true. Set to false when the briefing is self-contained '
         + 'and does not depend on prior conversation. See amicus_guide for guidance.'
@@ -120,6 +120,7 @@ function getTools() {
           'right (default): flush against the right edge. ' +
           'left: flush against the left edge. center: centered.'
         ),
+      pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -350,8 +351,9 @@ function getTools() {
       summaryLength: z.enum(['brief', 'normal', 'verbose']).optional().describe(
         'Summary verbosity for every leg.'
       ),
-      includeContext: z.boolean().optional().default(true).describe(
-        'Include parent conversation context (built once, shared by all legs). Set false for self-contained briefings.'
+      includeContext: z.boolean().optional().describe(
+        'Include parent conversation context (built once, shared by all legs). ' +
+        'Default: true. Set false for self-contained briefings.'
       ),
       coworkProcess: z.string().optional().describe(
         'Cowork VM process name (e.g., "modest-laughing-goodall"). ' +
@@ -366,6 +368,7 @@ function getTools() {
         'finishes (best-effort; amicus_wait remains the reliable completion mechanism). Exec ' +
         'commands are NOT accepted over MCP.'
       ),
+      pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -497,6 +500,13 @@ function getTools() {
         'finishes (best-effort; amicus_wait remains the reliable completion mechanism). Exec ' +
         'commands are NOT accepted over MCP.'
       ),
+      pack: z.string().optional().describe('Policy pack name or path — bench/chair/options/template defaults for this run; explicit params override pack values (recorded either way).'),
+      ui: z.boolean().optional().describe(
+        'Auto-open the Council Workspace window on this run. Default: opens when the client is ' +
+        'Claude Code (local), Electron is installed, a display exists, and config workspace.autoOpen is ' +
+        'not false. false: never open. true: open even for other clients (still requires Electron + ' +
+        'a display; never installs).'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),

package/src/observe/council-legs.js

@@ -34,6 +34,7 @@ const path = require('path');
 const { readProgress, isStalled } = require('../sidecar/progress');
 const { enrichLegUsage, TERMINAL } = require('./live-doc');
 const { roleFor } = require('../council/run-stages');
+const { logger } = require('../utils/logger');
 
 /**
  * A leg's council role. The chair stage is the one case alias identity
@@ -54,6 +55,37 @@ const { roleFor } = require('../council/run-stages');
 function legRole({ bench, critic, lenses, stageName, modelInput }) {
   if (!modelInput) { return null; }
   if (stageName === 'chair') { return 'chair'; }
+  // ⚠️ v4.4.1 LC-4: roleFor's LENS branch does `o.models.indexOf(alias)`, so a
+  // run.json carrying truthy `lenses` with a missing or non-array `bench` throws
+  // a TypeError. This function runs on every status poll, so one malformed
+  // run.json took out three surfaces at once: `amicus status`, the amicus_status
+  // MCP tool, and `amicus watch`. It was unreachable only because
+  // src/council/run.js:72 happens to write `bench` and `lenses` together — an
+  // argument that rests entirely on one writer never changing.
+  //
+  // A role we cannot compute is `null` — the module's existing, documented
+  // degradation (an em-dash in the Role column), never a guess and never a
+  // throw. The non-lens branch never touches `models`, so it stays exact.
+  //
+  // ⚠️ v4.4.1 A2: the guard above was ASYMMETRIC — it validated `bench` and took `lenses` on
+  // trust, but roleFor's lens branch indexes BOTH (`o.lenses[o.models.indexOf(alias)]`). Neither
+  // remaining shape throws, because slug() coerces with String(), so both produced a confident
+  // LIE instead of a crash: `lenses: 'security'` with `bench: ['gpt']` indexes the STRING and
+  // yields `lens:s`, and a `lenses` array shorter than `bench` yields `lens:undefined`. The
+  // length pairing is a real, enforced invariant, not an assumption — cli-handlers-council-run.js:170
+  // refuses `--lenses` unless it has exactly one lens per seat — so a run.json that violates it is
+  // malformed, and the honest answer for a malformed pairing is the same `null` (an em-dash in the
+  // Role column) that LC-4 established, never a guess.
+  if (lenses && (!Array.isArray(bench) || !Array.isArray(lenses) || lenses.length !== bench.length)) {
+    logger.debug('leg role unresolved: run.json lenses/bench are not a matched pair', {
+      modelInput, stageName,
+      benchType: bench === null ? 'null' : typeof bench,
+      lensesType: lenses === null ? 'null' : typeof lenses,
+      benchLength: Array.isArray(bench) ? bench.length : null,
+      lensesLength: Array.isArray(lenses) ? lenses.length : null,
+    });
+    return null;
+  }
   return roleFor({ models: bench, critic, lenses }, modelInput);
 }
 
@@ -71,15 +103,30 @@ function buildLegRow(project, legId, runCtx) {
   const { getSessionDir } = require('../session-manager');
   const legDir = getSessionDir(project, legId);
   let meta = {};
+  // ⚠️ v4.4.1 LC-9: the catch stays ALL-OR-NOTHING on purpose (Appendix A-9) —
+  // it mirrors the wave branch, and a half-parsed metadata object is worse than
+  // an empty one. What was wrong was the SILENCE: a corrupt metadata.json, an
+  // EACCES on the leg dir, and "the file doesn't exist yet" were indistinguishable
+  // and left no trace anywhere, so a leg with corrupt metadata rendered as a
+  // just-started leg forever. `code` is what separates them — ENOENT is the
+  // ordinary just-started case, anything else is a real fault. Logging only; the
+  // branching is untouched.
   try { meta = JSON.parse(fs.readFileSync(path.join(legDir, 'metadata.json'), 'utf-8')); }
-  catch { /* leg metadata not written yet — just-started leg */ }
+  catch (metaErr) {
+    logger.debug('leg metadata.json unreadable — rendering the leg with base fields only', {
+      legId, code: metaErr.code || null, error: metaErr.message,
+    });
+  }
   // Truthful null, never metadata.model as a fallback: showing the resolved
   // id where the alias was expected is exactly the F36 bug (blind mode would
   // leak the real model id instead of degrading to an em-dash).
   const modelInput = meta.modelInput || null;
+  // LC-4: hoisted out of the object literal below so the guard inside legRole is
+  // the only thing standing between a malformed run.json and three live surfaces.
+  const role = legRole({ ...runCtx, modelInput });
   const row = {
     taskId: legId, model: meta.model || null, status: meta.status || 'unknown',
-    modelInput, role: legRole({ ...runCtx, modelInput }),
+    modelInput, role,
   };
   let stalledMs = null;
   let p = null;
@@ -91,7 +138,17 @@ function buildLegRow(project, legId, runCtx) {
     row.lastActivityAt = p.lastActivityAt;
     row.stalled = row.status === 'running' && isStalled(p.lastActivityMs);
     if (row.stalled) { stalledMs = p.lastActivityMs; }
-  } catch { /* no progress.json yet — a just-started leg; base fields only. */ }
+  } catch (progressErr) {
+    // ⚠️ v4.4.1 LC-9: same deal as the metadata catch above — all-or-nothing by
+    // design (A-9), silent by accident. readProgress swallows a malformed
+    // progress.json itself, so reaching here means the leg DIR could not be
+    // stat'd/read at all (EACCES, a vanished session dir) or readProgress threw
+    // on a shape it could not handle — neither of which is "hasn't started yet",
+    // and both of which previously left the row indistinguishable from one.
+    logger.debug('leg progress unreadable — rendering the leg with base fields only', {
+      legId, code: progressErr.code || null, error: progressErr.message,
+    });
+  }
 
   // council review C3: this is a SEPARATE try from readProgress's above, on
   // purpose. The old code wrapped both in one try, so a pricing-resolution

package/src/observe/live-doc.js

@@ -15,7 +15,24 @@
 
 const { resolveUsage, sumWaveUsage } = require('../utils/pricing');
 
-const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'idle-timeout']);
+// ⚠️ v4.4.1 A1: 'timeout' AND 'timed-out' — the codebase genuinely has two spellings for one
+// state, written by two different producers, and this set has to cover both.
+//   'timeout'   — src/utils/result-schema.js:23 statusFromResult, i.e. the LEG/wave-document and
+//                 `--json` run-document vocabulary. Correct, still emitted, stays.
+//   'timed-out' — src/sidecar/session-finalize.js:21 resolveTerminalState, i.e. what actually
+//                 lands in a session's metadata.json `status` and (since LC-3) progress.json's
+//                 terminal stage. It was MISSING here, and this set is the one every observability
+//                 reader consults, so three real consequences followed: `amicus watch <taskId>` on
+//                 a timed-out single session never exited (watch-render.js:138 polls until
+//                 TERMINAL.has(doc.status), and amicus_status stamps metadata.status straight onto
+//                 the doc — mcp-server.js:687); a timed-out leg skipped the "prefer metadata.usage
+//                 over the stale progress.json snapshot" branch in council-legs.js:162 and reported
+//                 an under-counted cost; and markLive kept stamping view:'live' on a finished
+//                 single-session doc.
+// NOTE this is deliberately NOT the same list as src/utils/result-schema.js:13 TERMINAL_STATUSES
+// (the leg set, no 'partial'). Two mirrors of THIS list exist — src/workspace/run-detail.js:26 and
+// electron/workspace-ui/live-model.js:14 — byte-identical, held by drift pins. Edit all three.
+const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'timed-out', 'idle-timeout']);
 
 /**
  * Attach read-time-resolved usage to a leg from its raw progress usage.

package/src/observe/watch-render.js

@@ -29,7 +29,10 @@ const legCost = (leg) => (leg.usage && leg.usage.cost ? formatCost(leg.usage.cos
 const legTokens = (leg) => (leg.usage && leg.usage.tokens ? `${leg.usage.tokens.input || 0}/${leg.usage.tokens.output || 0}` : DASH);
 const truncate = (s, n) => { const t = String(s || ''); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
 
-const STAGE_MARK = { complete: '✓', running: '▶', pending: '·' };
+// `partial` (v4.4.1 F6): a stage that FINISHED but lost seats. Without its own
+// mark it fell through to `pending`, so a degraded Stage 1 rendered as if it had
+// not started — the opposite of reporting loudly.
+const STAGE_MARK = { complete: '✓', running: '▶', partial: '⚠', pending: '·' };
 
 /** The in-place refresh block for a composed wave/council/solo doc. */
 function renderTable(doc, width = 100) {

package/src/pack/pack-cli.js

@@ -0,0 +1,38 @@
+// src/pack/pack-cli.js
+'use strict';
+
+/**
+ * @module pack/pack-cli
+ * v4.5 Task 13: shared --pack CLI wiring for handleFanout and handleStart
+ * (src/cli-handlers-run.js). Task 12 wired handleCouncilRun's pack block
+ * inline; fanout/start need the identical resolve-or-exit shape at TWO call
+ * sites in the SAME file, which would push cli-handlers-run.js over the
+ * 300-line size gate — extracted here instead. Deliberately excludes
+ * council's packSuffix helper: neither fanout nor start has a
+ * chair/critic/lenses pre-flight to attribute a failure to (Task-12 reviewer
+ * confirmed no analog is needed here).
+ */
+
+const { applyPackToArgs } = require('./pack-resolve');
+const { failJson } = require('../utils/error-doc');
+
+/**
+ * Resolve `args.pack` (when present) into `args`, in place, using
+ * cli-handlers-run.js's own exit-on-error style (`process.exit(failJson(...))`)
+ * rather than handleCouncilRun's `return failJson(...)`. A no-op — returns
+ * null without touching `args` or exiting — when --pack was not passed.
+ * @param {object} args - parsed CLI args; explicit-flag keys read from args.__explicit
+ * @param {'fanout'|'solo'} expectedKind
+ * @param {boolean} useJson
+ * @returns {{name: string, version: string, hash: string, source: string}|null}
+ */
+function applyPackOrExit(args, expectedKind, useJson) {
+  if (args.pack === undefined) { return null; }
+  const explicit = args.__explicit || new Set();
+  const pr = applyPackToArgs({ packRef: args.pack, expectedKind, args, explicit, useJson });
+  if (pr.error) { process.exit(failJson(useJson, pr.error)); }
+  for (const n of pr.notices) { process.stderr.write(n + '\n'); }
+  return pr.packRecord;
+}
+
+module.exports = { applyPackOrExit };