amicus 4.2.1 → 4.4.0

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',

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();