amicus 4.2.0 → 4.3.0

package/src/cli-handlers-watch.js

@@ -0,0 +1,89 @@
+// src/cli-handlers-watch.js
+'use strict';
+
+/**
+ * `amicus watch <id>` (spec 5.1) — render any in-flight (or terminal) run from
+ * any process, reading only the data layer (Surfaces A/B/C). This file owns id
+ * resolution + the command entry; the pure renderers live in
+ * src/observe/watch-render.js (Task 12). No fs.watch — a poll loop over the
+ * composed doc (via handlers.amicus_status) + the events tail.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateTaskId } = require('./utils/validators');
+
+/**
+ * Resolve a watch id to a wave / council / solo target (pure over disk).
+ * Resolution order (spec 5.1): council pointer file -> council; else session
+ * metadata (type:'wave' -> wave, else -> solo); nothing readable -> unknown.
+ * Uses the SAME canonical path builders the rest of the codebase resolves
+ * sessions/pointers with — readPointer (council/run-state.js) and
+ * getSessionDir (session-manager.js) — rather than hand-rolling disk paths,
+ * so watch can never drift from how start/status/council resolve ids.
+ * @param {string} id
+ * @param {string} project
+ * @returns {{kind:'wave'|'council'|'solo'|'unknown', id: string, runDir?: string}}
+ */
+function resolveWatchTarget(id, project) {
+  const clean = String(id).replace(/^council-/, '');
+
+  const { readPointer } = require('./council/run-state');
+  const ptr = readPointer(project, clean);
+  if (ptr) { return { kind: 'council', id: clean, runDir: ptr.runDir }; }
+
+  // getSessionDir THROWS on a path-traversal id ('..' / separators) — this
+  // resolver is exported and docblocked "pure over disk", so it must be
+  // total for arbitrary input, not just for ids that already passed
+  // validateTaskId in the wired CLI path (handleWatch, below). A throw here
+  // (traversal or otherwise) falls through to 'unknown' like any other
+  // unreadable id, rather than propagating out of a "pure" resolver.
+  try {
+    const { getSessionDir } = require('./session-manager');
+    const metaPath = path.join(getSessionDir(project, clean), 'metadata.json');
+    if (fs.existsSync(metaPath)) {
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      return { kind: meta.type === 'wave' ? 'wave' : 'solo', id: clean };
+    }
+  } catch { /* fall through to unknown */ }
+  return { kind: 'unknown', id: clean };
+}
+
+/**
+ * `amicus watch <id> [--json|--plain] [--interval <sec>] [--project <p>] [--ui]`
+ * @param {object} args parsed CLI args
+ * @returns {Promise<number>} exit code (render loop: Task 12)
+ */
+async function handleWatch(args) {
+  const { failJson, ERROR_CODES } = require('./utils/error-doc');
+  const id = args._[1];
+  if (!id || id === true) {
+    process.stderr.write('Error: id is required for watch\nUsage: amicus watch <id> [--json] [--plain] [--interval <sec>]\n');
+    return 1;
+  }
+  const check = validateTaskId(String(id));
+  if (!check.valid) { process.stderr.write(`${check.error}\n`); return 1; }
+
+  // --ui is registered as the v4.4 Council Workspace seam only; this rev
+  // (v4.3) registers the flag + this fail-fast, the GUI itself is out of
+  // scope. --ui alone is accepted and falls through to the loop.
+  if (args.ui && args.json) {
+    process.stderr.write('Error: --ui is interactive-only and cannot be combined with --json\n');
+    return 1;
+  }
+
+  const project = args.project || args.cwd || process.cwd();
+  const target = resolveWatchTarget(String(id), project);
+  if (target.kind === 'unknown') {
+    return failJson(!!args.json, {
+      code: ERROR_CODES.BAD_SESSION,
+      message: `watch: id '${id}' not found or unreadable in ${project}`,
+      hint: 'Pass --project if the run was launched elsewhere.',
+    });
+  }
+
+  const { runWatchLoop } = require('./observe/watch-render');
+  return runWatchLoop(target, args, project);
+}
+
+module.exports = { handleWatch, resolveWatchTarget };

package/src/cli.js

@@ -143,6 +143,12 @@ function isBooleanFlag(key) {
      'render',               // council verdict: also refresh report.html next to the decided verdict
      'claude',               // init: register for Claude Code only (Task 15)
      'desktop',              // init: register for Claude Desktop only (Task 15)
+     'failed',               // spend: only non-complete (wasted) rows (v4.3 Task 4, spec §7.3)
+     'rows',                 // spend: include matching raw rows, capped at 1000 (v4.3 Task 4)
+     'plain',                // watch: milestone log lines instead of the refresh table (v4.3 Task 11)
+     'ui',                   // watch: open the Council Workspace window; v4.4 seam (v4.3 Task 11)
+     'follow',               // fanout / council run: stream this run's own events to stderr (v4.3 Task 13)
+     'fallback',             // fanout / council run: opt-in cheaper-model substitution (v4.3 Task 18, spec 6.2); --no-fallback negates via the generic no-* catch-all below
    ];
   return booleanFlags.includes(key);
 }
@@ -369,6 +375,7 @@ Commands:
   council verdict <tally.json> [--decisions <d.json>] [-o <out.json>]   Build + write verdict.json
   doctor      Check your setup: keys, catalog, binary, skills, MCP (--json)
   spend [--since 7d] [--json]           Cross-run cost rollup from the spend ledger
+  watch <id> [--json] [--plain] [--interval <sec>]   Live-render a run from any terminal
   abort       Abort a running session (or --all)
   setup       Configure default model and aliases
     --api-keys               Open API key setup window
@@ -431,10 +438,27 @@ Options for 'fanout':
                                ~32KB Windows argument cap). Mutually exclusive
                                with --prompt. Also works with 'start'.
   --wave-id <id>               Explicit wave ID (leg IDs become <id>-1..N)
+  --retry-failed <waveId>       Relaunch ONLY that wave's failed/timed-out/crashed/
+                                aborted legs as a NEW linked wave, using each leg's
+                                own saved context (byte-identical retry). Skips
+                                --prompt/--models; --models filters which failed
+                                legs to retry. wave.json is never modified.
   --json                       Emit the wave result as stable JSON on stdout
   --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
   --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
+  --fallback / --no-fallback   Opt-in cheaper-model substitution on a classified
+                               rate-limit/overload leg failure (spec 6.2). Overrides
+                               config fallbacks.enabled when passed; default: config, else off.
   --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
+  --follow                      Stream this run's events to stderr as they happen (--json -> NDJSON)
+  --on-complete <cmd>           Run a shell command once, at terminal state, after
+                                wave.json is durable. The command is user-authored
+                                on THIS command line (CLI-only — never sourced from
+                                config/briefings/model output); payload rides via
+                                env only (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/
+                                RESULT_FILE/EVENTS_FILE/COST/PROJECT), never model
+                                text. Child stdout/stderr go to amicus stderr.
+                                Never changes the wave's exit code, docs, or events.
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
@@ -519,7 +543,8 @@ Subcommands for 'council':
       [--chair <model>] [--critic <model>] [--lenses s1,s2,...]
       [--out-dir <dir>] [--json] [--max-cost <usd>] [--timeout <min>]
       [--gateway auto|direct|openrouter] [--no-validate-model]
-      [--debate] [--claude-review <file>] [--no-cost-gate]
+      [--debate] [--claude-review <file>] [--no-cost-gate] [--follow]
+      [--fallback] [--no-fallback] [--on-complete <cmd>]
                                 Run the full headless council engine (v4.0).
                                 Chair default: deepseek (must NOT be a bench seat).
                                 --critic and --lenses are mutually exclusive.
@@ -527,6 +552,21 @@ Subcommands for 'council':
                                 --claude-review <file> enters Claude's own review as
                                 a judged entry; --no-cost-gate disables the per-leg
                                 price gate for the whole run (repairs + chair).
+                                --fallback/--no-fallback opts stage legs (Stage-1 +
+                                Stage-2) into cheaper-model substitution on a
+                                classified rate-limit/overload failure (spec 6.2);
+                                the chair never substitutes via chains.
+                                --follow streams run events to stderr as they
+                                happen (--json -> NDJSON).
+                                --on-complete <cmd> runs a shell command once, at
+                                terminal state, after run.json is durable. The
+                                command is user-authored on THIS command line
+                                (CLI-only — never sourced from config/briefings/
+                                model output); payload rides via env only
+                                (AMICUS_TASK_ID/TYPE/STATUS/EXIT_CODE/RESULT_FILE/
+                                EVENTS_FILE/COST/PROJECT), never model text. Child
+                                stdout/stderr go to amicus stderr. Never changes
+                                the run's exit code, docs, or events.
                                 Exit: 0 full run, 2 degraded, 1 quorum/cost/validation.
   save <name> --models a,b,c    Save a named council preset (>=2 resolvable members)
     --json                     Machine-readable output
@@ -544,9 +584,26 @@ Options for 'doctor':
   spend: `
 Options for 'spend':
   --since <Nd>                  Restrict to the last N days (e.g. --since 7d)
+  --wave <id>                   Only rows from this fan-out wave
+  --council <runId|name>        Only rows from this council run (id or preset name)
+  --project <path|.>            Only rows from this project ('.' = cwd)
+  --model <id-or-prefix>        Only rows whose model starts with this
+  --op <start|continue|resume|leg>   Only rows with this operation
+  --failed                      Only non-complete (wasted) rows
+  --group-by <model|wave|council|project|op|day>   Rollup dimension (default model)
+  --rows                        Include matching raw rows (capped at 1000)
   --json                        Machine-readable output (versioned spend doc)
   Reads ~/.config/amicus/spend-ledger.jsonl (one row per completed run/leg).
   Shows remaining OpenRouter credit when a key is configured.
+`,
+  watch: `
+Options for 'watch':
+  <id>                          A fan-out wave id, council run id, or session id
+  --project <path>              Project the run was launched in (default cwd)
+  --interval <sec>              Refresh interval (default 2, floor 0.5)
+  --plain                       Milestone log lines instead of the refresh table
+  --json                        NDJSON: tailed events + composed doc on change + final doc
+  --ui                          Open the Council Workspace window (v4.4; interactive-only)
 `,
   setup: `
 Options for 'setup':

package/src/council/run-chair.js

@@ -19,6 +19,7 @@ const stage2 = require('./briefings-stage2');
 const { parseChairVerdict } = require('./parse-stage2');
 const runState = require('./run-state');
 const { isAbortExit } = require('./run-stages');
+const { emitStageStarted, emitStageTerminal } = require('../observe/events');
 
 /**
  * Chair fallback promotion (spec §4): the highest peers-only street-cred
@@ -68,6 +69,9 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       // below are the launches a re-armed price gate would refuse LAST, after
       // the whole bench has already been paid for.
       noCostGate: o.noCostGate,
+      // v4.3 Task 3 (spec §7.2 named defect): without this, chair spend is
+      // ledgered with councilRunId:null and is unattributable.
+      councilRunId: o.runId, councilName: o.councilName,
     });
     addWave(solo.wave);
     const ok = solo.leg && solo.leg.status === 'complete'
@@ -83,8 +87,10 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
     // Never abort in-flight legs for cost — this only stops NEW launches.
     degraded.value = true;
     runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'chair', 'skipped', null, o.follow);
   } else {
     runState.updateStage(o.runDir, 'chair', { status: 'running', startedAt: now(), project: o.runDir });
+    emitStageStarted(o.runDir, o.runId, 'chair', null, o.follow);
     // Fallback chain (spec §4): retry same chair once → promote best
     // non-bench model from the ledger → give up (no Claude fallback headless).
     let attempt = await attemptChair(o.chair, `${o.runId}-ch1`);
@@ -105,8 +111,9 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       }
     }
     chairLeg = attempt.leg;
-    runState.updateStage(o.runDir, 'chair',
-      { status: chairLeg ? 'complete' : 'error', completedAt: now() });
+    const chairStatus = chairLeg ? 'complete' : 'error';
+    runState.updateStage(o.runDir, 'chair', { status: chairStatus, completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'chair', chairStatus, null, o.follow);
     // The chair chain may have promoted a fallback (or given up) — checkpoint
     // the ACTUAL chair into run.json now so status/`--json`/the human summary
     // never report the originally-requested chair after a promotion. Mirrors
@@ -126,6 +133,7 @@ async function runChair(ctx, { packet, degraded, statsFn, isSignalled }) {
       project: o.runDir, waveId: `${o.runId}-ch4`,
       timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
       noCostGate: o.noCostGate,
+      councilRunId: o.runId, councilName: o.councilName,
     });
     addWave(repair.wave);
     if (isAbortExit(repair.exitCode) || isSignalled()) { return bail(repair.exitCode || isSignalled()); }

package/src/council/run-debate.js

@@ -18,6 +18,7 @@ const { materializeDebate } = require('./run-launch');
 const { tally } = require('./tally');
 const { isAbortExit } = require('./run-stages');
 const runState = require('./run-state');
+const { emitStageStarted } = require('../observe/events');
 
 /** Spec §5.7 fallback: a dead/unparseable defense means every bundled id's original stands. */
 function allNoResponse(ids) {
@@ -65,7 +66,9 @@ function debateTargets(provisionalRecord, tallyInput) {
 /** Common launch options for every debate leg (judge-isolated `_scratch` cwd). */
 function legOpts(ctx, waveId) {
   return { project: ctx.scratchDir, waveId, timeout: ctx.o.timeout, gateway: ctx.o.gateway,
-    noValidateModel: ctx.o.noValidateModel, noCostGate: ctx.o.noCostGate };
+    noValidateModel: ctx.o.noValidateModel, noCostGate: ctx.o.noCostGate,
+    // v4.3 Task 3 (spec §7.2): attribution ids for every defense/re-vote leg.
+    councilRunId: ctx.o.runId, councilName: ctx.o.councilName };
 }
 
 async function runDefenseSolo(ctx, raiser, findings, idx) {
@@ -121,6 +124,7 @@ async function runRevoteWave(ctx, judges, bundleFindings) {
   // nothing was defended/amended, or the cost ceiling hit).
   runState.updateStage(ctx.o.runDir, 'debate-revote',
     { status: 'running', startedAt: new Date().toISOString(), project: ctx.scratchDir, waveId });
+  emitStageStarted(ctx.o.runDir, ctx.o.runId, 'debate-revote', waveId, ctx.o.follow);
   runState.appendStageWave(ctx.o.runDir, 'debate-revote', waveId);
   const res = await ctx.launchers.launchWave({ ...legOpts(ctx, waveId), models: judges, prompt: bundle });
   ctx.addWave(res.wave);

package/src/council/run-launch.js

@@ -26,7 +26,13 @@ function createLaunchers(deps = {}) {
 
   /**
    * @param {{models: string[], prompt: string, project: string, waveId: string,
-   *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string}} opts
+   *   timeout?: number, gateway?: string, noValidateModel?: boolean, agent?: string,
+   *   councilRunId?: string, councilName?: string, fallback?: object, catalog?: Array}} opts
+   *   councilRunId/councilName (v4.3 Task 3, spec §7.2) are additive attribution
+   *   ids forwarded verbatim into the runFanout call so it can stamp them onto
+   *   every leg. fallback/catalog (v4.3 Task 18, spec §6.2) are likewise
+   *   additive/opt-in — omitted by callers that must never substitute (the
+   *   chair, debate legs); run-stages.js's Stage-1/Stage-2 launches pass them.
    * @returns {Promise<{wave: object|null, exitCode: number}>}
    */
   async function launchWave(opts) {
@@ -43,6 +49,13 @@ function createLaunchers(deps = {}) {
       includeContext: false,
       gatewayMode: opts.gateway,
       noValidateModel: opts.noValidateModel,
+      councilRunId: opts.councilRunId,
+      councilName: opts.councilName,
+      // v4.3 Task 18 (spec §6.2): additive/opt-in. Callers that must never
+      // substitute (run-chair.js, run-debate.js) simply omit these — runLeg's
+      // fallback path only activates when `fallback.enabled` is true.
+      fallback: opts.fallback,
+      catalog: opts.catalog,
       // v4.1 §4.5d: `--no-cost-gate` is a WHOLE-RUN opt-out (an intentional
       // o3-class council), so it has to ride every council launch — otherwise
       // fanout's per-$/Mtok gate refuses the first repair or the chair

package/src/council/run-stages.js

@@ -41,6 +41,13 @@ async function launchStage1(ctx) {
   const common = {
     project: o.runDir, timeout: o.timeout, gateway: o.gateway,
     noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+    // v4.3 Task 3 (spec §7.2): attribution ids, forwarded verbatim to runFanout
+    // via run-launch.js so every Stage-1 leg's ledger row carries them.
+    councilRunId: o.runId, councilName: o.councilName,
+    // v4.3 Task 18 (spec §6.2): fallback chains apply to STAGE legs only —
+    // the chair (run-chair.js) and debate legs (run-debate.js) never receive
+    // this, so they never substitute via chains.
+    fallback: o.fallback, catalog: o.catalog,
   };
   const launches = [];
   // Record every sub-wave BEFORE it launches: `amicus abort` cascades over
@@ -121,6 +128,8 @@ async function runStage1(ctx) {
         model: m.modelInput, prompt: briefings.buildFindingsRepairPrompt({ errors: res.errors }),
         project: o.runDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+        councilRunId: o.runId, councilName: o.councilName,
+        fallback: o.fallback, catalog: o.catalog,
       });
       ctx.addWave(solo.wave);
       if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, reviews, deadLegs }; }
@@ -170,6 +179,8 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
     models: judges, prompt: bundle, project: ctx.scratchDir, waveId: `${o.runId}-s2`,
     timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
     noCostGate: o.noCostGate,
+    councilRunId: o.runId, councilName: o.councilName,
+    fallback: o.fallback, catalog: o.catalog,
   });
   ctx.addWave(wave);
   if (isAbortExit(exitCode)) { return { aborted: exitCode, judgeResults: [] }; }
@@ -195,6 +206,8 @@ async function runStage2(ctx, { reviews, labels, globalFindings, extraLabeled =
         model: judge, prompt: stage2.buildJudgeRepairPrompt({ errors: parsed.errors }),
         project: ctx.scratchDir, waveId, timeout: o.timeout,
         gateway: o.gateway, noValidateModel: o.noValidateModel, noCostGate: o.noCostGate,
+        councilRunId: o.runId, councilName: o.councilName,
+        fallback: o.fallback, catalog: o.catalog,
       });
       ctx.addWave(solo.wave);
       if (isAbortExit(solo.exitCode)) { return { aborted: solo.exitCode, judgeResults }; }

package/src/council/run.js

@@ -32,18 +32,26 @@ const { buildDebateAddendum } = require('./briefings-debate');
 const { decorateRecord } = require('./debate');
 const asm = require('./run-assemble');
 const { sumWaveUsage } = require('../utils/pricing');
+const { emitRunStarted, emitRunTerminal, emitStageStarted, emitStageTerminal } = require('../observe/events');
+const { fireCouncilOnComplete } = require('../observe/on-complete');
 
 const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGBREAK: 143 };
 
 /**
  * @param {object} options {briefing, models, chair, critic?, lenses?, project, runId,
- *   runDir, timeout?, maxCost?, gateway?, noValidateModel?, date, debate?, noCostGate?}
+ *   runDir, timeout?, maxCost?, gateway?, noValidateModel?, date, debate?, noCostGate?,
+ *   councilName?, fallback?, catalog?} councilName (v4.3 Task 3) = preset name when
+ *   launched via `--council <preset>`, else null — threaded via ctx.o into every
+ *   launchWave/launchSolo for leg ledger attribution. fallback/catalog (v4.3 Task 18
+ *   §6.2): ctx.o carries both, but only run-stages.js's stage launches read them —
+ *   the chair/debate legs never substitute via chains.
  * @param {object} [deps] {launchers?, appendRunFn?, statsFn?, installSignalAbortFn?}
  * @returns {Promise<{exitCode: number, run: object}>}
  */
 async function runCouncil(options, deps = {}) {
   const o = { critic: null, lenses: null, maxCost: null, debate: false, claudeReviewFile: null,
-    noCostGate: false, ...options };
+    noCostGate: false, councilName: null, ...options };
+  o.follow = o.follow ? require('../observe/follow').createFollowPrinter({ json: o.json }) : null; // Task 13: stderr mirror
   const launchers = deps.launchers || createLaunchers();
   const appendRunFn = deps.appendRunFn || require('./ledger').appendRun;
   const statsFn = deps.statsFn || require('./ledger').deriveReliability;
@@ -71,6 +79,7 @@ async function runCouncil(options, deps = {}) {
     usage: null, pid: process.pid, createdAt: now(),
   });
   runState.writePointer(o.project, o.runId, o.runDir);
+  emitRunStarted(o.runDir, o.runId, { bench: o.models, chair: o.chair }, o.follow);
 
   let signalled = null;
   const uninstall = installSignals({
@@ -81,7 +90,7 @@ async function runCouncil(options, deps = {}) {
   });
 
   const degraded = { value: false };
-  const finalize = (exitCode, error) => {
+  const finalize = async (exitCode, error) => {
     uninstall();
     const code = signalled || exitCode;
     const status = (code === 130 || code === 143) ? 'aborted'
@@ -91,6 +100,8 @@ async function runCouncil(options, deps = {}) {
       usage: { cost: sumWaveUsage(allLegs).cost },
       completedAt: now(),
     });
+    emitRunTerminal(o.runDir, o.runId, status, code, o.follow);
+    await fireCouncilOnComplete(o.onComplete, run, { runId: o.runId, runDir: o.runDir, exitCode: code, project: o.project }, o.onCompleteDeps);
     return { exitCode: code, run };
   };
 
@@ -116,11 +127,13 @@ async function runCouncil(options, deps = {}) {
       status: 'running', startedAt: now(), project: o.runDir,
       ...(o.lenses ? {} : { waveId: `${o.runId}-s1` }),
     });
+    emitStageStarted(o.runDir, o.runId, 'stage1', o.lenses ? null : `${o.runId}-s1`, o.follow);
     const s1 = await runStage1(ctx);
     runState.updateStage(o.runDir, 'stage1', {
       status: 'complete', completedAt: now(),
       taskIds: s1.reviews.map(r => (r.leg && r.leg.taskId)).filter(Boolean),
     });
+    emitStageTerminal(o.runDir, o.runId, 'stage1', 'complete', o.lenses ? null : `${o.runId}-s1`, o.follow);
     if (signalled || s1.aborted) { return finalize(s1.aborted || signalled); }
     if (s1.deadLegs.length > 0) { degraded.value = true; } // bench shrank → never a "full run"
     if (s1.reviews.length < 2) {
@@ -151,9 +164,11 @@ async function runCouncil(options, deps = {}) {
       .concat(claudeReview ? asm.labelClaudeReview(claudeReview, labels) : []);
     runState.updateStage(o.runDir, 'stage2',
       { status: 'running', startedAt: now(), waveId: `${o.runId}-s2`, project: ctx.scratchDir });
+    emitStageStarted(o.runDir, o.runId, 'stage2', `${o.runId}-s2`, o.follow);
     const s2 = await runStage2(ctx, { reviews: s1.reviews, labels, globalFindings,
       extraLabeled: claudeReview ? [{ label: claudeReview.label, text: claudeReview.text }] : [] });
     runState.updateStage(o.runDir, 'stage2', { status: 'complete', completedAt: now() });
+    emitStageTerminal(o.runDir, o.runId, 'stage2', 'complete', `${o.runId}-s2`, o.follow);
     if (signalled || s2.aborted) { return finalize(s2.aborted || signalled); }
     if (s2.judgeResults.filter(j => j.ok).length < 2) { degraded.value = true; } // thin cross-review
 
@@ -183,9 +198,12 @@ async function runCouncil(options, deps = {}) {
       // checkpoint — no ledger append, written before any debate leg launches.
       fs.writeFileSync(path.join(o.runDir, 'tally-provisional.json'), JSON.stringify(provisional, null, 2), { mode: 0o600 });
       runState.updateStage(o.runDir, 'tally-provisional', { status: 'complete', startedAt: now(), completedAt: now() });
+      emitStageStarted(o.runDir, o.runId, 'tally-provisional', null, o.follow);
+      emitStageTerminal(o.runDir, o.runId, 'tally-provisional', 'complete', null, o.follow);
       const worthDebating = !runDebateMod.nothingToDebate(provisional);
       if (worthDebating && !overBudget()) {
         runState.updateStage(o.runDir, 'debate-defense', { status: 'running', startedAt: now(), project: ctx.scratchDir });
+        emitStageStarted(o.runDir, o.runId, 'debate-defense', null, o.follow);
         const dbg = await runDebateMod.runDebate(ctx, { provisionalRecord: provisional, tallyInput: provisionalInput });
         // A signal mid-debate aborts finalization: no tally-final, no ledger (spec §5.7). Close
         // the summary FIRST — the writer contract requires a valid `outcome` whenever the key exists.
@@ -195,6 +213,7 @@ async function runCouncil(options, deps = {}) {
           return finalize(dbg.aborted);
         }
         runState.updateStage(o.runDir, 'debate-defense', { status: 'complete', completedAt: now() });
+        emitStageTerminal(o.runDir, o.runId, 'debate-defense', 'complete', null, o.follow);
         // run-debate owns debate-revote's running/waveId/waveIds checkpoint — only it
         // knows whether the wave launched. Never advertise a `-rv` id here: a skipped
         // re-vote would leave the abort cascade chasing the v4.0 lens `-s1` phantom.
@@ -203,6 +222,10 @@ async function runCouncil(options, deps = {}) {
         // work that never happened.
         runState.updateStage(o.runDir, 'debate-revote', dbg.revoteLaunched
           ? { status: 'complete', completedAt: now() } : { status: 'skipped', completedAt: now() });
+        // debate-revote-TERMINAL only — run-debate.js owns the START (spec §4.2 /
+        // v4.3 Task 7 B3 note): only it knows the `-rv` waveId when launched.
+        emitStageTerminal(o.runDir, o.runId, 'debate-revote',
+          dbg.revoteLaunched ? 'complete' : 'skipped', dbg.revoteLaunched ? `${o.runId}-rv` : null, o.follow);
         ({ debatedInput, debateFindings, debateSummary } = dbg);
         debatedRecord = tally(debatedInput);
         // Defensive truthiness guard: `[]` is truthy in JS, so an empty outcomes
@@ -258,9 +281,14 @@ async function runCouncil(options, deps = {}) {
       catch (e) { process.stderr.write(`Notice: council ledger append failed: ${e.message}\n`); }
     }
     asm.writeTallyFiles({ runDir: o.runDir, tallyInput: finalInput, record });
-    runState.updateStage(o.runDir, o.debate ? 'tally-final' : 'tally', { status: 'complete', completedAt: now() });
+    const tallyStage = o.debate ? 'tally-final' : 'tally';
+    runState.updateStage(o.runDir, tallyStage, { status: 'complete', completedAt: now() });
+    emitStageStarted(o.runDir, o.runId, tallyStage, null, o.follow);
+    emitStageTerminal(o.runDir, o.runId, tallyStage, 'complete', null, o.follow);
     asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
     runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
+    emitStageStarted(o.runDir, o.runId, 'verdict', null, o.follow);
+    emitStageTerminal(o.runDir, o.runId, 'verdict', 'complete', null, o.follow);
 
     return finalize(degraded.value ? 2 : 0);
   } catch (err) {

package/src/headless.js

@@ -448,7 +448,15 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 
         const mr = mirrorMessages(messages, mirror);
         mr.appendLines.forEach(line => logMessage(conversationPath, line));
-        mr.progressUpdates.forEach(p => writeProgress(sessionDir, p.stage, p.extra));
+        // Surface A (spec §4.1): stamp raw usage on each 'receiving' flush from the
+        // PERSISTENT mirror.usageByMsg Map (accumulated across polls) — NOT
+        // mr.usageByMsg, which doesn't exist on mirrorMessages()'s per-poll delta.
+        // Cost resolution happens at read time (Task 9); the writer stays cheap.
+        const { sumPerMessageUsage } = require('./utils/pricing');
+        mr.progressUpdates.forEach(p => writeProgress(
+          sessionDir, p.stage,
+          p.stage === 'receiving' ? { ...p.extra, usage: sumPerMessageUsage(mirror.usageByMsg) } : p.extra,
+        ));
         const currentAssistantMsgId = mr.currentAssistantMsgId;
         const assistantFinished = mr.assistantFinished;
         if (mr.sessionError) {

package/src/mcp-council-awareness.js

@@ -16,6 +16,7 @@ const fs = require('fs');
 const path = require('path');
 const runState = require('./council/run-state');
 const { RUNNING_VERSION } = require('./utils/version-info');
+const { enrichLegUsage, markLive, rollupWaveUsage } = require('./observe/live-doc');
 
 /**
  * Every wave a stage launched: the primary `waveId` plus the recorded
@@ -58,6 +59,41 @@ function countWaveLegs(project, waveId) {
   return { total: legs.length, complete };
 }
 
+/**
+ * Leg ids recorded on a sub-wave's metadata.json, or [] when the wave record
+ * is absent/malformed. A small sibling to countWaveLegs — kept separate so
+ * that helper's {total, complete} contract (other callers depend on it) isn't
+ * overloaded into returning ids too.
+ * @returns {string[]}
+ */
+function waveLegIds(project, waveId) {
+  const { getSessionDir } = require('./session-manager');
+  let legs;
+  try {
+    legs = JSON.parse(fs.readFileSync(
+      path.join(getSessionDir(project, waveId), 'metadata.json'), 'utf-8')).legs;
+  } catch { return []; }
+  return Array.isArray(legs) ? legs : [];
+}
+
+/**
+ * Read-time cost-by-seat for one leg (A8: progress.json only, never a ledger).
+ * Tolerates a leg with no progress.usage yet — contributes nothing (N3).
+ */
+function legUsage(project, legId) {
+  const { getSessionDir } = require('./session-manager');
+  const { readProgress } = require('./sidecar/progress');
+  let model = null;
+  try {
+    model = JSON.parse(fs.readFileSync(
+      path.join(getSessionDir(project, legId), 'metadata.json'), 'utf-8')).model || null;
+  } catch { /* leg metadata not written yet */ }
+  let progressUsage;
+  try { progressUsage = readProgress(getSessionDir(project, legId)).usage; }
+  catch { /* no progress.json yet */ }
+  return enrichLegUsage({ model }, progressUsage);
+}
+
 function elapsedOf(run) {
   const end = run.completedAt || new Date().toISOString();
   const ms = Math.max(0, new Date(end).getTime() - new Date(run.createdAt || end).getTime());
@@ -94,11 +130,19 @@ function buildCouncilStatusPayload(project, taskId) {
   // Sum across every sub-wave the active stage launched: a lens stage1 has no
   // seat wave at all, and a critic solo runs beside one. Stays null until at
   // least one sub-wave record exists on disk.
+  // Cost-by-seat rides the same loop, read-time from progress.json only (A8) —
+  // usageLegs stays empty (no `usage` on the payload) until a leg has actually
+  // flushed usage; a leg with none yet contributes nothing (N3).
+  const usageLegs = [];
   for (const waveId of active && active.project ? subWaveIds(active) : []) {
     const c = countWaveLegs(active.project, waveId);
     if (!c) { continue; }
     legsTotal = (legsTotal || 0) + c.total;
     legsComplete = (legsComplete || 0) + c.complete;
+    for (const legId of waveLegIds(active.project, waveId)) {
+      const enriched = legUsage(active.project, legId);
+      if (enriched.usage) { usageLegs.push(enriched); }
+    }
   }
   const payload = {
     taskId: run.runId, type: 'council-run', runId: run.runId, runDir: ptr.runDir,
@@ -107,8 +151,9 @@ function buildCouncilStatusPayload(project, taskId) {
     exitCode: run.exitCode !== undefined ? run.exitCode : null,
     version: RUNNING_VERSION,
   };
+  if (usageLegs.length) { payload.usage = rollupWaveUsage(usageLegs); }
   if (run.error) { payload.reason = `${run.error.code}: ${run.error.message}`; }
-  return payload;
+  return markLive(payload);
 }
 
 /** amicus_list entries for every council pointer in the project. */

package/src/mcp-council-run.js

@@ -16,6 +16,7 @@ const path = require('path');
 const runState = require('./council/run-state');
 const { fenceSidecarOutput } = require('./utils/untrusted-fence');
 const { isPathInside } = require('./project-root-allowlist');
+const { validateOnComplete, requestMcpNotify } = require('./mcp-notify');
 
 function textResult(text, isError) {
   const result = { content: [{ type: 'text', text }] };
@@ -23,7 +24,14 @@ function textResult(text, isError) {
   return result;
 }
 
-/** Resolve the bench: models XOR council preset (amicus_fanout parity). */
+/**
+ * Resolve the bench: models XOR council preset (amicus_fanout parity).
+ * Also returns `presetName` (v4.3 Task 3, spec §7.1): the trimmed council
+ * preset name when that branch was taken, else null — this handler always
+ * spawns the CLI child with an already-expanded `--models` list (never
+ * `--council`), so the preset name would otherwise be lost; the caller
+ * forwards it via the internal `--council-name` passthrough instead.
+ */
 function resolveBenchInput(input) {
   const inputModels = Array.isArray(input.models) ? input.models : [];
   const hasModels = inputModels.length > 0;
@@ -34,11 +42,12 @@ function resolveBenchInput(input) {
     const { resolveCouncilMembers } = require('./utils/config');
     const { readCache } = require('./utils/model-catalog');
     const catalog = (readCache() || {}).models || [];
-    const expanded = resolveCouncilMembers(input.council.trim(), catalog);
+    const presetName = input.council.trim();
+    const expanded = resolveCouncilMembers(presetName, catalog);
     if (expanded.error) { return { error: expanded.error }; }
-    return { bench: expanded.models };
+    return { bench: expanded.models, presetName };
   }
-  return { bench: inputModels };
+  return { bench: inputModels, presetName: null };
 }
 
 /**
@@ -49,6 +58,12 @@ function resolveBenchInput(input) {
  * @param {{spawnFn: Function, clientName: string}} helpers injected by mcp-server
  */
 async function handleCouncilRunTool(input, project, helpers) {
+  // Task 15 (spec §5.3): validate onComplete FIRST, before any run dir is
+  // prepared — exec strings are rejected over MCP (the Zod enum on the tool
+  // def already rejects them at the call boundary; this is defense-in-depth
+  // for any caller that bypasses schema validation).
+  const oc = validateOnComplete(input.onComplete);
+  if (!oc.ok) { return textResult(oc.error, true); }
   const CHAIR_DEFAULT = 'deepseek';
   if (typeof input.briefingFile !== 'string' || !input.briefingFile.trim()) {
     return textResult("amicus_council_run requires 'briefingFile' (a path to the briefing).", true);
@@ -62,6 +77,7 @@ async function handleCouncilRunTool(input, project, helpers) {
   const benchRes = resolveBenchInput(input);
   if (benchRes.error) { return textResult(benchRes.error, true); }
   const bench = benchRes.bench;
+  const presetName = benchRes.presetName;
   if (bench.length < 2) { return textResult('A council needs at least 2 seats.', true); }
   const chair = (typeof input.chair === 'string' && input.chair.trim()) ? input.chair.trim() : CHAIR_DEFAULT;
   if (bench.includes(chair)) {
@@ -123,6 +139,10 @@ async function handleCouncilRunTool(input, project, helpers) {
   if (input.timeoutMinutes) { args.push('--timeout', String(input.timeoutMinutes)); }
   if (typeof input.maxCost === 'number') { args.push('--max-cost', String(input.maxCost)); }
   if (input.gateway) { args.push('--gateway', input.gateway); }
+  // v4.3 Task 3 (spec §7.1): the bench above is already expanded, so `--council`
+  // itself is never spawned (it would collide with `--models`) — this internal,
+  // undocumented flag carries the preset NAME through for attribution only.
+  if (presetName) { args.push('--council-name', presetName); }
   // v4.1 §4.5b/§4.5d. claudeReviewFile is resolved against `project` for the same
   // reason outDir is — an MCP client may send a relative path, and the child's cwd
   // is the run dir. Validation of the file itself stays in the spawned engine's
@@ -145,6 +165,10 @@ async function handleCouncilRunTool(input, project, helpers) {
   // read-merge-write has no lock (see run-state.writeSpawnPid).
   try { if (typeof child?.pid === 'number') { runState.writeSpawnPid(runDir, child.pid); } }
   catch { /* best-effort */ }
+  // Task 15 (spec §5.3): the run is now known-launched under runId — mark it
+  // for a best-effort terminal notify. runWait's poll loop (mcp-wait.js) is
+  // the only code that later sees this council run reach terminal state.
+  if (oc.mode === 'mcp-notify') { requestMcpNotify(runId); }
 
   const body = JSON.stringify({
     schemaVersion: 2, type: 'council-run', runId, runDir, status: 'running',