@sabaiway/agent-workflow-kit 10.4.0 → 10.6.0

package/tools/review-roster-resolve.mjs

@@ -0,0 +1,104 @@
+import { safeLine, REVIEW_CMD_ALIASES } from './carriers.mjs';
+import { READY, NEEDS_SKILL, NEEDS_CLI, NEEDS_CREDENTIALS, DEGRADED } from './detect-backends.mjs';
+import { parseSlotToken, validateRoster } from './review-roster.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+const READY_STATES = new Set([READY, 'placed', 'customized']);
+
+const setupTarget = (entry) => entry?.setupHint?.local ?? entry?.setupHint?.url ?? null;
+
+export const remedyFor = (entry = {}) => {
+  const setup = setupTarget(entry);
+  if (entry.readiness === NEEDS_SKILL) return setup ? `bridge skill not installed — ${safeLine(setup)}` : 'bridge skill not installed — run /agent-workflow-kit setup';
+  if (entry.readiness === NEEDS_CLI) return setup ? `the CLI is not installed — ${safeLine(setup)}` : 'the CLI is not installed';
+  if (entry.readiness === NEEDS_CREDENTIALS) return 'not signed in (credentials missing)';
+  if (entry.readiness === DEGRADED) return 'wrapper not on PATH — run /agent-workflow-kit setup';
+  return entry.readiness ? safeLine(entry.readiness) : 'bridge readiness unavailable';
+};
+
+export const lensVehicleSpec = (member) => {
+  const parsed = typeof member === 'string' ? parseSlotToken(member) : member;
+  if (parsed.kind !== 'lens') throw new Error(`not a lens member: ${parsed.member ?? member}`);
+  return {
+    stem: parsed.stem,
+    template: parsed.template,
+    model: parsed.model,
+    effort: parsed.effort,
+    tools: 'read-only',
+    derived: parsed.derived,
+  };
+};
+
+export const deriveLensTemplate = (template, spec) => {
+  if (!spec?.derived) return String(template);
+  return String(template)
+    .replace(/^name:.*$/mu, `name: ${spec.stem}`)
+    .replace(/^model:.*$/mu, `model: ${spec.model}`)
+    .replace(/^effort:.*$/mu, `effort: ${spec.effort}`);
+};
+
+const postureValue = (postures, receiptId) => {
+  const value = postures?.[receiptId];
+  if (typeof value === 'string') return value;
+  return value?.state === 'valid' ? value.posture : null;
+};
+
+const bridgeRow = (parsed, readiness, postures) => {
+  const alias = REVIEW_CMD_ALIASES[parsed.instrument];
+  const entry = readiness.find((candidate) => candidate?.name === alias.backend);
+  const state = entry?.readiness ?? NEEDS_SKILL;
+  return {
+    member: parsed.member,
+    stem: parsed.stem,
+    kind: 'bridge',
+    state,
+    reason: state === READY ? null : remedyFor({ ...entry, readiness: state }),
+    posture: postureValue(postures, parsed.stem),
+  };
+};
+
+const lensRow = (parsed, surveyLens) => {
+  if (typeof surveyLens !== 'function') {
+    return {
+      member: parsed.member, stem: parsed.stem, kind: 'lens', state: 'unsurveyed',
+      reason: null, posture: null,
+    };
+  }
+  const survey = surveyLens(lensVehicleSpec(parsed)) ?? {};
+  const state = survey.state ?? 'unusable';
+  const posture = READY_STATES.has(state) && survey.model && survey.effort
+    ? `model=${safeLine(survey.model)} effort=${safeLine(survey.effort)}`
+    : null;
+  return {
+    member: parsed.member,
+    stem: parsed.stem,
+    kind: 'lens',
+    state,
+    reason: survey.reason == null ? null : safeLine(survey.reason),
+    posture,
+  };
+};
+
+export const resolveRoster = ({ value, readiness = [], surveyLens, postures } = {}) => {
+  validateRoster(value);
+  return value.map((member) => {
+    const parsed = parseSlotToken(member);
+    return parsed.kind === 'bridge'
+      ? bridgeRow(parsed, readiness, postures)
+      : lensRow(parsed, surveyLens);
+  });
+};
+
+export const isReadyMember = (row) => READY_STATES.has(row.state);
+
+export const skippedLine = (row, remedy = row.reason) =>
+  `skipped this round — ${safeLine(row.state)}: ${remedy ?? 'no remedy recorded'}`;
+
+export const rosterLabel = (roster, { states = true } = {}) => roster.map((row) => {
+  if (!states || isReadyMember(row)) return row.member;
+  return `${row.member} (${safeLine(row.state)})`;
+}).join(' + ');
+
+export const activeLineCell = (roster, options) => `[${rosterLabel(roster, options)}]`;
+
+refuseDirectRun(import.meta.url);

package/tools/review-roster.mjs

@@ -0,0 +1,128 @@
+import { REVIEW_CMD_ALIASES, receiptIdOfCmd, LENS_VERDICTS } from './carriers.mjs';
+import { KNOWN_BACKENDS } from './detect-backends.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+export { LENS_VERDICTS };
+
+export const BUNDLED_LENS_TEMPLATES = Object.freeze(['review-lens']);
+const MEMBER_TOKEN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const SUFFIX_TOKEN = /^[a-z0-9]+$/u;
+
+const reviewCommands = () => KNOWN_BACKENDS
+  .map((backend) => backend.roleCmds?.review)
+  .filter(Boolean);
+
+const failRoster = (message, code = null) => Object.assign(new Error(`review roster: ${message}`), { code });
+
+export const parseSlotToken = (member) => {
+  if (typeof member !== 'string' || member.length === 0) {
+    throw failRoster('every member must be a non-empty string');
+  }
+  const bridgeCommands = reviewCommands();
+  if (bridgeCommands.includes(member)) {
+    const alias = REVIEW_CMD_ALIASES[member];
+    if (!alias) throw failRoster(`bridge member "${member}" has no receipt alias`);
+    return {
+      member,
+      instrument: member,
+      kind: 'bridge',
+      stem: alias.receiptId,
+      model: null,
+      effort: null,
+      template: null,
+      derived: false,
+    };
+  }
+  const parts = member.split(':');
+  if (parts.length !== 1 && parts.length !== 3) {
+    if (bridgeCommands.includes(parts[0])) throw failRoster(`bridge member "${parts[0]}" takes no suffix`);
+    throw failRoster(`member "${member}" must be a bare stem or carry both model and effort`);
+  }
+  const [instrument, model = null, effort = null] = parts;
+  if (bridgeCommands.includes(instrument)) throw failRoster(`bridge member "${instrument}" takes no suffix`);
+  if (!MEMBER_TOKEN.test(instrument)) throw failRoster(`member instrument "${instrument}" is not a slug`);
+  if (model !== null && (!SUFFIX_TOKEN.test(model) || !SUFFIX_TOKEN.test(effort))) {
+    throw failRoster(`member "${member}" has an invalid model or effort token`);
+  }
+  if (model !== null && !BUNDLED_LENS_TEMPLATES.includes(instrument)) {
+    throw failRoster(`derived member "${member}" has no bundled lens template`);
+  }
+  return {
+    member,
+    instrument,
+    kind: 'lens',
+    stem: model === null ? instrument : `${instrument}-${model}-${effort}`,
+    model,
+    effort,
+    template: BUNDLED_LENS_TEMPLATES.includes(instrument) ? instrument : null,
+    derived: model !== null,
+  };
+};
+
+export const validateRoster = (value) => {
+  if (!Array.isArray(value)) throw failRoster('value must be an array');
+  if (value.length === 0) throw failRoster('array must not be empty');
+  const parsed = value.map(parseSlotToken);
+  const seen = new Set();
+  for (const member of parsed) {
+    if (seen.has(member.stem)) throw failRoster(`duplicate resolved stem "${member.stem}"`);
+    seen.add(member.stem);
+  }
+  return value;
+};
+
+export const expandShorthand = (value) => {
+  if (value === 'solo') return { lossless: true, members: [] };
+  if (value === 'council') return { lossless: true, members: reviewCommands() };
+  return { lossless: false, members: null };
+};
+
+export const bridgeMembersOf = (value) => validateRoster(value)
+  .filter((member) => parseSlotToken(member).kind === 'bridge');
+
+export const lensMembersOf = (value) => {
+  const values = Array.isArray(value)
+    ? [value]
+    : Object.values(value ?? {}).flatMap((activity) => (
+      Array.isArray(activity?.review) ? [activity.review] : []
+    ));
+  return values.flat().filter((member) => parseSlotToken(member).kind === 'lens');
+};
+
+export const obligationsOf = (value) => {
+  const backends = bridgeMembersOf(value).map(receiptIdOfCmd);
+  if (backends.length === 0) return { recipe: 'solo', backends, minShip: 0, perBackend: false };
+  return {
+    recipe: backends.length === 1 ? 'reviewed' : 'council',
+    backends,
+    minShip: 1,
+    perBackend: true,
+  };
+};
+
+const explicitMembers = (value) => {
+  if (Array.isArray(value)) return [...value];
+  const expanded = expandShorthand(value);
+  if (!expanded.lossless) throw failRoster('reviewed has no lossless roster expansion');
+  return [...expanded.members];
+};
+
+export const addReviewer = (value, member) => {
+  const next = explicitMembers(value);
+  const parsed = parseSlotToken(member);
+  if (next.some((entry) => parseSlotToken(entry).stem === parsed.stem)) return next;
+  next.push(member);
+  validateRoster(next);
+  return next;
+};
+
+export const removeReviewer = (value, member) => {
+  const next = explicitMembers(value);
+  const stem = parseSlotToken(member).stem;
+  const filtered = next.filter((entry) => parseSlotToken(entry).stem !== stem);
+  if (next.length > 0 && filtered.length === 0) throw failRoster('removing the last member requires the solo shorthand', 'last-member');
+  if (filtered.length > 0) validateRoster(filtered);
+  return filtered;
+};
+
+refuseDirectRun(import.meta.url);

package/tools/review-rounds-cli.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
+import { uncarriableArtifactByte } from './repo-lex.mjs';
+import { readReceipts, resolveReceiptsPath } from './core-evidence.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { ACTIVITIES, composeReadiness, requiredBackendsForConfiguredRecipe } from './recipes.mjs';
+import { groupRounds, renderRounds } from './review-rounds.mjs';
+
+const REVIEW_ACTIVITIES = new Set(Object.entries(ACTIVITIES).filter(([, def]) => Object.hasOwn(def.slots, 'review')).map(([name]) => name));
+
+const assertArtifactPathCarryable = (value) => {
+  const byte = uncarriableArtifactByte(value);
+  if (byte !== null) throw new Error(`artifact path contains ${byte} byte, which the receipt encoder cannot carry`);
+};
+
+const gitTopLevel = (cwd, run = spawnSync) => {
+  const result = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.replace(/\r?\n$/u, '') : null;
+};
+
+export const normalizeArtifactPath = (path, { cwd = process.cwd(), run = spawnSync, realpath = realpathSync, top = gitTopLevel(cwd, run) } = {}) => {
+  assertArtifactPathCarryable(path);
+  const absolute = realpath(resolve(cwd, path));
+  const root = top === null ? null : realpath(top);
+  const rel = root === null ? null : relative(root, absolute);
+  const contained = rel !== null && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  const normalized = contained ? rel.split(sep).join('/') : absolute.split(sep).join('/');
+  assertArtifactPathCarryable(normalized);
+  return normalized;
+};
+
+const parseArgs = (argv) => {
+  const values = { activity: 'plan-authoring', artifact: null };
+  for (const [index, arg] of argv.entries()) {
+    if (arg === '--artifact' || arg === '--activity') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+      if (arg === '--artifact') values.artifact = value;
+      else values.activity = value;
+      continue;
+    }
+    if (index > 0 && (argv[index - 1] === '--artifact' || argv[index - 1] === '--activity')) continue;
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (values.artifact === null) throw new Error('--artifact needs a <path>');
+  if (!REVIEW_ACTIVITIES.has(values.activity)) throw new Error(`--activity must be one of ${[...REVIEW_ACTIVITIES].join(', ')}, got ${values.activity}`);
+  return values;
+};
+
+// Every refusal exits 2: usage, an unreadable store, a malformed config, a detection failure.
+export const main = (argv, deps = {}) => {
+  try {
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const { artifact, activity } = parseArgs(argv);
+    const run = deps.run ?? spawnSync;
+    const top = gitTopLevel(cwd, run);
+    const artifactPath = normalizeArtifactPath(artifact, { cwd, run, top });
+    const root = top ?? cwd;
+    const { config } = loadConfig(root);
+    const detection = { failed: false };
+    const readiness = config?.[activity]?.review == null
+      ? composeReadiness(root, { onDetectError: () => { detection.failed = true; }, ...(deps.readinessDeps ?? {}) })
+      : [];
+    const obligation = requiredBackendsForConfiguredRecipe({ config, readiness, detectionFailed: detection.failed, activity });
+    if (obligation.unknowable) throw new Error('backend detection failed — the review obligation is unknowable');
+    const receiptsPath = resolveReceiptsPath(root, env);
+    if (receiptsPath === null) throw new Error('the review receipts store cannot be resolved (not a git work tree and AW_REVIEW_RECEIPTS is unset)');
+    const read = readReceipts(receiptsPath);
+    if (read.readError !== undefined) throw new Error(`the review receipts store is unreadable: ${read.readError}`);
+    const selected = read.receipts.filter((receipt) => receipt.artifactPath === artifactPath);
+    const pathless = read.receipts.filter((receipt) => ['plan', 'diff'].includes(receipt.artifact) && !Object.hasOwn(receipt, 'artifactPath')).length;
+    const grouped = groupRounds(selected, obligation);
+    return {
+      code: 0,
+      stdout: renderRounds({ ...grouped, obligation, artifactPath, pathless, malformed: read.malformed }),
+      stderr: '',
+    };
+  } catch (err) {
+    return { code: 2, stdout: '', stderr: `review-rounds: ${err.message}` };
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) process.stdout.write(`${result.stdout}\n`);
+  if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+  process.exitCode = result.code;
+}

package/tools/review-rounds.mjs

@@ -0,0 +1,115 @@
+import { isRenderableLine } from './repo-lex.mjs';
+import { isShipVerdict, isRecognizedVerdict } from './core-evidence.mjs';
+
+export const SIGNALS = Object.freeze({
+  NO_RECEIPTS: 'no receipts for <path>',
+  INCOMPLETE: 'incomplete round — <backend> missing: dispatch it',
+  CONVERGED: 'converged',
+  CROSSOVER: 'crossover — stop: diff-review',
+  CAP_REACHED: 'cap reached — classify each surviving finding: fixable-bug / inherent-layer-residual / escalate',
+  FOLD_AND_RE_REVIEW: 'round 1 — fold and re-review',
+});
+
+const isNonNegativeInteger = (value) => Number.isInteger(value) && value >= 0;
+const isPlainLine = isRenderableLine;
+
+const invalidFieldOf = (receipt) => {
+  if (typeof receipt?.artifactPath !== 'string') return 'artifactPath';
+  if (typeof receipt.fingerprint !== 'string' || !/^[0-9a-f]{64}$/u.test(receipt.fingerprint)) return 'fingerprint';
+  if (!isPlainLine(receipt.backend) || receipt.backend.length === 0) return 'backend';
+  if (receipt.probe !== false) return 'probe';
+  if (!isPlainLine(receipt.verdict)) return 'verdict';
+  if (!isNonNegativeInteger(receipt.durationS)) return 'durationS';
+  if (!isNonNegativeInteger(receipt.blocking)) return 'blocking';
+  return null;
+};
+
+export const groupRounds = (receipts, obligation) => {
+  const expected = new Set(obligation.backends);
+  const rounds = [];
+  const invalid = [];
+  const unexpected = [];
+  for (const receipt of receipts) {
+    const invalidField = invalidFieldOf(receipt);
+    if (invalidField !== null) {
+      invalid.push({ field: invalidField, receipt });
+      continue;
+    }
+    if (!expected.has(receipt.backend)) {
+      unexpected.push(receipt);
+      continue;
+    }
+    const previous = rounds.at(-1);
+    const round = previous?.fingerprint === receipt.fingerprint
+      ? previous
+      : { fingerprint: receipt.fingerprint, byBackend: {} };
+    if (round !== previous) rounds.push(round);
+    round.byBackend[receipt.backend] = receipt;
+  }
+  return { rounds, invalid, unexpected };
+};
+
+export const isComplete = (round, obligation) => {
+  const present = obligation.backends.filter((backend) => round.byBackend[backend] !== undefined);
+  return obligation.perBackend
+    ? present.length === obligation.backends.length
+    : present.length >= obligation.minShip;
+};
+
+const isConverged = (round, obligation) => obligation.backends
+  .map((backend) => round.byBackend[backend])
+  .filter(Boolean)
+  .every((receipt) => receipt.blocking === 0 && isShipVerdict(receipt.verdict));
+
+const hasCrossover = (rounds, obligation) => {
+  const [earlier, latest] = rounds.slice(-2);
+  return obligation.backends.some((shipBackend) => {
+    const shipEarlier = earlier.byBackend[shipBackend];
+    const shipLatest = latest.byBackend[shipBackend];
+    if (!isShipVerdict(shipEarlier?.verdict) || !isShipVerdict(shipLatest?.verdict)) return false;
+    return obligation.backends.some((negativeBackend) => {
+      if (negativeBackend === shipBackend) return false;
+      const negativeEarlier = earlier.byBackend[negativeBackend]?.verdict;
+      const negativeLatest = latest.byBackend[negativeBackend]?.verdict;
+      return isRecognizedVerdict(negativeEarlier) && !isShipVerdict(negativeEarlier)
+        && isRecognizedVerdict(negativeLatest) && !isShipVerdict(negativeLatest);
+    });
+  });
+};
+
+export const signalFor = (rounds, obligation, artifactPath) => {
+  if (rounds.length === 0) return SIGNALS.NO_RECEIPTS.replace('<path>', () => artifactPath);
+  const latest = rounds.at(-1);
+  if (!isComplete(latest, obligation)) {
+    const missing = obligation.backends.find((backend) => latest.byBackend[backend] === undefined);
+    return SIGNALS.INCOMPLETE.replace('<backend>', () => missing);
+  }
+  if (isConverged(latest, obligation)) return SIGNALS.CONVERGED;
+  const complete = rounds.filter((round) => isComplete(round, obligation));
+  if (complete.length >= 2 && hasCrossover(complete, obligation)) return SIGNALS.CROSSOVER;
+  if (complete.length >= 2) return SIGNALS.CAP_REACHED;
+  return SIGNALS.FOLD_AND_RE_REVIEW;
+};
+
+export const renderRounds = ({ rounds, invalid = [], unexpected = [], obligation, artifactPath, pathless = 0, malformed = 0 }) => {
+  const lines = [];
+  rounds.reduce((total, round, index) => {
+    const receipts = obligation.backends.map((backend) => round.byBackend[backend]).filter(Boolean);
+    const duration = receipts.reduce((sum, receipt) => sum + receipt.durationS, 0);
+    const cells = obligation.backends.map((backend) => {
+      const receipt = round.byBackend[backend];
+      return receipt === undefined
+        ? `${backend}: missing`
+        : `${backend}: ${receipt.verdict} (${receipt.blocking} blocking, ${receipt.durationS}s)`;
+    });
+    const next = total + duration;
+    lines.push(`round ${index + 1} · ${cells.join(' · ')} · receipted duration: ${duration}s · cumulative: ${next}s`);
+    return next;
+  }, 0);
+  for (const entry of invalid) lines.push(`invalid: ${entry.field}`);
+  for (const receipt of unexpected) lines.push(`unexpected: ${receipt.backend}`);
+  lines.push(`pathless plan/diff receipts: ${pathless}`);
+  lines.push(`malformed receipt lines: ${malformed}`);
+  lines.push(`signal: ${signalFor(rounds, obligation, artifactPath)}`);
+  return lines.join('\n');
+};

package/tools/review-state.mjs

@@ -9,6 +9,11 @@
 // `--check` turns the report into a gate exit code (declare it in docs/ai/gates.json).
 //
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
+// Before the review-recipe exits, configured plan-execution.execute=delegated with a plan and a
+// dirty, fingerprintable tree audits the delegation ledger. An absent ledger is inert; an
+// unavailable ledger, a HEAD error or a SUBSTITUTED held session refuses unless a codex-exec degrade at the
+// substituted return's tree, standing after every later fold, accepts it, or the fold of that thread's
+// retry lifts it (codex never grants it).
 //   exit 0  when the CONFIGURED plan-execution.review recipe is solo (or the computed default is —
 //           absent config with no reviewer backend ready); when no plan is in flight (docs/plans/
 //           holds no top-level .md that is not queue.md and not scratch by the naming convention:
@@ -105,6 +110,10 @@ import { selectReliedOnReceipt, evaluateVetoOverride, evaluateInternalAttestatio
 // graph; re-exported here so every historical consumer keeps its import site.
 import { PLANS_REL, isScratchPlanName, plansInFlight } from './plan-files.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import {
+  decideHeldSession, HELD_EXECUTE_WRAPPER, HELD_RECEIPT_BACKEND, judgeLedger,
+} from './held-session.mjs';
 
 export { PLANS_REL, isScratchPlanName, plansInFlight, shellQuoteArg };
 // The canonical review-domain primitives live in the core-evidence DAG bottom (ONE home for the
@@ -138,6 +147,7 @@ export {
 
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
+const CORE_EVIDENCE_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'));
 const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate silently
 // --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
 // a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
@@ -296,10 +306,35 @@ export const degradeRecordSet = ({ cwd, env = process.env, fingerprint }) => {
   const storePath = resolveEvidencePath(cwd, env);
   const read = storePath ? readEvidence(storePath) : { records: [], malformed: 0, malformedReasons: [] };
   const unavailable = (read.malformed ?? 0) > 0 || read.readError != null;
+  const records = unavailable ? [] : authoritativeOfKind(read.records, 'degrade');
   const set = unavailable || fingerprint == null
     ? new Set()
-    : new Set(authoritativeOfKind(read.records, 'degrade').filter((r) => r.fingerprint === fingerprint).map((r) => r.backend));
-  return { set, storePath, malformed: read.malformed ?? 0, readError: read.readError ?? null, unavailable };
+    : new Set(records.filter((r) => r.fingerprint === fingerprint).map((r) => r.backend));
+  return { set, records, storePath, malformed: read.malformed ?? 0, readError: read.readError ?? null, unavailable };
+};
+
+export const selectHeldSessionDegrades = (records) =>
+  records.filter((record) => record.kind === 'degrade' && record.backend === HELD_EXECUTE_WRAPPER);
+
+export const shouldReadHeldSession = ({ configuredExecute, plans, fingerprint, clean }) =>
+  configuredExecute === 'delegated' && plans.length > 0 && fingerprint !== null && clean === false;
+
+export const buildHeldSessionState = ({
+  cwd,
+  env,
+  configuredExecute,
+  plans,
+  fingerprint,
+  clean,
+  degrades,
+  resolveStore,
+  readStore,
+  audit,
+  readHead,
+}) => {
+  if (!shouldReadHeldSession({ configuredExecute, plans, fingerprint, clean })) return null;
+  const ledger = readDelegationLedger(cwd, env, { resolveStore, readStore, audit, readHead });
+  return judgeLedger(ledger, { backend: HELD_RECEIPT_BACKEND, degrades });
 };
 
 // ── the check + report core ─────────────────────────────────────────────────────────
@@ -340,6 +375,15 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
   const base = resolveBase(cwd);
   const degrade = degradeRecordSet({ cwd, env, fingerprint });
   const degradedExempt = requiredBackends.filter((b) => degrade.set.has(b));
+  const heldSession = buildHeldSessionState({
+    cwd,
+    env,
+    configuredExecute: config?.[ACTIVITY]?.execute,
+    plans,
+    fingerprint,
+    clean,
+    degrades: selectHeldSessionDegrades(degrade.records),
+  });
   // ── the Phase-2 flow arms' state (two-tier activation, P3) ──
   // Tier 1 is store-file PRESENCE: no file ⇒ every field below stays inert and the decision is
   // byte-identical to the pre-flow checker (the unarmed fast path also reads NO plan file).
@@ -437,6 +481,7 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     evidenceReadError: degrade.readError,
     evidenceUnavailable: degrade.unavailable,
     degradedExempt,
+    heldSession,
     maskedUntracked: countNeverCommittableUntracked(cwd, { lstat }),
     detectionWarning,
     flowPresent,
@@ -476,7 +521,27 @@ const backendFailurePart = (b, state) => {
   if (b.state === 'probe') return `${b.backend}: only probe receipts for the current tree (CODEX_PROBE=1 / AGY_PROBE=1 relaxes the quality guards) — a probe review never attests; re-run a real one`;
   if (b.state === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${state.receiptsPath}`;
   if (b.state === 'stale') return `${b.backend}: receipts exist but none matches the current tree (edited after review) — run a fresh review`;
-  return `${b.backend}: no receipt — run its review wrapper, or record an explicit degrade (node ${shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'))} degrade --backend ${b.backend} --reason "...")`;
+  return `${b.backend}: no receipt — run its review wrapper, or record an explicit degrade (node ${CORE_EVIDENCE_TOOL} degrade --backend ${b.backend} --reason "...")`;
+};
+
+const describesHeldRecovery = (state) => {
+  const substitution = state.heldSession.substitution;
+  if (substitution === null) return '';
+  const canRetry = substitution.folded === false;
+  if (state.evidenceUnavailable === true) {
+    const retry = canRetry ? '; or fold the retry of that thread' : '';
+    return ` — the evidence store is unavailable, so the degrade lane cannot be judged: repair it (inspect ${state.evidenceStorePath}) and re-check${retry}`;
+  }
+  const canDegrade = typeof substitution.postTreeDigest === 'string'
+    && state.fingerprint === substitution.postTreeDigest;
+  if (!canDegrade && !canRetry) {
+    return ' — no recovery lane remains: the tree moved after the substituted return and that thread is folded; re-dispatch the work under the held session';
+  }
+  const degrade = canDegrade
+    ? ` — mint the accepted-replacement record now, before the next edit: node ${CORE_EVIDENCE_TOOL} degrade --backend ${HELD_EXECUTE_WRAPPER} --reason "..."`
+    : '';
+  const retry = canRetry ? `${canDegrade ? '; or' : ' —'} fold the retry of that thread` : '';
+  return `${degrade}${retry}`;
 };
 
 // The normative --check decision (the header contract, in order). → { code, reason }.
@@ -493,6 +558,11 @@ export const decideCheck = (state) => {
     ? ` — evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}); the degrade escape is denied (fail-closed) — inspect ${state.evidenceStorePath}`
     : '';
   const earlyNotes = `${malformedNote}${evidenceNote}${state.receiptsReadError ? ` — receipts store unreadable (${state.receiptsReadError}); inspect ${state.receiptsPath}` : ''}`;
+  if (state.heldSession !== null && state.heldSession !== undefined) {
+    const held = decideHeldSession(state.heldSession);
+    const heldRecovery = describesHeldRecovery(state);
+    if (held.code !== 0) return { ...held, reason: `${held.reason}${heldRecovery}${earlyNotes}`, terminal: true, heldSession: true };
+  }
   // Detector failure with NO configured recipe: the computed default is unknowable → fail closed.
   // An EXPLICIT configured recipe needs no detector — its obligations are readiness-independent.
   if (state.obligations.unknowable) {
@@ -649,6 +719,7 @@ const formatHuman = (state, check) => {
   if (state.fingerprint == null) lines.push('  tree: not a git work tree');
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
+  if (state.heldSession != null) lines.push(`  ${decideHeldSession(state.heldSession).line}`);
   lines.push(`  receipts: ${state.receiptsPath ?? '(unresolvable — no git dir)'} (${state.receiptCount} line(s)${state.malformed ? `, ${state.malformed} malformed — inspect the file` : ''})`);
   if (state.receiptsReadError) lines.push(`  ⚠ receipts store unreadable (${state.receiptsReadError}) — inspect ${state.receiptsPath}`);
   if (state.evidenceUnavailable) lines.push(`  ⚠ evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}) — the degrade escape is denied (fail-closed)`);
@@ -700,7 +771,12 @@ attests; a malformed OR absent probe marker is rejected fail-closed — silence
 The ONLY escape for an unavailable backend under council is an explicit current-tree degrade
 record (node core-evidence.mjs degrade) — and never all backends.
 
---check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
+--check exits 0/1 per the normative contract in the tool header. FIRST, before any of the arms
+below, a configured plan-execution.execute = delegated with a plan in flight and a dirty,
+fingerprintable tree audits the delegation ledger: an absent ledger is inert; an unreadable,
+malformed, foreign or audit-refused ledger, a failed HEAD read, or a SUBSTITUTED held session
+exits 1 (a substitution is lifted only by a codex-exec degrade at the substituted return's own
+tree, or the fold of that thread's retry). THEN: 0 for solo / no plan in flight /
 a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
 not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an
@@ -728,11 +804,12 @@ export const main = (argv, ctx = {}) => {
   const cwd = ctx.cwd ?? process.cwd();
   const env = ctx.env ?? process.env;
   const detect = ctx.detect ?? detectBackends;
+  const build = ctx.buildState ?? buildState;
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
     const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
     if (unknown !== undefined) throw fail(2, `unknown argument: ${unknown}`);
-    const state = buildState({ cwd, env, detect, surveyVehicle: ctx.surveyVehicle, lstat: ctx.lstat, readFile: ctx.readFile });
+    const state = build({ cwd, env, detect, surveyVehicle: ctx.surveyVehicle, lstat: ctx.lstat, readFile: ctx.readFile });
     const check = decideCheck(state);
     // The mask advisory is NON-FAILING by contract: one notice line, never an exit-code arm.
     const advisory = maskAdvisoryLine(state);
@@ -779,6 +856,7 @@ export const mainAwait = async (argv, ctx = {}) => {
   const now = ctx.now ?? (() => Date.now());
   const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const pollMs = ctx.pollMs ?? AWAIT_POLL_MS;
+  const build = ctx.buildState ?? buildState;
   try {
     for (let i = 0; i < argv.length; i += 1) {
       const a = argv[i];
@@ -798,9 +876,10 @@ export const mainAwait = async (argv, ctx = {}) => {
     for (;;) {
       const elapsed = now() - start;
       if (elapsed >= timeoutMs) return { code: 1, stdout: '', stderr: `review-state --await: TIMEOUT after ${timeoutS}s — ${lastReason}` };
-      const check = decideCheck(buildState({ cwd, env, detect }));
+      const check = decideCheck(build({ cwd, env, detect }));
       lastReason = check.reason;
       if (check.code === 0) return { code: 0, stdout: `review-state --await: READY — ${check.reason}`, stderr: '' };
+      if (check.heldSession === true) return { code: 1, stdout: '', stderr: `review-state --await: HELD SESSION — ${check.reason}` };
       // Decision 4 (#50): an AUTHORITATIVE veto ends the wait loudly BEFORE the deadline — the
       // dispatched review answered with a landed negative; classifying that as a timeout was the
       // misclassification this amendment closes. Only a fresh review can move it, never waiting.