amicus 3.2.2 → 4.0.0

package/src/mcp-council-run.js

@@ -0,0 +1,267 @@
+// src/mcp-council-run.js
+'use strict';
+
+/**
+ * @module mcp-council-run
+ * MCP surface for headless council runs (spec §8): the amicus_council_run
+ * handler (15th tool, born-fenced) plus the council-awareness helpers that
+ * amicus_status / amicus_list / amicus_abort call through the sessions-dir
+ * pointer file. Lives outside mcp-server.js (grandfathered-oversized); the
+ * spawn helper is INJECTED by mcp-server at call time to avoid a require
+ * cycle.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const runState = require('./council/run-state');
+const { fenceSidecarOutput } = require('./utils/untrusted-fence');
+const { RUNNING_VERSION } = require('./utils/version-info');
+const { isPathInside } = require('./project-root-allowlist');
+
+function textResult(text, isError) {
+  const result = { content: [{ type: 'text', text }] };
+  if (isError) { result.isError = true; }
+  return result;
+}
+
+/** Resolve the bench: models XOR council preset (amicus_fanout parity). */
+function resolveBenchInput(input) {
+  const inputModels = Array.isArray(input.models) ? input.models : [];
+  const hasModels = inputModels.length > 0;
+  const hasCouncil = typeof input.council === 'string' && input.council.trim();
+  if (hasModels && hasCouncil) { return { error: "Pass exactly one of 'models' / 'council', not both." }; }
+  if (!hasModels && !hasCouncil) { return { error: "Provide 'models' or 'council'." }; }
+  if (hasCouncil) {
+    const { resolveCouncilMembers } = require('./utils/config');
+    const { readCache } = require('./utils/model-catalog');
+    const catalog = (readCache() || {}).models || [];
+    const expanded = resolveCouncilMembers(input.council.trim(), catalog);
+    if (expanded.error) { return { error: expanded.error }; }
+    return { bench: expanded.models };
+  }
+  return { bench: inputModels };
+}
+
+/**
+ * amicus_council_run: validate → prep run dir → spawn CLI child → return
+ * {runId, runDir} immediately (fenced).
+ * @param {object} input tool input
+ * @param {string} project resolved project dir
+ * @param {{spawnFn: Function, clientName: string}} helpers injected by mcp-server
+ */
+async function handleCouncilRunTool(input, project, helpers) {
+  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);
+  }
+  let briefing;
+  try { briefing = fs.readFileSync(input.briefingFile, 'utf-8'); }
+  catch (e) { return textResult(`Cannot read briefingFile ${input.briefingFile}: ${e.message}`, true); }
+  if (briefing.charCodeAt(0) === 0xFEFF) { briefing = briefing.slice(1); }
+  if (!briefing.trim()) { return textResult(`briefingFile ${input.briefingFile} is empty.`, true); }
+
+  const benchRes = resolveBenchInput(input);
+  if (benchRes.error) { return textResult(benchRes.error, true); }
+  const bench = benchRes.bench;
+  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)) {
+    return textResult(`Chair '${chair}' is a bench seat — pick a chair outside the bench (default: ${CHAIR_DEFAULT}).`, true);
+  }
+  const critic = (typeof input.critic === 'string' && input.critic.trim()) ? input.critic.trim() : null;
+  if (critic && !bench.includes(critic)) {
+    return textResult(`Critic '${critic}' must be one of the bench seats (${bench.join(', ')}).`, true);
+  }
+  const lenses = Array.isArray(input.lenses) && input.lenses.length ? input.lenses : null;
+  if (critic && lenses) { return textResult('critic and lenses are mutually exclusive in v4.0.', true); }
+  if (lenses && lenses.length !== bench.length) {
+    return textResult(`lenses needs exactly one lens per seat (${bench.length} seats, got ${lenses.length}).`, true);
+  }
+  if (input.timeoutMinutes !== undefined &&
+      (typeof input.timeoutMinutes !== 'number' || !Number.isFinite(input.timeoutMinutes) || input.timeoutMinutes <= 0)) {
+    return textResult('timeoutMinutes must be a positive number.', true);
+  }
+  if (input.maxCost !== undefined &&
+      (typeof input.maxCost !== 'number' || !Number.isFinite(input.maxCost) || input.maxCost <= 0)) {
+    return textResult('maxCost must be a positive number.', true);
+  }
+
+  const { generateTaskId } = require('./sidecar/start');
+  const runId = generateTaskId();
+  const runDir = input.outDir
+    ? path.resolve(project, String(input.outDir))
+    : path.join(project, `council-${runId}`);
+  if (!isPathInside(runDir, project)) {
+    return textResult(`outDir must resolve to a path inside the project directory (${project}).`, true);
+  }
+  const briefingPath = path.join(runDir, 'briefing.md');
+  try {
+    fs.mkdirSync(runDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(briefingPath, briefing, { mode: 0o600 });
+    runState.initRun(runDir, {
+      schemaVersion: 2, type: 'council-run', runId, status: 'running', stages: [],
+      bench, chair, critic, lenses, labelMap: null,
+      options: {
+        timeout: input.timeoutMinutes || null,
+        maxCost: (typeof input.maxCost === 'number') ? input.maxCost : null,
+        gateway: input.gateway || 'auto', outDir: runDir,
+      },
+      usage: null, createdAt: new Date().toISOString(),
+    });
+    runState.writePointer(project, runId, runDir);
+  } catch (err) {
+    return textResult(`Failed to prepare council run: ${err.message}`, true);
+  }
+
+  const args = [
+    'council', 'run', '--prompt-file', briefingPath, '--run-id', runId,
+    '--out-dir', runDir, '--json', '--cwd', project,
+    '--models', bench.join(','), '--chair', chair,
+    '--client', helpers.clientName,
+  ];
+  if (critic) { args.push('--critic', critic); }
+  if (lenses) { args.push('--lenses', lenses.join(',')); }
+  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); }
+
+  try { helpers.spawnFn(args, runDir); } catch (err) {
+    try {
+      runState.checkpoint(runDir, { status: 'error', error: { code: 'INTERNAL', message: err.message }, completedAt: new Date().toISOString() });
+    } catch { /* best-effort */ }
+    return textResult(`Failed to start council run: ${err.message}`, true);
+  }
+
+  const body = JSON.stringify({
+    schemaVersion: 2, type: 'council-run', runId, runDir, status: 'running',
+    message: 'Council run started. Preferred: call amicus_wait with the runId — one blocking ' +
+      'call replaces polling; re-call it while it returns timedOut: true. Fallback: poll ' +
+      'amicus_status with the runId. Artifacts land in runDir (verdict.json, report.html).',
+  });
+  // Born-fenced (spec §8): council MCP tool text is wrapped like amicus_read.
+  return textResult(fenceSidecarOutput(body));
+}
+
+/** ---- council-awareness helpers (consumed by mcp-server status/list/abort) ---- */
+
+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());
+  return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/** Status payload for a council runId, or null when the id is not a council run. */
+function buildCouncilStatusPayload(project, taskId) {
+  const ptr = runState.readPointer(project, taskId);
+  if (!ptr) { return null; }
+  const run = runState.readRun(ptr.runDir);
+  if (!run) { return null; }
+
+  // Crash detection: a running run.json whose engine pid is gone is 'error'.
+  if (run.status === 'running' && run.pid) {
+    try { process.kill(run.pid, 0); } catch (err) {
+      if (err.code !== 'EPERM') {
+        runState.checkpoint(ptr.runDir, {
+          status: 'error', completedAt: new Date().toISOString(),
+          error: { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' },
+        });
+        run.status = 'error';
+        run.error = { code: 'INTERNAL', message: 'Council engine process exited unexpectedly' };
+      }
+    }
+  }
+
+  const stages = (run.stages || []).map(s => ({
+    name: s.name, status: s.status, waveId: s.waveId || null,
+  }));
+  const active = (run.stages || []).find(s => s.status === 'running') || null;
+  let legsTotal = null; let legsComplete = null;
+  if (active && active.waveId && active.project) {
+    try {
+      const { getSessionDir } = require('./session-manager');
+      const { TERMINAL_STATUSES } = require('./utils/result-schema');
+      const meta = JSON.parse(fs.readFileSync(
+        path.join(getSessionDir(active.project, active.waveId), 'metadata.json'), 'utf-8'));
+      const legs = meta.legs || [];
+      legsTotal = legs.length;
+      legsComplete = legs.filter((id) => {
+        try {
+          const m = JSON.parse(fs.readFileSync(
+            path.join(getSessionDir(active.project, id), 'metadata.json'), 'utf-8'));
+          return TERMINAL_STATUSES.includes(m.status);
+        } catch { return false; }
+      }).length;
+    } catch { /* stage wave not on disk yet */ }
+  }
+  const payload = {
+    taskId: run.runId, type: 'council-run', runId: run.runId, runDir: ptr.runDir,
+    status: run.status, currentStage: active ? active.name : null, stages,
+    legsTotal, legsComplete, elapsed: elapsedOf(run),
+    exitCode: run.exitCode !== undefined ? run.exitCode : null,
+    version: RUNNING_VERSION,
+  };
+  if (run.error) { payload.reason = `${run.error.code}: ${run.error.message}`; }
+  return payload;
+}
+
+/** amicus_list entries for every council pointer in the project. */
+function listCouncilRuns(project) {
+  const { sanitizePreview } = require('./sidecar/progress-fields');
+  const out = [];
+  for (const ptr of runState.listPointers(project)) {
+    const run = runState.readRun(ptr.runDir);
+    if (!run) { continue; }
+    let briefing = '';
+    try { briefing = fs.readFileSync(path.join(ptr.runDir, 'briefing.md'), 'utf-8'); }
+    catch { /* optional */ }
+    const active = (run.stages || []).find(s => s.status === 'running');
+    out.push({
+      id: run.runId, type: 'council-run', status: run.status, mode: 'headless',
+      model: null, agent: 'Plan', createdAt: run.createdAt,
+      briefing: sanitizePreview(briefing, 80),
+      stage: active ? active.name : null,
+    });
+  }
+  return out;
+}
+
+/**
+ * Abort a council run via its pointer: checkpoint run.json aborted (abort-wins)
+ * and cascade to the active stage's wave + legs so in-flight legs settle.
+ * @returns {null|{notFound?: true}|{alreadyTerminal: true, status}|{aborted: true, cascaded: number}}
+ */
+function abortCouncilRun(project, taskId) {
+  const ptr = runState.readPointer(project, taskId);
+  if (!ptr) { return null; }
+  const run = runState.readRun(ptr.runDir);
+  if (!run) { return null; }
+  if (run.status !== 'running') { return { alreadyTerminal: true, status: run.status }; }
+
+  const { markAborted } = require('./utils/session-abort');
+  const { getSessionDir } = require('./session-manager');
+  let cascaded = 0;
+  for (const s of run.stages || []) {
+    if (s.status !== 'running' || !s.waveId || !s.project) { continue; }
+    try {
+      const waveDir = getSessionDir(s.project, s.waveId);
+      let meta = {};
+      try { meta = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8')); }
+      catch { /* wave record may not exist yet */ }
+      for (const legId of meta.legs || []) {
+        try { if (markAborted(getSessionDir(s.project, legId), 'council abort')) { cascaded++; } }
+        catch { /* skip leg */ }
+      }
+      markAborted(waveDir, 'council abort');
+    } catch { /* skip stage */ }
+  }
+  runState.checkpoint(ptr.runDir, { status: 'aborted', completedAt: new Date().toISOString() });
+  if (run.pid) {
+    try { require('./utils/abort-coordinator').waitThenKill(run.pid).catch(() => {}); }
+    catch { /* best-effort */ }
+  }
+  return { aborted: true, cascaded };
+}
+
+module.exports = {
+  handleCouncilRunTool, buildCouncilStatusPayload, listCouncilRuns, abortCouncilRun,
+};

package/src/mcp-server.js

@@ -198,6 +198,18 @@ function appendVersionWarning(content) {
   return content;
 }
 
+/**
+ * v4.0 §7: stamp the additive {schemaVersion, type} envelope keys onto an MCP
+ * JSON success body. `type` reflects the doc's subject family — 'run' for
+ * session status/acks, 'wave' for wave status + fanout acks, 'abort' for abort
+ * acks. Published result-doc schemas (schemas/) describe the durable --json
+ * docs; these snapshots/acks share the family type names (docs/schemas.md).
+ */
+function stampEnvelope(type, body) {
+  const { SCHEMA_VERSION } = require('./utils/result-schema-version');
+  return { schemaVersion: SCHEMA_VERSION, type, ...body };
+}
+
 /**
  * Compute next poll hint for headless sessions.
  * @returns {{ hint: string }}
@@ -244,9 +256,17 @@ const handlers = {
     const { validateStartInputs } = require('./utils/input-validators');
     const validation = validateStartInputs(input);
     if (!validation.valid) {
+      // v4.0 §7: error-doc-shaped tool text (was the raw validation_error object).
+      const { buildErrorDoc, ERROR_CODES } = require('./utils/error-doc');
+      const verr = validation.error;
       return {
         isError: true,
-        content: [{ type: 'text', text: JSON.stringify(validation.error) }],
+        content: [{ type: 'text', text: JSON.stringify(buildErrorDoc({
+          code: verr.field === 'prompt' ? ERROR_CODES.MISSING_PROMPT : ERROR_CODES.BAD_ARGS,
+          message: `${verr.field}: ${verr.message}`,
+          hint: Array.isArray(verr.suggestions) && verr.suggestions.length
+            ? `Valid values: ${verr.suggestions.join(', ')}` : null,
+        })) }],
       };
     }
 
@@ -263,7 +283,7 @@ const handlers = {
     // resolveLaunchModel (start-helpers.js) via model-input-default.js.
     const { resolveGatewayMode } = require('./utils/config');
     const { resolveRouteForLaunch } = require('./utils/route-launch');
-    const { toStructuredError } = require('./utils/route-error');
+    const { toErrorDocFields } = require('./utils/route-error');
     const { resolveModelInputOrDefault } = require('./utils/model-input-default');
 
     const modelInput = resolveModelInputOrDefault(input.model);
@@ -277,9 +297,10 @@ const handlers = {
       validateModel: true,
     });
     if (routeResult.kind !== 'resolved') {
+      const { buildErrorDoc } = require('./utils/error-doc');
       return {
         isError: true,
-        content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+        content: [{ type: 'text', text: JSON.stringify(buildErrorDoc(toErrorDocFields(routeResult))) }],
       };
     }
     const resolvedModel = routeResult.executableId;
@@ -472,10 +493,10 @@ const handlers = {
         });
 
         // Return immediately
-        const body = JSON.stringify({
+        const body = JSON.stringify(stampEnvelope('run', {
           taskId, status: 'running', mode: 'headless',
           message: 'Amicus started in headless mode. Use amicus_status to check progress.',
-        });
+        }));
         // FIX 2 (#61 whole-branch review): surface the router's one-shot
         // migration notice here too — resolveRouteForLaunch already burned
         // the migration_notified flag for this vendor when it built
@@ -532,7 +553,7 @@ const handlers = {
         "Tell the user: 'Let me know when you're done with the session and have clicked Fold.' " +
         'Then wait for the user to tell you. Use amicus_read to get results once they confirm.';
 
-    const body = JSON.stringify({ taskId, status: 'running', mode, message });
+    const body = JSON.stringify(stampEnvelope('run', { taskId, status: 'running', mode, message }));
     // FIX 2 (#61 whole-branch review): the spawn path never touches stderr of
     // the CLI child that will do the routing print — this handler already
     // resolved the route in-process above, so surface its notice here.
@@ -550,6 +571,17 @@ const handlers = {
     const sessionDir = safeSessionDir(cwd, input.taskId);
     const metadata = readMetadata(input.taskId, cwd);
     if (!metadata) {
+      // Council runs live behind sessions-dir pointer files, not session dirs
+      // (v4.0 spec §8). Resolve them before failing.
+      const council = require('./mcp-council-run').buildCouncilStatusPayload(cwd, input.taskId);
+      if (council) {
+        const content = [{ type: 'text', text: JSON.stringify(council) }];
+        appendVersionWarning(content);
+        if (council.status === 'running') {
+          content.push({ type: 'text', text: HEADLESS_STATUS_REMINDER });
+        }
+        return { content };
+      }
       return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
         'If you ran it in a different project, pass the original "project".', true);
     }
@@ -608,12 +640,12 @@ const handlers = {
       }
 
       const ms = elapsedMs(metadata);
-      const response = {
-        taskId: metadata.taskId, type: 'wave', status: metadata.status,
+      const response = stampEnvelope('wave', {
+        taskId: metadata.taskId, status: metadata.status,
         legsComplete: done, legsTotal: legs.length, legs,
         elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
         version: RUNNING_VERSION,
-      };
+      });
       if (metadata.status === 'crashed' || metadata.status === 'error') {
         response.reason = metadata.reason || 'Unknown error';
       }
@@ -641,11 +673,11 @@ const handlers = {
     }
 
     const ms = elapsedMs(metadata);
-    const response = {
+    const response = stampEnvelope('run', {
       taskId: metadata.taskId, status: metadata.status,
       elapsed: `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`,
       version: RUNNING_VERSION,
-    };
+    });
     if (metadata.model) { response.model = metadata.model; }
 
     // F6: agent-visible mode (headless|interactive). metadata.mode is written at
@@ -817,7 +849,10 @@ const handlers = {
       }
     }
 
-    let sessions = Array.from(byId.values())
+    // v4.0 §8: council runs are pointer files in the same sessions root — merge
+    // them as first-class rows (type 'council-run') before sorting/filtering.
+    const councilRows = require('./mcp-council-run').listCouncilRuns(cwd);
+    let sessions = Array.from(byId.values()).concat(councilRows)
       .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
 
     if (input.status && input.status !== 'all') {
@@ -837,10 +872,10 @@ const handlers = {
     try { spawnSidecarProcess(args, sessionDir); } catch (err) {
       return textResult(`Failed to resume: ${err.message}`, true);
     }
-    return textResult(JSON.stringify({
+    return textResult(JSON.stringify(stampEnvelope('run', {
       taskId: input.taskId, status: 'running',
       message: 'Session resumed. Use amicus_status to check progress.',
-    }));
+    })));
   },
 
   async amicus_continue(input, project, mcpServer) {
@@ -857,7 +892,7 @@ const handlers = {
     if (input.model) {
       const { resolveGatewayMode } = require('./utils/config');
       const { resolveRouteForLaunch } = require('./utils/route-launch');
-      const { toStructuredError } = require('./utils/route-error');
+      const { toErrorDocFields } = require('./utils/route-error');
       const { resolveModelInputOrDefault } = require('./utils/model-input-default');
 
       const modelInput = resolveModelInputOrDefault(input.model);
@@ -869,9 +904,10 @@ const handlers = {
         validateModel: true,
       });
       if (routeResult.kind !== 'resolved') {
+        const { buildErrorDoc } = require('./utils/error-doc');
         return {
           isError: true,
-          content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+          content: [{ type: 'text', text: JSON.stringify(buildErrorDoc(toErrorDocFields(routeResult))) }],
         };
       }
       resolvedModel = routeResult.executableId;
@@ -910,16 +946,29 @@ const handlers = {
       return textResult(`Failed to continue: ${err.message}`, true);
     }
     recordSession(newTaskId, cwd); // #40: global index for cross-project lookup
-    return textResult(JSON.stringify({
+    return textResult(JSON.stringify(stampEnvelope('run', {
       taskId: newTaskId, status: 'running',
       message: 'Continuation started. Use amicus_status to check progress.',
-    }));
+    })));
   },
 
   async amicus_abort(input, project) {
     const cwd = project || getProjectDir(input.project);
     const metadata = readMetadata(input.taskId, cwd);
     if (!metadata) {
+      // Council runs resolve via the sessions-dir pointer file (v4.0 §8):
+      // mark run.json aborted + cascade to the active wave/leg records.
+      const council = require('./mcp-council-run').abortCouncilRun(cwd, input.taskId);
+      if (council) {
+        if (council.alreadyTerminal) {
+          return textResult(`Council run ${input.taskId} is not running (status: ${council.status}).`);
+        }
+        return textResult(JSON.stringify({
+          taskId: input.taskId, status: 'aborted', legsAborted: council.cascaded,
+          message: `Council run abort requested. ${council.cascaded} running leg(s) marked aborted; ` +
+            'the engine process will finalize run.json as aborted shortly.',
+        }));
+      }
       return textResult(`Session ${input.taskId} not found in project ${cwd}. ` +
         'If you ran it in a different project, pass the original "project".', true);
     }
@@ -953,11 +1002,11 @@ const handlers = {
       // if they outlive the grace window. Fire-and-forget — the tool result
       // must not block on the grace period.
       waitThenKill([metadata.pid, metadata.goPid]).catch(() => { /* best-effort */ });
-      return textResult(JSON.stringify({
+      return textResult(JSON.stringify(stampEnvelope('abort', {
         taskId: input.taskId, status: 'aborted', legsAborted,
         message: `Wave abort requested. ${legsAborted} running leg(s) marked aborted; ` +
           'the fan-out process will terminate shortly.',
-      }));
+      })));
     }
 
     // Single session: marker FIRST — the headless loop and the interactive
@@ -969,10 +1018,10 @@ const handlers = {
     markAborted(sessionDir, 'manual abort (MCP)');
     waitThenKill(metadata.pid).catch(() => { /* best-effort */ });
 
-    return textResult(JSON.stringify({
+    return textResult(JSON.stringify(stampEnvelope('abort', {
       taskId: input.taskId, status: 'aborted',
       message: 'Session abort requested. The Amicus process will terminate shortly.',
-    }));
+    })));
   },
 
   async amicus_fanout(input, project, mcpServer) {
@@ -1062,12 +1111,12 @@ const handlers = {
       return textResult(`Failed to start fan-out: ${err.message}`, true);
     }
 
-    const body = JSON.stringify({
+    const body = JSON.stringify(stampEnvelope('wave', {
       waveId, taskIds: legIds, status: 'running', mode: 'headless',
       message: 'Fan-out started. Preferred: call amicus_wait with the waveId — one blocking call ' +
         'replaces polling; re-call it while it returns timedOut: true. Fallback: poll amicus_status ' +
         'with the waveId. Either way, amicus_read the waveId when complete.',
-    });
+    }));
     return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
   },
 
@@ -1078,24 +1127,34 @@ const handlers = {
       // Auto-append to the reliability ledger (parity with `amicus council
       // tally`). Best-effort: a ledger write failure must not fail the tally.
       try { require('./council/ledger').appendRun(record); } catch { /* best-effort */ }
-      return textResult(JSON.stringify(record));
+      // v4.0 §8 (H9): fence the JSON — council output summarizes untrusted
+      // model prose entering the orchestrating agent's context. JSON intact
+      // inside the fence; CLI --json stays unfenced (the programmatic channel).
+      return textResult(fenceSidecarOutput(JSON.stringify(record)));
     } catch (err) { return textResult(`council tally failed: ${err.message}`, true); }
   },
 
   async amicus_council_stats() {
     try {
-      const { deriveReliability } = require('./council/ledger');
-      return textResult(JSON.stringify(deriveReliability()));
+      const { deriveReliability, buildStatsDoc } = require('./council/ledger');
+      return textResult(fenceSidecarOutput(JSON.stringify(buildStatsDoc(deriveReliability()))));
     } catch (err) { return textResult(`council stats failed: ${err.message}`, true); }
   },
 
   async amicus_verdict(input) {
     try {
       const { buildVerdict } = require('./council/verdict');
-      return textResult(JSON.stringify(buildVerdict(input.record, input.decisions || [])));
+      return textResult(fenceSidecarOutput(JSON.stringify(buildVerdict(input.record, input.decisions || []))));
     } catch (err) { return textResult(`verdict build failed: ${err.message}`, true); }
   },
 
+  async amicus_council_run(input, project, mcpServer) {
+    const cwd = project || getProjectDir(input.project);
+    return require('./mcp-council-run').handleCouncilRunTool(input, cwd, {
+      spawnFn: spawnSidecarProcess, clientName: detectClient(mcpServer),
+    });
+  },
+
   async amicus_setup() {
     const { checkElectronAvailable } = require('./sidecar/interactive-process');
     if (!checkElectronAvailable()) {

package/src/mcp-tools.js

@@ -421,6 +421,56 @@ function getTools() {
       project: z.string().optional().describe('Optional project directory path.'),
     },
   },
+  {
+    name: 'amicus_council_run',
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    description:
+      'Run the FULL headless council engine: Stage-1 independent reviews → ' +
+      'anonymized peer cross-review → deterministic tally → non-bench chair ' +
+      'synthesis → verdict.json + report.html, without any orchestrating agent. ' +
+      'Returns {runId, runDir} immediately (async). Preferred: call amicus_wait ' +
+      'with the runId; re-call while it returns timedOut: true. Artifacts land ' +
+      'in runDir. Exit semantics: run.json status complete (full run), partial ' +
+      '(degraded: dead leg / thin judging / no chair verdict), error, aborted.',
+    inputSchema: {
+      briefingFile: z.string().describe(
+        'Path to the briefing file (self-contained material + criteria). The file is ' +
+        'copied into the run dir; councils always brief via file (no inline prompt).'
+      ),
+      models: z.array(safeModel).min(2).max(10).optional().describe(
+        `2-10 bench seats. Short aliases (${aliasNames}) or full model IDs. Omit when using 'council'.`
+      ),
+      council: z.string().optional().describe(
+        "Run a saved council or built-in bench ('free', 'budget', 'frontier') instead of 'models'."
+      ),
+      chair: z.string().optional().describe(
+        "Chair model (default 'deepseek'). Must NOT be a bench seat; synthesizes the verdict."
+      ),
+      critic: z.string().optional().describe(
+        'Optional critic seat: one bench member swaps to an adversarial brief. Must BE a bench seat. ' +
+        'Mutually exclusive with lenses.'
+      ),
+      lenses: z.array(z.string()).optional().describe(
+        'Optional expert lenses, one per seat (count must equal seat count). Forces no-ledger. ' +
+        'Mutually exclusive with critic.'
+      ),
+      outDir: z.string().optional().describe(
+        'Run directory (default <project>/council-<runId>/).'
+      ),
+      maxCost: z.number().optional().describe(
+        'Whole-run USD ceiling, checked before each paid stage launch.'
+      ),
+      timeoutMinutes: z.number().optional().describe(
+        'Per-leg timeout in minutes (existing fanout semantics). Default: 15.'
+      ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (default), direct, or openrouter.'
+      ),
+      project: z.string().optional().describe(
+        'Optional project directory path. Auto-detected from working directory if omitted.'
+      ),
+    },
+  },
   {
     name: 'amicus_guide',
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },