amicus 3.2.3 → 4.0.1

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

package/src/prompt-builder.js

@@ -4,7 +4,7 @@
  * Spec Reference: §6 Fold Mechanism, §9 Implementation
  * Constructs system prompts for sidecar sessions in both interactive and headless modes.
  */
-const { buildFoldMarker } = require('./utils/fold-marker');
+const { buildFoldMarker, stripFoldMarkers } = require('./utils/fold-marker');
 
 /**
  * Summary template for fold output per spec §6.1
@@ -78,17 +78,19 @@ function buildSystemPrompt(briefing, context, project, headless, mode, client) {
  * @param {string} [mode='code'] - Agent mode ('code', 'ask', or 'plan')
  * @param {string} [summaryLength='normal'] - Desired summary length for headless mode
  * @param {string} [client='code-local'] - Client type for branding
- * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). Only used in
- *   headless mode: the model is instructed to emit `[SIDECAR_FOLD:<nonce>]` instead of
- *   the legacy bare `[SIDECAR_FOLD]`, so runHeadless's detector (which must be given
- *   this SAME nonce) can't be forced into completing by a model that merely echoes the
- *   public, guessable bare marker. Callers that build a headless prompt and intend to
- *   run it should generate one nonce (utils/fold-marker.generateFoldNonce()) BEFORE
- *   calling buildPrompts, pass it here, and pass the SAME value to runHeadless's
- *   options.nonce. Omitted in interactive mode (GUI fold is exit-code driven, not
- *   marker-detected) and harmless to omit in headless mode too — buildHeadlessModeSection
- *   falls back to the legacy bare marker, matching runHeadless's own no-nonce fallback.
+ * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). REQUIRED in
+ *   headless mode; ignored in interactive mode. In headless mode the model is instructed
+ *   to emit `[SIDECAR_FOLD:<nonce>]` instead of the legacy bare `[SIDECAR_FOLD]`, so
+ *   runHeadless's detector (which must be given this SAME nonce) can't be forced into
+ *   completing by a model that merely echoes the public, guessable bare marker. Callers
+ *   that build a headless prompt generate one nonce (utils/fold-marker.generateFoldNonce())
+ *   BEFORE calling buildPrompts, pass it here, and pass the SAME value to runHeadless's
+ *   options.nonce. Omitting it in headless mode THROWS (see @throws) — there is no
+ *   bare-marker fallback on this live path: a real prompt must never advertise the
+ *   guessable marker. Interactive mode ignores the nonce entirely (GUI fold is
+ *   exit-code driven, not marker-detected).
  * @returns {{system: string, userMessage: string}} Separated prompts
+ * @throws {TypeError} If `headless` is true and no `nonce` is supplied.
  *
  * @example
  * const { system, userMessage } = buildPrompts(
@@ -101,6 +103,19 @@ function buildSystemPrompt(briefing, context, project, headless, mode, client) {
  * // Use: POST /session/:id/message { system, parts: [{ type: 'text', text: userMessage }] }
  */
 function buildPrompts(briefing, context, project, headless, mode, summaryLength = 'normal', client, nonce) {
+  // 15b.3 (#BL-7 residual): a headless run MUST carry a per-run nonce so the
+  // model is instructed to emit the unguessable `[SIDECAR_FOLD:<nonce>]` — never
+  // the public, guessable bare `[SIDECAR_FOLD]`. buildPrompts is the live
+  // orchestration boundary (start / continue / fanout / mcp-server all route
+  // through it, and all four already generate and pass a nonce), so a forgotten
+  // nonce fails loud HERE rather than silently baking the bare marker into an
+  // executed prompt. Mirrors headless.js's producer precedent — extractSummary /
+  // formatFoldOutput throw a TypeError when the nonce is missing. Interactive
+  // mode is exempt: its fold is exit-code driven, not marker-detected.
+  if (headless && !nonce) {
+    throw new TypeError('buildPrompts requires a per-run nonce for headless mode (15b.3/v4.0 §9)');
+  }
+
   const systemSections = [
     buildHeader(client),
     buildEnvironmentSection(project, mode),
@@ -108,11 +123,11 @@ function buildPrompts(briefing, context, project, headless, mode, summaryLength
   ];
 
   // Strip fold markers from context so the model doesn't mimic them from
-  // previous sidecar outputs in the conversation history. Matches BOTH the
-  // legacy bare `[SIDECAR_FOLD]` and any nonced `[SIDECAR_FOLD:<nonce>]` —
-  // a resumed/continued conversation's history can carry either shape
-  // depending on when the prior turn ran (15b.3).
-  const cleanContext = context ? context.replace(/\[SIDECAR_FOLD(:[^\]]*)?\]/g, '') : context;
+  // previous sidecar outputs in the conversation history. stripFoldMarkers
+  // (src/utils/fold-marker.js) removes BOTH the legacy bare `[SIDECAR_FOLD]`
+  // and any nonced `[SIDECAR_FOLD:<nonce>]` — marker-only lines vanish
+  // entirely; inline occurrences are removed in place (v4.0 §9).
+  const cleanContext = stripFoldMarkers(context);
 
   let userMessage;
   if (headless) {
@@ -254,9 +269,11 @@ Keep track of key findings as you work.`;
  * @param {string} [nonce] - Per-run fold nonce (15b.3, #BL-7 residual). When provided,
  *   the model is instructed to emit `[SIDECAR_FOLD:<nonce>]` instead of the legacy bare
  *   `[SIDECAR_FOLD]` — see buildPrompts' @param doc for the full rationale. Falls back to
- *   the legacy bare marker when omitted (keeps this function usable standalone / by the
- *   deprecated buildSystemPrompt(), which has no orchestration-layer caller to source a
- *   nonce from).
+ *   the legacy bare marker when omitted. NOTE: buildPrompts — the live orchestration path —
+ *   now THROWS rather than reach this helper without a nonce in headless mode, so the
+ *   fallback branch is reachable ONLY via the deprecated buildSystemPrompt(), which has no
+ *   orchestration-layer caller to source a nonce from and launches no real runs. Its bare
+ *   marker is therefore inert: nothing on a live run path ever advertises the guessable form.
  * @returns {string}
  */
 function buildHeadlessModeSection(summaryLength, nonce) {

package/src/sidecar/fanout-leg.js

@@ -64,7 +64,7 @@ function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
  * Run one leg end-to-end: session record → runHeadless (shared server) →
  * leg finalize. Never throws — always resolves to a run document.
  */
-async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce }) {
+async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce, directory }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
@@ -107,7 +107,7 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
     result = await runHeadless(
       leg.model, systemPrompt, userMessage, legId, project,
       timeoutMs, agent || 'build',
-      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce }
+      { client, server, watchdog, summaryLength, reasoning, nonce: foldNonce, directory }
     );
   } catch (err) {
     result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId: legId };

package/src/sidecar/fanout.js

@@ -245,7 +245,7 @@ async function runFanout(options) {
           leg, legId: legIds[i], waveId, project, systemPrompt, userMessage,
           timeoutMs, agent: options.agent, client, server,
           summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
-          foldNonce,
+          foldNonce, directory: options.directory,
         })
       : Promise.resolve(buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }))
     )));

package/src/sidecar/resume.js

@@ -17,7 +17,7 @@ const {
 } = require('./session-utils');
 const { acquireLock, releaseLock } = require('../utils/session-lock');
 const { runHeadless } = require('../headless');
-const { extractNonceFromText, generateFoldNonce } = require('../utils/fold-marker');
+const { extractNonceFromText, generateFoldNonce, stripFoldMarkers } = require('../utils/fold-marker');
 const { logger } = require('../utils/logger');
 
 /** Load session metadata from session directory */
@@ -83,7 +83,12 @@ function buildResumeUserMessage(briefing, conversation) {
 
   if (conversation) {
     parts.push('## PREVIOUS CONVERSATION\n');
-    parts.push(conversation);
+    // v4.0 §9: the replay used to carry the previous turn's valid nonced
+    // [SIDECAR_FOLD:<nonce>] marker verbatim (BACKLOG "Resume nonce-echo
+    // hazard"). Each run mints a fresh nonce so the stale marker could never
+    // fold the new run, but a wire-format token has no business riding into
+    // the new prompt — strip every marker line before embedding.
+    parts.push(stripFoldMarkers(conversation));
     parts.push('\n---\n');
     parts.push('## RESUME\n');
     parts.push('You are resuming a previous session. Continue from where you left off.');

package/src/utils/abort-result.js

@@ -16,7 +16,7 @@ const { SCHEMA_VERSION } = require('./result-schema-version');
  * a specific taskId that exists yet was not running (already terminal) reports
  * ok:false so a scripted caller can tell "nothing happened" from "you aborted N".
  * @param {object} opts
- * @param {'session'|'wave'|'all'} opts.scope
+ * @param {'session'|'wave'|'all'|'council-run'} opts.scope
  * @param {string|null} opts.taskId - null for scope:'all'
  * @param {string[]} opts.aborted - ids actually marked aborted (session/wave id + any legs)
  * @returns {object} abort document

package/src/utils/error-doc.js

@@ -20,6 +20,8 @@ const ERROR_CODES = Object.freeze({
   BAD_SESSION: 'BAD_SESSION',       // task id missing / invalid / not found
   BUDGET_EXCEEDED: 'BUDGET_EXCEEDED', // the WS-2 #10 spend gate
   INTERNAL: 'INTERNAL',             // unexpected pre-flight throw
+  COUNCIL_QUORUM: 'COUNCIL_QUORUM', // council run: <2 surviving Stage-1 reviews (v4.0 §4)
+  COST_EXCEEDED: 'COST_EXCEEDED',   // council run: whole-run --max-cost ceiling hit pre-tally (v4.0 §4)
 });
 
 /**

package/src/utils/fold-marker.js

@@ -70,10 +70,31 @@ function extractNonceFromText(text) {
   return m ? m[1] : null;
 }
 
+/**
+ * v4.0 §9 (BL-7 done-done): remove every fold-marker occurrence — bare
+ * `[SIDECAR_FOLD]` and nonced `[SIDECAR_FOLD:<nonce>]` — from a text.
+ * A line consisting of ONLY a marker (plus horizontal whitespace) is removed
+ * together with its line terminator; a marker embedded mid-line is removed in
+ * place, keeping the rest of the line. Superset of prompt-builder.js's old
+ * inline regex (which left empty lines behind) — used by the resume replay
+ * (src/sidecar/resume.js) and buildPrompts (src/prompt-builder.js) so a
+ * replayed conversation never carries a stale wire-format token.
+ * @param {string|null|undefined} text
+ * @returns {string|null|undefined} falsy input is returned unchanged
+ */
+function stripFoldMarkers(text) {
+  if (!text) { return text; }
+  const marker = `\\[${FOLD_MARKER_PREFIX}(:[^\\]]*)?\\]`;
+  const markerOnlyLine = new RegExp(`^[^\\S\\r\\n]*${marker}[^\\S\\r\\n]*(?:\\r?\\n|$)`, 'gm');
+  const inlineMarker = new RegExp(marker, 'g');
+  return text.replace(markerOnlyLine, '').replace(inlineMarker, '');
+}
+
 module.exports = {
   FOLD_MARKER_PREFIX,
   generateFoldNonce,
   buildFoldMarker,
   trailingFoldMarkerRegex,
   extractNonceFromText,
+  stripFoldMarkers,
 };

package/src/utils/route-error.js

@@ -145,9 +145,35 @@ function toCliMessage(result) {
   return lines.join('\n');
 }
 
+/**
+ * v4.0 §7: map a RouteResult onto error-doc fields ({code, message, hint})
+ * for buildErrorDoc/failJson — the CLI --json and MCP failure surfaces.
+ * Key-shaped reasons map to MISSING_KEY; everything else is BAD_MODEL.
+ * Suggestions are inlined into the message text (the error doc has no
+ * structured suggestions slot; the hint carries the fix line).
+ * @param {object} result a RouteResult with kind 'error' or 'selection_required'
+ * @returns {{code: string, message: string, hint: (string|null)}}
+ */
+function toErrorDocFields(result) {
+  const { ERROR_CODES } = require('./error-doc');
+  const KEY_REASONS = ['no_openrouter_key', 'no_direct_key', 'no_key_for_vendor'];
+  const err = toStructuredError(result);
+  const sentence = REASON_TEXT[err.reason] || `Model routing error (${err.reason}).`;
+  let message = err.requested ? `${sentence} (requested "${err.requested}")` : sentence;
+  if (err.suggestions.length > 0) {
+    message += ` Did you mean: ${err.suggestions.map((s) => s && s.model).filter(Boolean).join(', ')}?`;
+  }
+  return {
+    code: KEY_REASONS.includes(err.reason) ? ERROR_CODES.MISSING_KEY : ERROR_CODES.BAD_MODEL,
+    message,
+    hint: FIX_HINTS[err.reason] || null,
+  };
+}
+
 module.exports = {
   toStructuredError,
   toCliMessage,
+  toErrorDocFields,
   REASON_TEXT,
   ROUTE_ERROR_REASONS,
   SELECTION_REQUIRED_REASON,

package/src/utils/start-helpers.js

@@ -46,7 +46,8 @@ function deriveAlias(args) {
 async function resolveLaunchModel(args) {
   const { resolveGatewayMode } = require('./config');
   const { resolveRouteForLaunch } = require('./route-launch');
-  const { toCliMessage, toStructuredError } = require('./route-error');
+  const { toCliMessage, toErrorDocFields } = require('./route-error');
+  const { failJson, ERROR_CODES } = require('./error-doc');
   const { resolveModelInputOrDefault } = require('./model-input-default');
 
   const gatewayMode = resolveGatewayMode(args.gateway);
@@ -66,9 +67,13 @@ async function resolveLaunchModel(args) {
   // via model-input-default.js, so this lookup lives in exactly one place.
   const modelInput = resolveModelInputOrDefault(args.model);
   if (modelInput === undefined) {
-    process.stderr.write(
-      'No model specified and no default configured. Run \'amicus setup\' to set a default model.\n'
-    );
+    const message = 'No model specified and no default configured. Run \'amicus setup\' to set a default model.';
+    if (args.json) {
+      // v4.0 §7: --json pre-flight failures land on STDOUT as the error doc.
+      failJson(true, { code: ERROR_CODES.BAD_MODEL, message, hint: 'amicus setup' });
+    } else {
+      process.stderr.write(`${message}\n`);
+    }
     process.exit(1);
   }
 
@@ -106,17 +111,21 @@ async function resolveLaunchModel(args) {
         provenance: result.provenance || {},
       };
     } catch (err) {
-      process.stderr.write(`${err.message || 'Model selection cancelled.'}\n`);
+      const message = err.message || 'Model selection cancelled.';
+      if (args.json) {
+        failJson(true, { code: ERROR_CODES.BAD_MODEL, message,
+          hint: 'Pass --model <vendor/model> explicitly to skip the picker.' });
+      } else {
+        process.stderr.write(`${message}\n`);
+      }
       process.exit(1);
     }
   }
 
-  // 'error': render and exit. (A non-interactive run never reaches
-  // kind:'selection_required' — allowSelection is false there, so the router
-  // resolves a catalog miss straight to kind:'error' with reason
-  // 'model_not_found' instead; see gateway-router.js's catalogGate.)
+  // 'error': render and exit. Under --json the error doc goes to STDOUT
+  // (v4.0 §7 — was toStructuredError on stderr); human stderr is unchanged.
   if (args.json) {
-    process.stderr.write(`${JSON.stringify(toStructuredError(result))}\n`);
+    failJson(true, toErrorDocFields(result));
   } else {
     process.stderr.write(`${toCliMessage(result)}\n`);
   }