amicus 3.2.2 → 4.0.0

package/src/council/run-state.js

@@ -0,0 +1,122 @@
+// src/council/run-state.js
+'use strict';
+
+/**
+ * @module council/run-state
+ * Durable state for one headless council run (spec §4/§5): atomic run.json
+ * read/write with checkpoint semantics, plus the sessions-dir pointer file
+ * (`council-<runId>.json` → {runId, runDir}) that lets status/wait/list/abort
+ * resolve council runIds without knowing --out-dir.
+ *
+ * Abort-wins: once run.json's status is 'aborted', no later checkpoint can
+ * demote it (same precedence rule as fanout's writeWaveMetadata — an external
+ * `amicus abort` must never lose a write race against the engine's own
+ * finalize).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomic } = require('../utils/atomic-write');
+const { SESSIONS_DIR } = require('../session-manager');
+
+const RUN_FILE = 'run.json';
+
+function runPath(runDir) { return path.join(runDir, RUN_FILE); }
+
+/** @returns {object|null} parsed run.json, or null when missing/corrupt */
+function readRun(runDir) {
+  try { return JSON.parse(fs.readFileSync(runPath(runDir), 'utf-8')); }
+  catch { return null; }
+}
+
+/** Abort-wins merge: once status is 'aborted', it cannot change to anything else. */
+function mergeRun(existing, patch) {
+  const merged = { ...existing, ...patch };
+  // If the prior run was aborted, preserve that status regardless of patch content
+  // (prevents falsy status values, null, '', or omitted status from overwriting)
+  if (existing.status === 'aborted' || patch.status === 'aborted') {
+    merged.status = 'aborted';
+    // An aborted run is terminal: never let a later (racing) finalize report a
+    // clean/degraded exitCode. Prefer a recorded abort code, then a patch abort
+    // code, else default SIGTERM's 143.
+    const prior = [130, 143].includes(existing.exitCode) ? existing.exitCode : null;
+    const fromPatch = [130, 143].includes(patch.exitCode) ? patch.exitCode : null;
+    merged.exitCode = prior || fromPatch || 143;
+  }
+  return merged;
+}
+
+function writeRun(runDir, run) {
+  writeFileAtomic(runPath(runDir), JSON.stringify(run, null, 2), { mode: 0o600 });
+  return run;
+}
+
+/** Create (or merge into) run.json; preserves an existing createdAt. */
+function initRun(runDir, seed) {
+  fs.mkdirSync(runDir, { recursive: true, mode: 0o700 });
+  const existing = readRun(runDir) || {};
+  const run = mergeRun(existing, {
+    ...seed,
+    createdAt: existing.createdAt || seed.createdAt,
+  });
+  return writeRun(runDir, run);
+}
+
+/** Read-merge-write checkpoint (atomic; abort-wins on status). */
+function checkpoint(runDir, patch) {
+  const existing = readRun(runDir) || {};
+  return writeRun(runDir, mergeRun(existing, patch));
+}
+
+/** Upsert one stages[] entry by name; other stages and order preserved. */
+function updateStage(runDir, name, patch) {
+  const existing = readRun(runDir) || {};
+  const stages = Array.isArray(existing.stages) ? existing.stages.slice() : [];
+  const i = stages.findIndex(s => s && s.name === name);
+  if (i === -1) { stages.push({ name, ...patch }); }
+  else { stages[i] = { ...stages[i], ...patch }; }
+  return checkpoint(runDir, { stages });
+}
+
+function stripPrefix(runId) { return String(runId).replace(/^council-/, ''); }
+
+/** `<project>/.claude/amicus_sessions/council-<runId>.json` */
+function pointerPath(project, runId) {
+  return path.join(project, '.claude', SESSIONS_DIR, `council-${stripPrefix(runId)}.json`);
+}
+
+function writePointer(project, runId, runDir) {
+  const p = pointerPath(project, runId);
+  fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+  writeFileAtomic(p, JSON.stringify({ runId: stripPrefix(runId), runDir }, null, 2), { mode: 0o600 });
+  return p;
+}
+
+/** @returns {{runId: string, runDir: string}|null} */
+function readPointer(project, runId) {
+  try {
+    const ptr = JSON.parse(fs.readFileSync(pointerPath(project, runId), 'utf-8'));
+    return (ptr && ptr.runId && ptr.runDir) ? ptr : null;
+  } catch { return null; }
+}
+
+/** All council pointers in the project sessions dir. */
+function listPointers(project) {
+  const root = path.join(project, '.claude', SESSIONS_DIR);
+  let names = [];
+  try { names = fs.readdirSync(root); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!/^council-[a-zA-Z0-9_-]{1,64}\.json$/.test(n)) { continue; }
+    try {
+      const ptr = JSON.parse(fs.readFileSync(path.join(root, n), 'utf-8'));
+      if (ptr && ptr.runId && ptr.runDir) { out.push(ptr); }
+    } catch { /* skip corrupt pointer */ }
+  }
+  return out;
+}
+
+module.exports = {
+  RUN_FILE, readRun, initRun, checkpoint, updateStage,
+  pointerPath, writePointer, readPointer, listPointers,
+};

package/src/council/run.js

@@ -0,0 +1,269 @@
+// src/council/run.js
+'use strict';
+
+/**
+ * @module council/run
+ * Headless council driver (spec §5): stage state machine over the DI launch
+ * wrappers — Stage-1 reviews → anonymized Stage-2 cross-review → tally →
+ * chair synthesis → verdict/report — checkpointing run.json after every
+ * stage (run-state) and consuming the existing pure primitives unchanged
+ * (tally, buildVerdict via run-assemble, report renderers, ledger).
+ *
+ * Tally sequencing: an in-memory provisional tally feeds the chair packet;
+ * the on-disk tally-input.json/tally.json are FINAL (chair runStats row
+ * included, actual chair in meta) and only the final record is ledgered —
+ * the skill's debate-mode provisional/final precedent.
+ *
+ * Never rejects for run errors: always resolves {exitCode, run}.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { tally } = require('./tally');
+const { assignLabels, toGlobalFindings } = require('./anonymize');
+const briefings = require('./briefings');
+const stage2 = require('./briefings-stage2');
+const { parseChairVerdict } = require('./parse-stage2');
+const runState = require('./run-state');
+const { createLaunchers } = require('./run-launch');
+const { runStage1, runStage2, isAbortExit } = require('./run-stages');
+const asm = require('./run-assemble');
+const { sumWaveUsage } = require('../utils/pricing');
+
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143, SIGBREAK: 143 };
+
+/**
+ * Chair fallback promotion (spec §4): the highest peers-only street-cred
+ * model from `council stats` that is not a bench seat and not the failed
+ * chair. "Highest street-cred" = BEST = numerically LOWEST mean rank
+ * (deriveReliability's avgStreetCredPeersOnly; lower is better).
+ * @returns {string|null}
+ */
+function pickFallbackChair(statsRows, bench, failedChair) {
+  const benchSet = new Set(bench);
+  const candidates = (statsRows || [])
+    .filter(r => !benchSet.has(r.model) && r.model !== failedChair
+      && typeof r.avgStreetCredPeersOnly === 'number')
+    .sort((a, b) => a.avgStreetCredPeersOnly - b.avgStreetCredPeersOnly);
+  return candidates.length ? candidates[0].model : null;
+}
+
+/**
+ * @param {object} options {briefing, models, chair, critic?, lenses?, project,
+ *   runId, runDir, timeout?, maxCost?, gateway?, noValidateModel?, date}
+ * @param {object} [deps] {launchers?, appendRunFn?, statsFn?, installSignalAbortFn?}
+ * @returns {Promise<{exitCode: number, run: object}>}
+ */
+async function runCouncil(options, deps = {}) {
+  const o = { critic: null, lenses: null, maxCost: null, ...options };
+  const launchers = deps.launchers || createLaunchers();
+  const appendRunFn = deps.appendRunFn || require('./ledger').appendRun;
+  const statsFn = deps.statsFn || require('./ledger').deriveReliability;
+  const installSignals = deps.installSignalAbortFn
+    || require('../utils/session-abort').installSignalAbort;
+  const now = () => new Date().toISOString();
+
+  const allLegs = [];
+  const addWave = (wave) => { if (wave && Array.isArray(wave.legs)) { allLegs.push(...wave.legs); } };
+  const spent = () => {
+    const c = sumWaveUsage(allLegs).cost;
+    return typeof c.amount === 'number' ? c.amount : 0;
+  };
+  const overBudget = () => o.maxCost !== null && o.maxCost !== undefined && spent() >= o.maxCost;
+
+  runState.initRun(o.runDir, {
+    schemaVersion: 2, type: 'council-run', runId: o.runId, status: 'running', stages: [],
+    bench: o.models.slice(), chair: o.chair, critic: o.critic, lenses: o.lenses,
+    labelMap: null,
+    options: { timeout: o.timeout || null, maxCost: o.maxCost, gateway: o.gateway || 'auto', outDir: o.runDir },
+    usage: null, pid: process.pid, createdAt: now(),
+  });
+  runState.writePointer(o.project, o.runId, o.runDir);
+
+  let signalled = null;
+  const uninstall = installSignals({
+    onAbort: (signal) => {
+      signalled = SIGNAL_EXIT[signal] || 143;
+      runState.checkpoint(o.runDir, { status: 'aborted', exitCode: signalled, completedAt: now() });
+    },
+  });
+
+  const degraded = { value: false };
+  const finalize = (exitCode, error) => {
+    uninstall();
+    const code = signalled || exitCode;
+    const status = (code === 130 || code === 143) ? 'aborted'
+      : code === 0 ? 'complete' : code === 1 ? 'error' : 'partial';
+    const run = runState.checkpoint(o.runDir, {
+      status, exitCode: code, error: error || null,
+      usage: { cost: sumWaveUsage(allLegs).cost },
+      completedAt: now(),
+    });
+    return { exitCode: code, run };
+  };
+
+  const ctx = { o, launchers, addWave, overBudget, scratchDir: path.join(o.runDir, '_scratch') };
+
+  try {
+    // Composed Stage-1 seat briefing persisted for auditability (spec §4 layout).
+    fs.writeFileSync(path.join(o.runDir, 'briefing-stage1.md'),
+      briefings.buildSeatBriefing({ briefing: o.briefing, date: o.date }), { mode: 0o600 });
+
+    // ---- Stage 1: independent reviews ----
+    runState.updateStage(o.runDir, 'stage1',
+      { status: 'running', startedAt: now(), waveId: `${o.runId}-s1`, project: o.runDir });
+    const s1 = await runStage1(ctx);
+    runState.updateStage(o.runDir, 'stage1', {
+      status: 'complete', completedAt: now(),
+      taskIds: s1.reviews.map(r => (r.leg && r.leg.taskId)).filter(Boolean),
+    });
+    if (signalled || s1.aborted) { return finalize(s1.aborted || signalled); }
+    if (s1.deadLegs.length > 0) { degraded.value = true; } // bench shrank → never a "full run"
+    if (s1.reviews.length < 2) {
+      return finalize(1, {
+        code: 'COUNCIL_QUORUM',
+        message: `Only ${s1.reviews.length} Stage-1 review(s) survived; a council needs at least 2`,
+      });
+    }
+
+    // ---- Cost gate: Stage 2 is a paid launch; no tally exists yet (spec §4) ----
+    if (overBudget()) {
+      return finalize(1, {
+        code: 'COST_EXCEEDED',
+        message: `Cost ceiling $${o.maxCost} reached before cross-review; no tally exists`,
+      });
+    }
+
+    // ---- Stage 2: anonymized cross-review ----
+    const labels = assignLabels(s1.reviews.map(r => r.model));
+    runState.checkpoint(o.runDir, { labelMap: labels.labelMap });
+    // Attach each review's run-global findings (buildTallyInput reads
+    // r.globalFindings per review, not a bare parallel array).
+    s1.reviews.forEach((r, i) => {
+      r.globalFindings = toGlobalFindings(labels.entries[i].letter, r.model, r.findings);
+    });
+    const globalFindings = s1.reviews.flatMap(r => r.globalFindings);
+    runState.updateStage(o.runDir, 'stage2',
+      { status: 'running', startedAt: now(), waveId: `${o.runId}-s2`, project: ctx.scratchDir });
+    const s2 = await runStage2(ctx, { reviews: s1.reviews, labels, globalFindings });
+    runState.updateStage(o.runDir, 'stage2', { status: 'complete', completedAt: now() });
+    if (signalled || s2.aborted) { return finalize(s2.aborted || signalled); }
+    if (s2.judgeResults.filter(j => j.ok).length < 2) { degraded.value = true; } // thin cross-review
+
+    // Merge Stage-2 judging conformance into each seat's row (worst wins).
+    const byJudge = new Map(s2.judgeResults.map(j => [j.judge, j]));
+    for (const r of s1.reviews) {
+      const j = byJudge.get(r.model);
+      if (j) { r.conformance = asm.worseConformance(r.conformance, j.conformance); }
+    }
+
+    // ---- Chair synthesis (provisional tally feeds the packet) ----
+    const mkInput = (chairStats, chairModel) => asm.buildTallyInput({
+      runId: o.runId, date: o.date, bench: o.models.slice(), chair: chairModel,
+      reviews: s1.reviews, judgeResults: s2.judgeResults, chairStats,
+    });
+    const provisionalInput = mkInput(null, o.chair);
+    const provisional = tally(provisionalInput);
+
+    const packet = stage2.buildChairPacket({
+      reviews: s1.reviews.map(r => ({ model: r.model, text: r.text })),
+      rankings: provisionalInput.rankings,
+      adjudications: provisionalInput.adjudications,
+      tierCounts: provisional.tierCounts,
+    });
+    fs.writeFileSync(path.join(o.runDir, 'chair-packet.md'), packet, { mode: 0o600 });
+    const attemptChair = async (model, waveId) => {
+      const solo = await launchers.launchSolo({
+        model, prompt: packet, project: o.runDir, waveId,
+        timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      addWave(solo.wave);
+      const ok = solo.leg && solo.leg.status === 'complete'
+        && solo.leg.summary && solo.leg.summary.trim();
+      return { leg: ok ? solo.leg : null, exitCode: solo.exitCode };
+    };
+
+    let chairLeg = null;
+    let actualChair = null;
+    if (overBudget()) {
+      // Ceiling hit after the tally is computable: skip the chair, write the
+      // verdict with overallVerdict null, exit 2 (spec §4 degradation table).
+      // Never abort in-flight legs for cost — this only stops NEW launches.
+      degraded.value = true;
+      runState.updateStage(o.runDir, 'chair', { status: 'skipped', completedAt: now() });
+    } else {
+      runState.updateStage(o.runDir, 'chair', { status: 'running', startedAt: now(), project: o.runDir });
+      // Fallback chain (spec §4): retry same chair once → promote best
+      // non-bench model from the ledger → give up (no Claude fallback headless).
+      let attempt = await attemptChair(o.chair, `${o.runId}-ch1`);
+      if (isAbortExit(attempt.exitCode) || signalled) { return finalize(attempt.exitCode || signalled); }
+      if (!attempt.leg && !overBudget()) {
+        attempt = await attemptChair(o.chair, `${o.runId}-ch2`);
+        if (isAbortExit(attempt.exitCode) || signalled) { return finalize(attempt.exitCode || signalled); }
+      }
+      if (attempt.leg) { actualChair = o.chair; }
+      else if (!overBudget()) {
+        let statsRows = [];
+        try { statsRows = statsFn(); } catch { /* no ledger yet */ }
+        const fallback = pickFallbackChair(statsRows, o.models, o.chair);
+        if (fallback) {
+          attempt = await attemptChair(fallback, `${o.runId}-ch3`);
+          if (isAbortExit(attempt.exitCode) || signalled) { return finalize(attempt.exitCode || signalled); }
+          if (attempt.leg) { actualChair = fallback; }
+        }
+      }
+      chairLeg = attempt.leg;
+      runState.updateStage(o.runDir, 'chair',
+        { status: chairLeg ? 'complete' : 'error', completedAt: now() });
+      // The chair chain may have promoted a fallback (or given up) — checkpoint
+      // the ACTUAL chair into run.json now so status/`--json`/the human summary
+      // never report the originally-requested chair after a promotion. Mirrors
+      // mkInput's actualChair || o.chair (a give-up with no actual chair keeps
+      // the requested chair).
+      runState.checkpoint(o.runDir, { chair: actualChair || o.chair });
+    }
+    const chairText = chairLeg ? chairLeg.summary : null;
+    let chairConformance = 'clean';
+
+    // ---- Chair VERDICT line (one repair re-prompt, spec §5) ----
+    let overallVerdict = chairText ? parseChairVerdict(chairText) : null;
+    if (chairText && !overallVerdict && !overBudget()) {
+      const repair = await launchers.launchSolo({
+        model: actualChair, prompt: stage2.buildChairRepairPrompt(),
+        project: o.runDir, waveId: `${o.runId}-ch4`,
+        timeout: o.timeout, gateway: o.gateway, noValidateModel: o.noValidateModel,
+      });
+      addWave(repair.wave);
+      if (isAbortExit(repair.exitCode) || signalled) { return finalize(repair.exitCode || signalled); }
+      overallVerdict = parseChairVerdict((repair.leg && repair.leg.summary) || '');
+      chairConformance = overallVerdict ? 'repaired' : 'unstructured';
+    }
+    // A completed chair whose verdict never parsed is 'unstructured' even when
+    // the repair was skipped (e.g. the chair leg itself tripped --max-cost).
+    if (chairText && !overallVerdict) { chairConformance = 'unstructured'; }
+    if (!chairLeg || !overallVerdict) { degraded.value = true; } // spec table: exit 2 rows
+
+    // ---- Final tally (chair row included) + ledger + artifacts ----
+    const chairStats = chairLeg ? asm.buildRunStatsEntry({
+      leg: chairLeg, model: actualChair, role: 'chair', wasChair: true,
+      conformance: chairConformance,
+    }) : null;
+    const finalInput = mkInput(chairStats, actualChair || o.chair);
+    const record = tally(finalInput);
+    if (!o.lenses) {
+      // Lens runs never feed cross-run reliability stats (spec §4 / skill rule).
+      try { appendRunFn(record); }
+      catch (e) { process.stderr.write(`Notice: council ledger append failed: ${e.message}\n`); }
+    }
+    asm.writeTallyFiles({ runDir: o.runDir, tallyInput: finalInput, record });
+    runState.updateStage(o.runDir, 'tally', { status: 'complete', completedAt: now() });
+    asm.writeVerdictFiles({ runDir: o.runDir, record, overallVerdict, chairText });
+    runState.updateStage(o.runDir, 'verdict', { status: 'complete', completedAt: now() });
+
+    return finalize(degraded.value ? 2 : 0);
+  } catch (err) {
+    return finalize(1, { code: 'INTERNAL', message: err.message });
+  }
+}
+
+module.exports = { runCouncil, pickFallbackChair, SIGNAL_EXIT };

package/src/council/tally.js

@@ -66,7 +66,8 @@ function computeStreetCred(rankings, models) {
   });
 }
 
-const COUNCIL_SCHEMA_VERSION = 1;
+// v4.0 §7: council family v2 — every council doc carries {schemaVersion, type}.
+const COUNCIL_SCHEMA_VERSION = 2;
 const VERDICTS = { agree: 'a', dispute: 'd', neutral: 'n' };
 
 function countTiers(findings) {
@@ -106,6 +107,7 @@ function tally(input) {
   });
   return {
     schemaVersion: COUNCIL_SCHEMA_VERSION,
+    type: 'council-tally',
     meta,
     judged: Array.isArray(rankings) && rankings.length >= 2,
     streetCred: computeStreetCred(rankings || [], meta.models),

package/src/council/verdict.js

@@ -2,23 +2,30 @@
 'use strict';
 const fs = require('fs');
 
-const VERDICT_SCHEMA_VERSION = 1;
+// v4.0 §7: council family v2 — verdict docs carry {schemaVersion, type} and a
+// nullable overallVerdict (the chair's Ship-it line; populated by the headless
+// engine in Plan B via opts.overallVerdict, null in every Stage-4 manual path).
+const VERDICT_SCHEMA_VERSION = 2;
 
 /**
  * Merge a tally record with Claude's Stage-4 decisions into the verdict record.
  * @param {object} record  tally() output
  * @param {Array<{id,decision,applied,duplicateOf,tierOverride}>} decisions
+ * @param {{overallVerdict?: (string|null)}} [opts] engine hook (Plan B): the
+ *   parsed chair `VERDICT:` line; omitted/undefined → null.
  */
-function buildVerdict(record, decisions = []) {
+function buildVerdict(record, decisions = [], opts = {}) {
   const byId = new Map(decisions.map(d => [d.id, d]));
   return {
     schemaVersion: VERDICT_SCHEMA_VERSION,
+    type: 'council-verdict',
     runId: record.meta.runId,
     runType: record.meta.runType,
     date: record.meta.date,
     chair: record.meta.chair,
     council: record.meta.models,
     claudeInCouncil: record.meta.claudeInCouncil,
+    overallVerdict: opts.overallVerdict === undefined ? null : opts.overallVerdict,
     findings: record.findings.map(f => {
       const d = byId.get(f.id) || {};
       const tierOverride = d.tierOverride || f.tierOverride || null;

package/src/headless.js

@@ -22,7 +22,8 @@ const { buildFoldMarker, trailingFoldMarkerRegex, generateFoldNonce } = require(
  *
  * #BL-7 residual (15b.3): the bare `[SIDECAR_FOLD]` string is now a LEGACY
  * literal only, kept exported for external consumers with no nonce context
- * (see extractSummary/formatFoldOutput's no-nonce fallback paths below).
+ * (the no-nonce fallback paths were retired in v4.0 §9 — the constant is
+ * export-only back-compat now).
  * NOTE for anyone `.toContain('[SIDECAR_FOLD]')`-checking real run output:
  * that substring check does NOT match the real nonced marker — a nonced
  * marker is `[SIDECAR_FOLD:<nonce>]`, which lacks the literal closing
@@ -716,46 +717,42 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
  * Extract summary from output (everything before the trailing fold marker)
  * Spec Reference: §6.2 - Return summary (everything before the fold marker)
  *
+ * v4.0 §9 (BL-7 done-done): `nonce` is REQUIRED for any non-empty output.
+ * The pre-15b.3 no-nonce fallback (matching the legacy bare `[SIDECAR_FOLD]`
+ * marker) is retired — no code path, internal or external, may complete on a
+ * bare marker. Callers with no nonce have no valid marker to split on and
+ * must not call this.
+ *
  * @param {string} output - Raw output from OpenCode
- * @param {string} [nonce] - This run's fold nonce (15b.3). When omitted, falls
- *   back to matching the LEGACY bare `[SIDECAR_FOLD]` marker — this keeps
- *   extractSummary usable as a standalone string utility (e.g. re-processing
- *   output captured before the nonce scheme, or a caller that genuinely has
- *   no nonce context) without ever accepting a WRONG nonce as a match.
+ * @param {string} nonce - This run's fold nonce (required for non-empty output)
  * @returns {string} Extracted summary
+ * @throws {TypeError} when output is non-empty and nonce is missing/empty
  */
 function extractSummary(output, nonce) {
   if (!output) {
     return '';
   }
+  if (!nonce) {
+    throw new TypeError('extractSummary requires a per-run nonce (15b.3/v4.0 §9)');
+  }
 
   // Split on the fold marker only when it is the FINAL non-empty line (#BL-7).
   // A marker echoed mid-output (describing code, reproducing these
   // instructions, or from scraped content) is NOT a delimiter — keep it as
   // content. Only the true trailing marker is stripped.
-  const idx = nonce ? findTrailingFoldMarker(output, nonce) : findLegacyBareTrailingMarker(output);
+  const idx = findTrailingFoldMarker(output, nonce);
   if (idx !== -1) {
     return output.slice(0, idx).trim();
   }
   return output.trim();
 }
 
-/**
- * Legacy bare-marker trailing match (`[SIDECAR_FOLD]`, no nonce) — the
- * pre-15b.3 behavior, kept only for extractSummary's no-nonce fallback path.
- * NEVER used by runHeadless's own detection (that always carries a nonce —
- * see findTrailingFoldMarker), so no live completion path can be forced by a
- * bare marker.
- * @param {string} output
- * @returns {number}
- */
-function findLegacyBareTrailingMarker(output) {
-  const m = /^[^\S\r\n]*\[SIDECAR_FOLD\][^\S\r\n]*$(?![\s\S]*\S)/m.exec(output);
-  return m ? m.index : -1;
-}
-
 /**
  * Format a structured fold output with metadata
+ * v4.0 §9: `nonce` is REQUIRED — the pre-15b.3 bare-`[SIDECAR_FOLD]` writer
+ * fallback is retired; the bare literal is never written by any path. The
+ * FOLD_MARKER/COMPLETE_MARKER constants remain exported for external
+ * consumers' greps/back-compat only (docs/SHIMS.md).
  * @param {Object} options - Fold output options
  * @param {string} options.model - Model identifier
  * @param {string} options.sessionId - Session identifier
@@ -763,14 +760,16 @@ function findLegacyBareTrailingMarker(output) {
  * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
  * @param {string} [options.mode='headless'] - Execution mode
  * @param {string} options.summary - Summary text
- * @param {string} [options.nonce] - This run's fold nonce (15b.3). When omitted,
- *   falls back to the legacy bare `[SIDECAR_FOLD]` marker for back-compat with
- *   external callers of this exported utility that predate the nonce scheme.
+ * @param {string} options.nonce - This run's fold nonce (required)
  * @returns {string} Formatted fold output
+ * @throws {TypeError} when nonce is missing/empty
  */
 function formatFoldOutput({ model, sessionId, client, cwd, mode, summary, nonce }) {
+  if (!nonce) {
+    throw new TypeError('formatFoldOutput requires a per-run nonce (15b.3/v4.0 §9)');
+  }
   return [
-    nonce ? buildFoldMarker(nonce) : FOLD_MARKER,
+    buildFoldMarker(nonce),
     `Model: ${model}`,
     `Session: ${sessionId}`,
     `Client: ${client || 'code-local'}`,