amicus 4.2.1 → 4.4.0

package/src/observe/council-legs.js

@@ -0,0 +1,183 @@
+// src/observe/council-legs.js
+'use strict';
+
+/**
+ * @module observe/council-legs
+ * Per-leg row builder for the composed council live doc
+ * (buildCouncilStatusPayload in src/mcp-council-awareness.js). Split out of
+ * that file to stay under the 300-line gate (DE-ROT Task 0.5, closes F01:
+ * `usageLegs` was computed then discarded — no `legs[]` ever reached the
+ * payload, so the live Seats panel had no data source).
+ *
+ * One row per leg id, built UNCONDITIONALLY: unlike the usage rollup (gated
+ * on `enriched.usage` in buildCouncilStatusPayload), a live seats panel needs
+ * just-started legs — the ones with no usage yet — just as much as priced
+ * ones. Field names mirror the wave branch (src/mcp-server.js:592-608) so
+ * live-normalize.js (Task 14) has one vocabulary to map, not two.
+ *
+ * `modelInput` + `role` (F36/F34 correction): a live leg's `model` is the
+ * RESOLVED executable id (metadata.model), never the council ALIAS that
+ * run.json's bench/chair/critic/lenses and roleFor's rule are keyed on — so
+ * deriving role from `model` is a silent no-op (Role column permanently
+ * em-dash) and blind mode's labelOf(alias) lookup never matches (real model
+ * id leaks). The alias IS on disk per-leg, though: every council leg goes
+ * through src/sidecar/fanout-leg.js's runSingleAttempt, which calls
+ * `writeLegPatch(legDir, { parentWave, modelInput })` synchronously,
+ * immediately after leg creation (fanout-leg.js:101) — well before any
+ * status poll could reasonably observe it missing. So this module reads
+ * `modelInput` straight off the leg's own metadata.json, no run.json join
+ * needed for the alias itself.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readProgress, isStalled } = require('../sidecar/progress');
+const { enrichLegUsage, TERMINAL } = require('./live-doc');
+const { roleFor } = require('../council/run-stages');
+
+/**
+ * A leg's council role. The chair stage is the one case alias identity
+ * cannot resolve: run-chair.js's fallback chain (ch1/ch2 = run.chair's own
+ * alias, ch3 = a DIFFERENT ledger-promoted alias, ch4 = whichever succeeded)
+ * means a chair leg's modelInput does not reliably equal run.json's `chair`
+ * field while the chain is still in flight (that field is only checkpointed
+ * once the WHOLE chain resolves, src/council/run-chair.js:122) — so alias
+ * matching would miss ch3/ch4 mid-run. The stage that owns the leg is the
+ * authoritative signal instead (plan's F34 correction: "derive role from the
+ * stage that owns the leg"). Every other stage (stage1/stage2/debate-*)
+ * reuses roleFor (src/council/run-stages.js) keyed on modelInput — a
+ * model's seat/critic/lens identity is stable whether it's reviewing
+ * (stage1) or judging (stage2), and a repair/debate leg relaunches the SAME
+ * alias as its origin leg, so the identity carries through unchanged.
+ * @returns {string|null} null when modelInput is unknown (truthful — never a guess)
+ */
+function legRole({ bench, critic, lenses, stageName, modelInput }) {
+  if (!modelInput) { return null; }
+  if (stageName === 'chair') { return 'chair'; }
+  return roleFor({ models: bench, critic, lenses }, modelInput);
+}
+
+/**
+ * One composed row for a leg, plus the ms-since-activity behind its `stalled`
+ * flag (or null when not stalled/not yet measurable) so the caller can roll
+ * several legs' staleness into one run-level summary without re-parsing
+ * `lastActivityAt` back into a timestamp.
+ * @param {string} project
+ * @param {string} legId
+ * @param {{bench: string[], critic: string|null, lenses: string[]|null, stageName: string}} runCtx
+ * @returns {{row: object, stalledMs: number|null}}
+ */
+function buildLegRow(project, legId, runCtx) {
+  const { getSessionDir } = require('../session-manager');
+  const legDir = getSessionDir(project, legId);
+  let meta = {};
+  try { meta = JSON.parse(fs.readFileSync(path.join(legDir, 'metadata.json'), 'utf-8')); }
+  catch { /* leg metadata not written yet — just-started leg */ }
+  // 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;
+  const row = {
+    taskId: legId, model: meta.model || null, status: meta.status || 'unknown',
+    modelInput, role: legRole({ ...runCtx, modelInput }),
+  };
+  let stalledMs = null;
+  let p = null;
+  try {
+    p = readProgress(legDir);
+    row.messages = p.messages;
+    row.stage = p.stage;
+    row.latestPreview = p.latestPreview;
+    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. */ }
+
+  // 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
+  // failure (an unknown model, a corrupt catalog row) landed in the exact same
+  // catch as "progress.json doesn't exist yet" — an operator (or the workspace's
+  // cost-by-seat panel) could not tell "pricing lookup failed" from "hasn't
+  // billed yet"; both rendered as a permanently blank cost cell. `usageError`
+  // makes the failure mode truthful and distinguishable, additive to the row
+  // (N3's undefined-key discipline still holds: only set usage/usageError when
+  // there is something to say).
+  //
+  // v4.4 B3 (diagnosis §4/§7.3): for a TERMINAL leg, metadata.json's `usage`
+  // block wins over the progress.json snapshot. progress.json's usage is stamped
+  // ONLY on 'receiving' flushes — which fire on text/tool/reasoning GROWTH, i.e.
+  // always strictly before OpenCode's finalization stamp — so on real paid runs
+  // 31 of 35 legs ended with an all-zero snapshot while metadata.json held
+  // thousands of real tokens and a reported cost. Reading the snapshot for a
+  // finished leg made every completed seat look free in the live doc.
+  // headless.js now also writes a terminal 'complete' progress record carrying
+  // the settled usage, which fixes the DATA; this makes the READER prefer the
+  // authoritative source either way, including for every leg already on disk.
+  // A still-RUNNING leg keeps reading progress.json — metadata.usage does not
+  // exist until the leg finalizes, and read-time resolution is what keeps a live
+  // in-flight cost current (live-doc.js's stated design).
+  if (TERMINAL.has(row.status) && meta.usage && meta.usage.cost) {
+    row.usage = meta.usage;
+  } else if (p && p.usage) {
+    try {
+      const enriched = enrichLegUsage(row, p.usage);
+      if (enriched.usage) { row.usage = enriched.usage; }
+    } catch (err) {
+      row.usageError = err.message;
+    }
+  }
+  return { row, stalledMs };
+}
+
+/**
+ * Rows for every leg id, plus a run-level stall rollup. A council run fans
+ * legs across several parallel sub-waves at once (seat wave, chair chain,
+ * lens/critic solos), so — unlike the single-leg wave branch, which only
+ * ever flags its own row — a run-level banner needs one summary rather than
+ * making the caller inspect every row.
+ *
+ * The rollup means exactly what the workspace's dead-run banner claims ("no
+ * leg activity for Xm — the run may be dead"): the run is stalled only when
+ * EVERY still-running leg is stalled. A single stalled leg alongside another
+ * leg that is actively producing (message/cost climbing) must NOT set the
+ * flag — that was the old (max-based) bug, observed live: `glm` sat stalled
+ * for two minutes while `qwen-coder` was visibly working, and the banner
+ * fired anyway. A leg that has already finished (any non-'running' status)
+ * is terminal — it is excluded from the "every leg" population entirely: it
+ * can neither keep the run "healthy" by counting as active, nor drag it
+ * "dead" by counting as stalled. Per-leg `row.stalled` is untouched by this —
+ * it stays the accurate, per-row signal it already was.
+ *
+ * When the run genuinely is stalled, `stalledForSeconds` is the SHORTEST
+ * idle duration among the stalled running legs, not the longest: that is the
+ * honest answer to "how long has the whole run been quiet" — something was
+ * still happening as recently as the most-recently-active (but still
+ * over-threshold) leg's last activity.
+ * @param {string} project
+ * @param {string[]} legIds
+ * @param {{bench: string[], critic: string|null, lenses: string[]|null, stageName: string}} runCtx
+ *   run.json's alias-valued fields (bench/critic/lenses) + the active stage's
+ *   name, threaded through to legRole — this module never reads run.json itself.
+ * @returns {{rows: object[], stalled?: true, stalledForSeconds?: number}}
+ */
+function buildLegRows(project, legIds, runCtx) {
+  const rows = [];
+  let runningCount = 0;
+  const stalledRunningMs = [];
+  for (const legId of legIds) {
+    const { row, stalledMs } = buildLegRow(project, legId, runCtx);
+    rows.push(row);
+    if (row.status === 'running') {
+      runningCount += 1;
+      if (stalledMs !== null) { stalledRunningMs.push(stalledMs); }
+    }
+  }
+  const out = { rows };
+  if (runningCount > 0 && stalledRunningMs.length === runningCount) {
+    out.stalled = true;
+    out.stalledForSeconds = Math.floor(Math.min(...stalledRunningMs) / 1000);
+  }
+  return out;
+}
+
+module.exports = { buildLegRows };

package/src/observe/events.js

@@ -0,0 +1,156 @@
+// src/observe/events.js
+'use strict';
+
+/**
+ * @module observe/events
+ * Surface B (spec 4.2): the append-only milestone event stream, one
+ * events.jsonl per wave dir / council run dir. Single-writer (the owning
+ * orchestrator) so ordering is trivially correct; a torn final line on a hard
+ * crash is acceptable and skipped by the tail reader (same tradeoff as the two
+ * ledgers). appendEvent NEVER throws (spec 8) — emitting an event must never
+ * fail a wave/leg. The reader is a poll-stat tail: no fs.watch anywhere
+ * (Windows reference platform, spec 3.1).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logger } = require('../utils/logger');
+
+const EVENTS_FILE = 'events.jsonl';
+const EVENTS_SCHEMA_VERSION = 1;
+
+/**
+ * Append one enveloped event line. Best-effort; swallows all failure.
+ * Reserved envelope keys — do not reuse these as payload field names, the
+ * stamped value always wins (spread order): schemaVersion, type, event, ts, id.
+ * @param {string} dir wave/council-run dir
+ * @param {{event:string, id:string}} payload event name + owning id + fields
+ */
+function appendEvent(dir, payload) {
+  try {
+    const { event, id, ...rest } = payload || {};
+    const line = JSON.stringify({
+      schemaVersion: EVENTS_SCHEMA_VERSION, type: 'event',
+      event, ts: new Date().toISOString(), id, ...rest,
+    }) + '\n';
+    fs.appendFileSync(path.join(dir, EVENTS_FILE), line);
+  } catch (e) {
+    logger.debug('events append failed (best-effort, run unaffected)', { error: e.message });
+  }
+}
+
+/**
+ * Create a poll-stat tail over an events file. Returns { poll() } — each call
+ * yields the events appended since the previous call (empty on no growth,
+ * missing file, or a transient open error). Holds an unterminated tail.
+ * @param {string} file absolute path to events.jsonl
+ */
+function createEventTail(file) {
+  let offset = 0;
+  let carry = '';
+  return {
+    poll() {
+      let stat;
+      try { stat = fs.statSync(file); }
+      catch { return []; } // not-yet-exists / transient -> missed tick
+      if (stat.size <= offset) { return []; }
+      let chunk;
+      try {
+        const fd = fs.openSync(file, 'r');
+        try {
+          const buf = Buffer.alloc(stat.size - offset);
+          fs.readSync(fd, buf, 0, buf.length, offset);
+          chunk = buf.toString('utf-8');
+        } finally { fs.closeSync(fd); }
+      } catch { return []; } // EBUSY/EPERM -> missed tick, retry next poll
+      offset = stat.size;
+      const text = carry + chunk;
+      const nl = text.lastIndexOf('\n');
+      if (nl === -1) { carry = text; return []; }
+      carry = text.slice(nl + 1);
+      const out = [];
+      for (const line of text.slice(0, nl).split('\n')) {
+        if (!line.trim()) { continue; }
+        try { out.push(JSON.parse(line)); } catch { /* skip torn/corrupt */ }
+      }
+      return out;
+    },
+  };
+}
+
+// ---- Milestone emit helpers (Task 7, spec 4.2 vocabulary) ----
+// Centralized here (not in fanout.js / run.js / run-chair.js / run-debate.js)
+// per the v4.3 Task 7 structural decision: those four files sit close to the
+// 300-line hard gate, so every call site below is a thin wrapper over
+// appendEvent — which already never throws — so every helper inherits that
+// never-fails guarantee for free. Keep this module dependency-free (fs + path
+// + logger only); do not import result-schema or anything heavier here.
+//
+// Task 13 dual-sink: every helper takes an OPTIONAL trailing `follow` arg
+// ({onEvent(event)}, from observe/follow.js). appendEvent (disk) stays
+// UNCONDITIONAL; when `follow` is present, the SAME raw event object (pre
+// envelope) is also handed to follow.onEvent — a live stderr mirror, not a
+// durable record. Callers that omit `follow` (every pre-Task-13 call site)
+// get the old behavior unchanged.
+
+/** Wave lifecycle start: models resolved (post-routing) + derived leg ids. */
+function emitWaveStarted(waveDir, waveId, models, legIds, follow) {
+  const evt = { event: 'wave-started', id: waveId, models, legIds };
+  appendEvent(waveDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Wave lifecycle end: fires AFTER wave.json is written (ordering guarantee). */
+function emitWaveTerminal(waveDir, waveId, { status, counts, usage, exitCode }, follow) {
+  const evt = { event: 'wave-terminal', id: waveId, status, counts, usage, exitCode };
+  appendEvent(waveDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Leg lifecycle start, into the OWNING wave's events.jsonl (not the leg dir). */
+function emitLegStarted(waveDir, waveId, legId, model, modelInput, follow) {
+  const evt = { event: 'leg-started', id: waveId, legId, model, modelInput };
+  appendEvent(waveDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Leg lifecycle end: fires AFTER the leg metadata patch + ledger append. */
+function emitLegTerminal(waveDir, waveId, legId, { model, status, durationMs, usage }, follow) {
+  const evt = { event: 'leg-terminal', id: waveId, legId, model, status, durationMs, usage };
+  appendEvent(waveDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Council run lifecycle start. */
+function emitRunStarted(runDir, runId, { bench, chair }, follow) {
+  const evt = { event: 'run-started', id: runId, bench, chair };
+  appendEvent(runDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Entering a council stage (stage1, stage2, chair, debate-defense, debate-revote, tally, verdict, ...). */
+function emitStageStarted(runDir, runId, stage, waveId, follow) {
+  const evt = { event: 'stage-started', id: runId, stage, waveId };
+  appendEvent(runDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Leaving a council stage (status: complete/error/skipped/aborted). */
+function emitStageTerminal(runDir, runId, stage, status, waveId, follow) {
+  const evt = { event: 'stage-terminal', id: runId, stage, status, waveId };
+  appendEvent(runDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+/** Council run lifecycle end: fires AFTER the terminal run.json checkpoint. */
+function emitRunTerminal(runDir, runId, status, exitCode, follow) {
+  const evt = { event: 'run-terminal', id: runId, status, exitCode };
+  appendEvent(runDir, evt);
+  if (follow) { follow.onEvent(evt); }
+}
+
+module.exports = {
+  appendEvent, createEventTail, EVENTS_FILE, EVENTS_SCHEMA_VERSION,
+  emitWaveStarted, emitWaveTerminal, emitLegStarted, emitLegTerminal,
+  emitRunStarted, emitStageStarted, emitStageTerminal, emitRunTerminal,
+};

package/src/observe/follow.js

@@ -0,0 +1,26 @@
+// src/observe/follow.js
+'use strict';
+
+/**
+ * @module observe/follow
+ * --follow (spec 5.2): stream a run's OWN events as they are emitted, to
+ * stderr — no tailing, the orchestrator is the emitter. json mode -> NDJSON
+ * event lines (CI: --json --follow 2>progress.ndjson); human mode -> terse
+ * per-event lines replacing the 15 s heartbeat table. stdout contracts stay
+ * byte-identical (the --json final doc / human summary are untouched).
+ */
+
+const { renderPlainLines } = require('./watch-render');
+
+function createFollowPrinter({ json, stream } = {}) {
+  const out = stream || process.stderr;
+  return {
+    onEvent(event) {
+      if (json) { out.write(JSON.stringify(event) + '\n'); return; }
+      const [line] = renderPlainLines([event], null);
+      if (line) { out.write(line + '\n'); }
+    },
+  };
+}
+
+module.exports = { createFollowPrinter };

package/src/observe/live-doc.js

@@ -0,0 +1,56 @@
+// src/observe/live-doc.js
+'use strict';
+
+/**
+ * @module observe/live-doc
+ * Surface C (spec 4.3): the composed live doc is the amicus_status rollup with
+ * an additive `view:'live'` marker + per-leg usage. This module owns the WAVE +
+ * single-session composed shape. (DE-ROT: the COUNCIL composed doc is built in
+ * src/mcp-council-awareness.js:buildCouncilStatusPayload, NOT here — Task 9 Step 5
+ * marks it live + adds per-stage usage there.) Cost is resolved at READ time from progress.json's raw
+ * usage (spec 4.1) so pricing stays current; cost-by-seat NEVER touches a
+ * ledger (A8). The `type` is deliberately NOT renamed (resolved Q8) — `view`
+ * disambiguates live composed docs from terminal wave.json/run.json.
+ */
+
+const { resolveUsage, sumWaveUsage } = require('../utils/pricing');
+
+const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'idle-timeout']);
+
+/**
+ * Attach read-time-resolved usage to a leg from its raw progress usage.
+ *
+ * v4.4.1 CA-1: the terminal progress record carries the leg's enumerated CHILD
+ * (subagent) session spend as `usage.subtree` / `usage.subtreeUnknown`
+ * (src/headless.js). Those must be forwarded, not dropped: the live workspace
+ * and `amicus watch` read progress.json directly, so silently keeping only
+ * {tokens, cost} here would make the GUI's cost-by-seat and its wave rollup
+ * disagree with run.json by exactly the child-session amount — reintroducing
+ * the under-report one surface down from where it was fixed.
+ */
+function enrichLegUsage(leg, progressUsage) {
+  if (!progressUsage || !progressUsage.tokens) { return leg; }
+  const resolved = resolveUsage({
+    model: leg.model,
+    usageTotals: progressUsage,
+    subtree: progressUsage.subtree,
+    subtreeUnknown: progressUsage.subtreeUnknown,
+  });
+  const usage = { tokens: resolved.tokens, cost: resolved.cost };
+  if (resolved.subtree) { usage.subtree = resolved.subtree; }
+  if (resolved.subtreeUnknown) { usage.subtreeUnknown = true; }
+  return { ...leg, usage };
+}
+
+/** Stamp view:'live' on a non-terminal composed doc; no-op when terminal. */
+function markLive(doc) {
+  if (doc && !TERMINAL.has(doc.status)) { doc.view = 'live'; }
+  return doc;
+}
+
+/** Sum enriched leg usage into a wave-level {tokens, cost} rollup. */
+function rollupWaveUsage(legs) {
+  return sumWaveUsage((legs || []).map((l) => ({ usage: l.usage })));
+}
+
+module.exports = { enrichLegUsage, markLive, rollupWaveUsage, TERMINAL };

package/src/observe/on-complete.js

@@ -0,0 +1,117 @@
+// src/observe/on-complete.js
+'use strict';
+
+/**
+ * @module observe/on-complete
+ * CLI --on-complete exec hook (spec 5.3). The command is user-authored on the
+ * command line of THIS invocation — the same trust level as typing it into the
+ * shell. Amicus never sources hook commands from config/briefings/model output
+ * (D8 withdrawn) and never interpolates anything into the command string. The
+ * payload rides via ENVIRONMENT only, ids/paths only — never model-generated
+ * text — so untrusted previews can never enter a user's shell pipeline. The
+ * hook can never change the run's exit code, docs, or events. CLI-only: MCP
+ * never gets exec (Task 15 gives MCP a notify-only hook).
+ */
+
+const HOOK_TIMEOUT_MS = Number(process.env.AMICUS_HOOK_TIMEOUT_MS) || 60000;
+
+/** ids/paths ONLY (spec 5.3). Every value is a string; cost/paths default ''. */
+function buildHookEnv(info) {
+  return {
+    AMICUS_TASK_ID: String(info.taskId || ''),
+    AMICUS_TYPE: String(info.type || ''),
+    AMICUS_STATUS: String(info.status || ''),
+    AMICUS_EXIT_CODE: String(info.exitCode !== null && info.exitCode !== undefined ? info.exitCode : ''),
+    AMICUS_RESULT_FILE: String(info.resultFile || ''),
+    AMICUS_EVENTS_FILE: String(info.eventsFile || ''),
+    AMICUS_COST: String(info.cost || ''),
+    AMICUS_PROJECT: String(info.project || ''),
+  };
+}
+
+/**
+ * Fire the exec hook once at terminal state. Never throws/rejects; a non-zero
+ * exit or timeout is a warning only — the run's exit code/docs/events are
+ * never touched by this function.
+ */
+function runOnComplete(cmd, info, deps = {}) {
+  const spawn = deps.spawn || require('child_process').spawn;
+  const logger = deps.logger || require('../utils/logger').logger;
+  const timeoutMs = deps.timeoutMs || HOOK_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, {
+        shell: true, cwd: info.project || process.cwd(),
+        env: { ...process.env, ...buildHookEnv(info) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      logger.warn('on-complete hook failed to spawn (run unaffected)', { error: e.message });
+      return resolve();
+    }
+    let done = false;
+    const finish = () => { if (!done) { done = true; clearTimeout(timer); resolve(); } };
+    const timer = setTimeout(() => {
+      logger.warn('on-complete hook timed out — killing (run unaffected)', { timeoutMs });
+      try { child.kill(); } catch { /* already gone */ }
+      finish();
+    }, timeoutMs);
+    if (child.stdout) { child.stdout.on('data', (d) => process.stderr.write(d)); }
+    if (child.stderr) { child.stderr.on('data', (d) => process.stderr.write(d)); }
+    child.on('error', (e) => { logger.warn('on-complete hook error (run unaffected)', { error: e.message }); finish(); });
+    child.on('close', (code) => {
+      if (code && code !== 0) { logger.warn('on-complete hook exited non-zero (run unaffected)', { code }); }
+      finish();
+    });
+  });
+}
+
+/**
+ * Thin fire helper for fanout's two terminal sites (normal finalize + the
+ * all-legs-failed short-circuit). No-ops on a falsy/non-string cmd so call
+ * sites stay one line with no guard of their own.
+ */
+async function fireWaveOnComplete(cmd, wave, { waveId, waveDir, wavePath, exitCode, project }, deps) {
+  if (!cmd || typeof cmd !== 'string') { return; }
+  try {
+    const path = require('path');
+    const { formatCost } = require('../utils/pricing');
+    const { EVENTS_FILE } = require('./events');
+    await runOnComplete(cmd, {
+      taskId: waveId, type: 'wave', status: wave.status, exitCode,
+      resultFile: wavePath, eventsFile: path.join(waveDir, EVENTS_FILE),
+      cost: wave.usage && wave.usage.cost ? formatCost(wave.usage.cost) : '',
+      project,
+    }, deps);
+  } catch (e) {
+    const logger = (deps && deps.logger) || require('../utils/logger').logger;
+    logger.warn('on-complete hook assembly failed (run unaffected)', { error: e.message });
+  }
+}
+
+/**
+ * Thin fire helper for council run.js's single finalize choke point. No-ops
+ * on a falsy/non-string cmd so the call site stays one line.
+ */
+async function fireCouncilOnComplete(cmd, run, { runId, runDir, exitCode, project }, deps) {
+  if (!cmd || typeof cmd !== 'string') { return; }
+  try {
+    const path = require('path');
+    const { formatCost } = require('../utils/pricing');
+    const { EVENTS_FILE } = require('./events');
+    await runOnComplete(cmd, {
+      taskId: runId, type: 'council-run', status: run.status, exitCode,
+      resultFile: path.join(runDir, 'run.json'), eventsFile: path.join(runDir, EVENTS_FILE),
+      cost: run.usage && run.usage.cost ? formatCost(run.usage.cost) : '',
+      project,
+    }, deps);
+  } catch (e) {
+    const logger = (deps && deps.logger) || require('../utils/logger').logger;
+    logger.warn('on-complete hook assembly failed (run unaffected)', { error: e.message });
+  }
+}
+
+module.exports = {
+  buildHookEnv, runOnComplete, fireWaveOnComplete, fireCouncilOnComplete, HOOK_TIMEOUT_MS,
+};