amicus 4.2.0 → 4.3.0

package/src/mcp-notify.js

@@ -0,0 +1,54 @@
+/**
+ * Pure helpers + in-process registry for the MCP `onComplete: 'mcp-notify'`
+ * input (spec §5.3, Task 15).
+ * @module mcp-notify
+ *
+ * Security property (THE defining property of this module): exec is
+ * deliberately NOT exposed over MCP. A shell-exec tool input would be a
+ * prompt-injection amplifier — an MCP client acting on untrusted content
+ * could make amicus run arbitrary shell commands. So onComplete over MCP
+ * accepts ONLY 'mcp-notify'; any other value (especially a command string)
+ * is a validation error. Nothing is ever spawned/exec'd from this module or
+ * from the MCP path that consumes it — it only ever sends a notification.
+ *
+ * Delivery seam: amicus_fanout/amicus_council_run spawn a DETACHED CLI child
+ * and return 'running' immediately — there is no in-process finalize to
+ * notify from. Instead, a run that requested notify is marked here (mirrors
+ * mcp-wait.js's `_inProcessRuns` in-process Map), and the ONE place that
+ * later sees the run reach terminal state — the `runWait` poll loop in
+ * mcp-wait.js — consumes the mark and sends the notification. Advisory/
+ * best-effort throughout: a send failure never changes the run outcome.
+ */
+
+'use strict';
+
+/** MCP onComplete accepts ONLY 'mcp-notify' — exec is deliberately not exposed
+ *  over MCP (a shell-exec tool input would be a prompt-injection amplifier). */
+function validateOnComplete(value) {
+  if (value === undefined || value === null) { return { ok: true, mode: null }; }
+  if (value === 'mcp-notify') { return { ok: true, mode: 'mcp-notify' }; }
+  return { ok: false, error: 'onComplete over MCP supports only \'mcp-notify\'; exec commands are not accepted over MCP.' };
+}
+
+/** Wrap a terminal event doc as an MCP logging notification payload. */
+function buildNotifyPayload(terminalEvent) {
+  return { level: 'info', logger: 'amicus', data: terminalEvent };
+}
+
+/** taskId/runId -> true, for runs (owned by THIS MCP server process) that
+ *  requested a best-effort mcp-notify on terminal. */
+const _notifyRequests = new Map();
+
+/** Mark a run for a best-effort terminal notify (called once the run's id is known and launch succeeded). */
+function requestMcpNotify(taskId) {
+  _notifyRequests.set(taskId, true);
+}
+
+/** Once-semantics: true + delete on first read for a requested id; false (no-op) otherwise,
+ *  including on a second call — so a re-wait on an already-terminal run never double-sends. */
+function consumeMcpNotify(taskId) {
+  if (_notifyRequests.has(taskId)) { _notifyRequests.delete(taskId); return true; }
+  return false;
+}
+
+module.exports = { validateOnComplete, buildNotifyPayload, requestMcpNotify, consumeMcpNotify };

package/src/mcp-server.js

@@ -18,6 +18,7 @@ const { recordSession } = require('./utils/session-index');
 const { fileURLToPath } = require('url');
 const { RUNNING_VERSION, versionWarning } = require('./utils/version-info');
 const { runWait, registerInProcessRun, settleInProcessRun } = require('./mcp-wait');
+const { validateOnComplete, requestMcpNotify } = require('./mcp-notify');
 const { detectClient } = require('./utils/client-detect');
 const { fenceSidecarOutput } = require('./utils/untrusted-fence');
 const { sliceForRead } = require('./utils/read-slice');
@@ -587,6 +588,7 @@ const handlers = {
     }
 
     if (metadata.type === 'wave') {
+      const { enrichLegUsage, markLive, rollupWaveUsage } = require('./observe/live-doc');
       const legs = (metadata.legs || []).map((legId) => {
         const m = readMetadata(legId, cwd);
         const leg = { taskId: legId, model: (m && m.model) || null, status: (m && m.status) || 'unknown' };
@@ -599,6 +601,11 @@ const handlers = {
           leg.phase = deriveStage(leg.status, p.stage);         // coarse: starting|generating|folding|terminal
           leg.latestPreview = p.latestPreview;
           leg.lastActivityAt = p.lastActivityAt;
+          // N3: enrichLegUsage returns the bare leg (no `usage` key) when
+          // progress carries no usage yet (e.g. solo interactive legs, Task 8)
+          // — merge only when present so we never put an undefined key on doc.
+          const enriched = enrichLegUsage(leg, p.usage);
+          if (enriched.usage) { leg.usage = enriched.usage; }
         } catch { /* no progress yet — leave base fields only */ }
         return leg;
       });
@@ -649,6 +656,11 @@ const handlers = {
       if (metadata.status === 'crashed' || metadata.status === 'error') {
         response.reason = metadata.reason || 'Unknown error';
       }
+      // Surface C (spec 4.3): additive read-time usage rollup + live marker.
+      // sumWaveUsage tolerates legs with no usage (A8: cost-by-seat from
+      // progress.json only, never a ledger) — safe even when no leg priced.
+      response.usage = rollupWaveUsage(legs);
+      markLive(response);
       const content = [{ type: 'text', text: JSON.stringify(response) }];
       appendVersionWarning(content);
       if (metadata.status === 'running') {
@@ -692,6 +704,17 @@ const handlers = {
       response.messageCount = progress.messages;                       // stable agent-facing alias
       response.phase = deriveStage(metadata.status, progress.stage);   // coarse lifecycle
 
+      // Surface C (spec 4.3): read-time cost resolution over the RAW usage the
+      // Object.assign above just copied from progress.json (Task 8). N3: most
+      // interactive/GUI runs write no progress.usage at all — enrichLegUsage
+      // returns no `usage` key in that case, so NEVER assign it unconditionally
+      // (that would leave the doc holding the unresolved raw {tokens,costReported}
+      // shape, or an undefined key when progress.usage was absent).
+      const { enrichLegUsage } = require('./observe/live-doc');
+      const enr = enrichLegUsage({ model: metadata.model }, progress.usage);
+      if (enr.usage) { response.usage = enr.usage; }
+      else { delete response.usage; }
+
       // Stall detection: flag when no activity for 2+ minutes
       const STALL_THRESHOLD_MS = 120000;
       if (metadata.headless && progress.lastActivityMs !== null && progress.lastActivityMs > STALL_THRESHOLD_MS) {
@@ -711,6 +734,7 @@ const handlers = {
     if (metadata.status === 'crashed' || metadata.status === 'error') {
       response.reason = metadata.reason || 'Unknown error';
     }
+    require('./observe/live-doc').markLive(response);
     const content = [{ type: 'text', text: JSON.stringify(response) }];
     appendVersionWarning(content);
     if (metadata.status === 'running' && metadata.headless) {
@@ -719,11 +743,20 @@ const handlers = {
     return { content };
   },
 
-  async amicus_wait(input, project) {
+  async amicus_wait(input, project, mcpServer) {
     // statusFn injection avoids a circular require and inherits amicus_status's
     // crash detection + wave leg rollup on every poll tick.
     return runWait(input, project, {
       statusFn: (i, p) => handlers.amicus_status(i, p),
+      // Task 15 (spec §5.3): best-effort mcp-notify delivery. mcpServer here
+      // is the McpServer instance the dispatch loop passes as the 3rd arg
+      // (server.js:register); mcpServer.server is the underlying low-level
+      // SDK Server that exposes sendLoggingMessage. A throw or an unsupported
+      // transport degrades silently — advisory only, never affects the wait.
+      notify: (payload) => {
+        try { if (mcpServer && mcpServer.server) { mcpServer.server.sendLoggingMessage(payload); } }
+        catch { /* best-effort; a send failure is a debug log only */ }
+      },
     });
   },
 
@@ -1026,6 +1059,12 @@ const handlers = {
 
   async amicus_fanout(input, project, mcpServer) {
     const cwd = project || getProjectDir(input.project);
+    // Task 15 (spec §5.3): validate onComplete FIRST, before any wave dir /
+    // metadata is written — 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 { generateTaskId } = require('./sidecar/start');
     const { deriveLegIds, DEFAULT_MAX_LEGS } = require('./sidecar/fanout');
 
@@ -1110,6 +1149,10 @@ const handlers = {
       } catch { /* best-effort */ }
       return textResult(`Failed to start fan-out: ${err.message}`, true);
     }
+    // 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.
+    if (oc.mode === 'mcp-notify') { requestMcpNotify(waveId); }
 
     const body = JSON.stringify(stampEnvelope('wave', {
       waveId, taskIds: legIds, status: 'running', mode: 'headless',
@@ -1196,6 +1239,13 @@ const handlers = {
     return textResult('Setup wizard launched. The Electron window should appear on your desktop.');
   },
   async amicus_guide() { return textResult(getGuideText()); },
+
+  // Read-only; deliberately NOT fenced (spec 7.3 — spend docs are ids/numbers/
+  // paths by construction, never model-generated prose). `project` here is the
+  // dispatch-resolved cwd, used only to expand a literal '.' filterProject —
+  // see src/mcp-spend.js's module docblock for why the row filter isn't named
+  // `project` itself.
+  amicus_spend: (input, project) => require('./mcp-spend').amicus_spend(input, project),
 };
 
 /** Start the MCP server on stdio transport */

package/src/mcp-spend.js

@@ -0,0 +1,125 @@
+// src/mcp-spend.js
+'use strict';
+
+/**
+ * @module mcp-spend
+ * Read-only `amicus_spend` MCP tool (spec §7.3, resolved Q1). Mirrors the CLI
+ * `amicus spend` query flags over spend-ledger.jsonl. No fence: spend docs are
+ * ids/numbers/paths by construction (never model-generated text) — the schema
+ * commits to keeping it that way, so unlike other sidecar-facing MCP tools
+ * this handler never calls fenceSidecarOutput. `buildSpendResult` is the pure
+ * core (dir/cwd DI seam, no I/O beyond readSpendRows); `amicus_spend` is the
+ * async MCP entry the server dispatch loop calls.
+ *
+ * Every query primitive (filterRows/groupRows/computeWasted/GROUP_DIMS/
+ * ROWS_CAP from ./spend-query, aggregateSpend/buildSpendDoc from
+ * ./cli-handlers-spend) is reused verbatim from Task 4 — nothing here
+ * reimplements filtering, grouping, or the wasted rollup.
+ *
+ * Row-filter naming note: the CLI's `--project` flag mirrors 1:1 onto every
+ * other filter EXCEPT this one, which is `filterProject` here rather than
+ * `project`. The MCP dispatch wrapper (mcp-server.js) treats an input key
+ * literally named `project` as the tool's own working-directory selector and
+ * resolves/validates it against the allowed project roots BEFORE the handler
+ * ever runs — throwing for a path outside them. That's the right behavior for
+ * a cwd selector; it is wrong for this field, which is a pure ledger-row
+ * filter that must be able to name ANY project the ledger has ever recorded
+ * spend for (the ledger itself is global, keyed by config dir, not by cwd —
+ * see readSpendRows). Reusing `project` here would make filtering by an
+ * out-of-roots historical project throw instead of returning rows. Hence the
+ * distinct name.
+ */
+
+const { readSpendRows } = require('./utils/spend-ledger');
+const { aggregateSpend, buildSpendDoc, parseSinceDays } = require('./cli-handlers-spend');
+const { filterRows, groupRows, computeWasted, GROUP_DIMS, ROWS_CAP } = require('./spend-query');
+const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+
+/** @param {string} message @param {string} hint @returns {{content:Array, isError:true}} */
+function errorResult(message, hint) {
+  const doc = buildErrorDoc({ code: ERROR_CODES.BAD_ARGS, message, hint });
+  return { content: [{ type: 'text', text: JSON.stringify(doc) }], isError: true };
+}
+
+/**
+ * Pure core: build the spend-doc MCP result for a given input + test seam.
+ * @param {{since?:string, wave?:string, council?:string, filterProject?:string,
+ *   model?:string, op?:string, failed?:boolean, groupBy?:string, rows?:boolean}} [input]
+ * @param {{dir?:string, cwd?:string, now?:()=>number}} [ctx] test/DI seam — dir
+ *   overrides the ledger's config dir (readSpendRows); cwd is the resolved
+ *   project dir used to expand a literal '.' filterProject (CLI --project .
+ *   parity); now overrides the clock used for `since` windowing (CLI --since
+ *   test parity).
+ * @returns {{content:[{type:'text', text:string}], isError?:true}}
+ */
+function buildSpendResult(input = {}, ctx = {}) {
+  const groupBy = input.groupBy || 'model';
+  if (!GROUP_DIMS.includes(groupBy)) {
+    return errorResult(
+      `invalid groupBy '${groupBy}'`,
+      `groupBy one of: ${GROUP_DIMS.join('|')}`
+    );
+  }
+
+  let windowDays = null;
+  if (input.since !== undefined) {
+    windowDays = parseSinceDays(input.since);
+    if (windowDays === null) {
+      return errorResult(
+        `invalid since '${input.since}'`,
+        "since must be an integer followed by 'd' (e.g. '7d')"
+      );
+    }
+  }
+
+  const rows = readSpendRows(ctx.dir);
+  const filters = {
+    wave: input.wave,
+    council: input.council,
+    model: input.model,
+    op: input.op,
+    failed: !!input.failed,
+    project: input.filterProject === '.' ? (ctx.cwd || process.cwd()) : input.filterProject,
+  };
+  const now = windowDays !== null ? (ctx.now ? ctx.now() : Date.now()) : undefined;
+  const filtered = filterRows(rows, { ...filters, since: windowDays, now });
+  const { total, byModel } = aggregateSpend(filtered);
+  const groups = groupRows(filtered, groupBy);
+  const wasted = computeWasted(filtered);
+
+  const doc = buildSpendDoc({
+    // credit stays null over MCP: the OpenRouter credit footer is a
+    // best-effort network probe the CLI path accepts blocking on —
+    // deliberately skipped here so a read-only local-file query never waits
+    // on the network. `since`/windowDays, by contrast, is a pure local
+    // filter (filterRows) with no network involved, so it IS threaded here.
+    total, byModel, windowDays, credit: null,
+    filters, groupBy, groups, wasted,
+    rows: input.rows ? filtered.slice(0, ROWS_CAP) : undefined,
+    rowsTruncated: input.rows ? filtered.length > ROWS_CAP : undefined,
+  });
+
+  // Spec §7.3: spend docs are ids/numbers/paths only, by construction — never
+  // fenced (contrast amicus_council_stats etc., which DO fence because they
+  // summarize model-raised prose).
+  return { content: [{ type: 'text', text: JSON.stringify(doc) }] };
+}
+
+/**
+ * MCP entry point. `project` is the dispatch-resolved cwd (mcp-server.js
+ * calls `handlers[name](input, project, server)`); this tool has no
+ * `project` input of its own (see module docblock), so it only uses it to
+ * expand a literal '.' `filterProject`. The 3rd positional slot is `server`
+ * in production (read only for `.dir`/`.now`, which it never has — a no-op)
+ * and a `{dir, now}` test seam in tests, mirroring handleSpend's
+ * depsOverride shape.
+ * @param {object} [input]
+ * @param {string} [project]
+ * @param {{dir?:string, now?:()=>number}} [testOverride]
+ * @returns {Promise<{content:Array, isError?:true}>}
+ */
+async function amicus_spend(input, project, testOverride = {}) {
+  return buildSpendResult(input || {}, { cwd: project, dir: testOverride.dir, now: testOverride.now });
+}
+
+module.exports = { amicus_spend, buildSpendResult };

package/src/mcp-tools.js

@@ -11,6 +11,7 @@ const { z } = require('zod');
 const { formatAliasNames } = require('./utils/config');
 const { READ_CAP_BYTES } = require('./utils/read-slice');
 const { GATEWAY_MODES } = require('./utils/model-descriptor');
+const { GROUP_DIMS, ROWS_CAP } = require('./spend-query');
 
 /** Zod pattern for safe task IDs (alphanumeric, hyphens, underscores only) */
 const safeTaskId = z.string().regex(
@@ -360,6 +361,11 @@ function getTools() {
         'Claude Code session UUID for exact context matching. ' +
         'Prevents ambiguity when multiple sessions are active in the same project.'
       ),
+      onComplete: z.enum(['mcp-notify']).optional().describe(
+        'Advisory: send an MCP info notification carrying the terminal event doc when the run ' +
+        'finishes (best-effort; amicus_wait remains the reliable completion mechanism). Exec ' +
+        'commands are NOT accepted over MCP.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
@@ -486,11 +492,44 @@ function getTools() {
         'Disable the per-leg price gate for the WHOLE run (repairs and chair included). ' +
         'Use for an intentional o3-class council. Independent of maxCost, which still caps the total.'
       ),
+      onComplete: z.enum(['mcp-notify']).optional().describe(
+        'Advisory: send an MCP info notification carrying the terminal event doc when the run ' +
+        'finishes (best-effort; amicus_wait remains the reliable completion mechanism). Exec ' +
+        'commands are NOT accepted over MCP.'
+      ),
       project: z.string().optional().describe(
         'Optional project directory path. Auto-detected from working directory if omitted.'
       ),
     },
   },
+  {
+    name: 'amicus_spend',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    description:
+      'Read-only cross-run cost rollup from the spend ledger (mirrors the CLI ' +
+      '`amicus spend` query flags). Filter by since/wave/council/project/model/op, keep ' +
+      'only failed (wasted) rows, and group by a dimension. Returns a versioned ' +
+      'spend doc (ids/numbers/paths only, never model-generated text) — never fenced.',
+    inputSchema: {
+      since: z.string().optional().describe(
+        "Only rows from the last N days, as an integer followed by 'd' (e.g. '7d')."
+      ),
+      wave: z.string().optional().describe('Only rows from this fan-out wave id.'),
+      council: z.string().optional().describe('Only rows from this council run id or preset name.'),
+      filterProject: z.string().optional().describe(
+        'Only rows whose recorded project dir matches this absolute path (a ledger-row ' +
+        'filter, NOT this tool\'s working-directory selector — the ledger is global, not ' +
+        'per-project). Pass \'.\' to mean the current project dir.'
+      ),
+      model: z.string().optional().describe('Only rows whose model id starts with this.'),
+      op: z.enum(['start', 'continue', 'resume', 'leg']).optional().describe('Only rows for this operation.'),
+      failed: z.boolean().optional().describe('Only non-complete (wasted) rows.'),
+      groupBy: z.enum(GROUP_DIMS).optional().describe(
+        `Group the rollup by this dimension (default 'model'). One of: ${GROUP_DIMS.join(', ')}.`
+      ),
+      rows: z.boolean().optional().describe(`Include matching raw rows in the result, capped at ${ROWS_CAP}.`),
+    },
+  },
   {
     name: 'amicus_guide',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },

package/src/mcp-wait.js

@@ -19,6 +19,7 @@
 'use strict';
 
 const { versionWarning } = require('./utils/version-info');
+const { consumeMcpNotify, buildNotifyPayload } = require('./mcp-notify');
 
 const DEFAULT_WAIT_MS = Number(process.env.AMICUS_WAIT_DEFAULT_MS) || 50000;
 const MAX_WAIT_MS = Number(process.env.AMICUS_WAIT_MAX_MS) || 110000;
@@ -98,8 +99,12 @@ function buildWaitResult(snapshot, timedOut, waitedMs) {
  * Wait for a session/wave to reach a terminal state, or time out.
  * @param {{taskId?:string, waveId?:string, timeoutMs?:number, project?:string}} input
  * @param {string} project resolved project dir
- * @param {{statusFn:Function, sleep?:Function, now?:Function, pollIntervalMs?:number}} deps
+ * @param {{statusFn:Function, sleep?:Function, now?:Function, pollIntervalMs?:number, notify?:Function}} deps
  *   statusFn(input, project) must be the amicus_status handler (or compatible).
+ *   notify(payload), if given, is called at most once per run — only when the
+ *   run requested it via requestMcpNotify (Task 15, spec §5.3) — right before
+ *   returning a terminal result. Best-effort: a notify() throw is swallowed
+ *   and never affects the wait result.
  * @returns {Promise<object>} MCP tool result
  */
 async function runWait(input, project, deps) {
@@ -143,7 +148,28 @@ async function runWait(input, project, deps) {
 
     if (snapshot) {
       lastSnapshot = snapshot;
-      if (isTerminalSnapshot(snapshot)) { return buildWaitResult(snapshot, false, now() - started); }
+      if (isTerminalSnapshot(snapshot)) {
+        // Task 15 (spec §5.3): best-effort mcp-notify delivery. This is the
+        // ONE place that sees a fanout/council-run reach terminal state (they
+        // spawn a detached CLI child and return 'running' immediately, so
+        // there is no in-process finalize to notify from). consumeMcpNotify
+        // gives once-semantics; a notify() throw is swallowed and never
+        // changes the wait result below. Consume FIRST (unconditionally on a
+        // requested run) so the registry entry always drains — even if this
+        // runWait caller supplied no notify capability, the entry must not
+        // leak; the send is then gated on deps.notify.
+        if (consumeMcpNotify(taskId) && deps.notify) {
+          try {
+            const evt = {
+              event: snapshot.type === 'council-run' ? 'run-terminal' : 'wave-terminal',
+              id: taskId, status: snapshot.status,
+              exitCode: (snapshot.exitCode === undefined || snapshot.exitCode === null) ? undefined : snapshot.exitCode,
+            };
+            deps.notify(buildNotifyPayload(evt));
+          } catch { /* advisory; never affects the wait result */ }
+        }
+        return buildWaitResult(snapshot, false, now() - started);
+      }
     }
 
     const remaining = deadline - now();

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,38 @@
+// 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. */
+function enrichLegUsage(leg, progressUsage) {
+  if (!progressUsage || !progressUsage.tokens) { return leg; }
+  const resolved = resolveUsage({ model: leg.model, usageTotals: progressUsage });
+  return { ...leg, usage: { tokens: resolved.tokens, cost: resolved.cost } };
+}
+
+/** 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 };