@sabaiway/agent-workflow-kit 10.5.0 → 11.0.0

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:
@@ -16,8 +21,8 @@
 //           the tree is clean (nothing to review — under a non-solo review obligation the PASS
 //           still NAMES every plan in flight and states that the gate arms as soon as the tree
 //           turns dirty, so a latent arm is discoverable before it blocks a pending commit); when
-//           the cwd is not a git work tree
-//           (the gate can never arm there, so nothing is announced); and when
+//           git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree
+//           location that passes; the five other states refuse by name); and when
 //           the obligations are SATISFIED: under `reviewed`, >=1 backend's latest normal receipt
 //           attests SHIP-CLASS (ship / ship with nits) for the current tree; under `council`,
 //           EVERY review-capable backend attests ship-class OR carries an explicit current-tree
@@ -104,7 +109,12 @@ import { selectReliedOnReceipt, evaluateVetoOverride, evaluateInternalAttestatio
 // in leaf modules so the procedures read surface reaches them without this module's write-API
 // 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 { escapeForDisplay, shellQuoteArg } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, stripGitLocationEnv, withGitPath } from './git-env.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,7 +148,7 @@ export {
 
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate silently
+const CORE_EVIDENCE_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'));
 // --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
 // injectable clock) so hermetic tests never spend wall-clock.
@@ -147,18 +157,18 @@ export const AWAIT_POLL_MS = 5000;
 
 // ── git plumbing (read-only queries; injectable for tests) ─────────────────────────
 
-const gitRaw = (args, cwd) =>
-  spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+const gitRaw = (args, cwd, env) =>
+  spawnSync('git', args, { cwd, env: withGitPath(env ?? process.env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
 // stdout Buffer of a git query, or null when git fails (not a repo / git absent).
-const gitBuf = (args, cwd) => {
-  const r = gitRaw(args, cwd);
+const gitBuf = (args, cwd, env) => {
+  const r = gitRaw(args, cwd, env);
   if (r.error || r.status !== 0) return null;
   return r.stdout;
 };
 
-const gitLine = (args, cwd) => {
-  const buf = gitBuf(args, cwd);
+const gitLine = (args, cwd, env) => {
+  const buf = gitBuf(args, cwd, env);
   return buf == null ? null : buf.toString('utf8').replace(/\r?\n$/, '');
 };
 
@@ -171,10 +181,10 @@ const gitLine = (args, cwd) => {
 // ignores them by construction; this count only feeds ONE non-failing advisory line naming the
 // cosmetic sandbox-masks apply — an applied managed block hides the paths from --exclude-standard,
 // so the advisory disappears exactly when the status noise does (no standing detector).
-export const countNeverCommittableUntracked = (cwd, { lstat = lstatSync } = {}) => {
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+export const countNeverCommittableUntracked = (cwd, { lstat = lstatSync, env } = {}) => {
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd, env);
   if (top == null) return 0;
-  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
+  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top, env);
   if (untrackedZ == null) return 0;
   return untrackedZ
     .toString('utf8')
@@ -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 ─────────────────────────────────────────────────────────
@@ -310,7 +345,10 @@ export const degradeRecordSet = ({ cwd, env = process.env, fingerprint }) => {
 // must read the same config/plans or a dirty unreceipted tree could false-PASS as "no plan in
 // flight". Outside a git tree the cwd is the only anchor (and --check exits 0).
 export const buildState = ({ cwd, env = process.env, detect = detectBackends, surveyVehicle, lstat = lstatSync, readFile = readFileSync } = {}) => {
-  const root = gitLine(['rev-parse', '--show-toplevel'], cwd) ?? cwd;
+  // WHICH repository, first; the config/plan anchor is the stripped discovery's top (from a subdirectory the bare cwd would miss docs/plans — decideCheck refuses on an unanchored root).
+  const location = resolveGitLocation(cwd, { env });
+  const anchoredTop = location.top ?? gitLine(['rev-parse', '--show-toplevel'], cwd, stripGitLocationEnv(env));
+  const root = anchoredTop ?? cwd;
   const { config, source: configSource } = loadConfig(root);
   // A bridge-detector throw reaches the hook, never a catch that would also lose the surveyed
   // executor vehicle: bridge readiness goes unknown (fail closed below), the carrier stays known.
@@ -319,16 +357,15 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     detectionWarning = `backend detection failed (${(err && err.message) || err}) — bridge readiness unknown.`;
   };
   const detection = composeReadiness(root, { detect, surveyVehicle, onDetectError });
-  // The resolver stays for DISPLAY/diagnostics only; the OBLIGATIONS come from the configured
-  // recipe (never the readiness-degraded effective one — no silent solo).
+  // The resolver stays for DISPLAY only; the OBLIGATIONS come from the configured recipe (never the readiness-degraded effective one — no silent solo).
   const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
   const obligations = requiredBackendsForConfiguredRecipe({ config: config ?? {}, readiness: detection, detectionFailed: detectionWarning != null });
   const requiredBackends = obligations.backends;
   const plans = plansInFlight(root);
   // The injected lstat threads through EVERY stat-dependent computation (fingerprint, clean, the
   // mask count) — a partial injection would let a test observe an inconsistent state.
-  const fingerprint = computeTreeFingerprint(cwd, { lstat });
-  const clean = fingerprint == null ? null : isTreeClean(cwd, { lstat });
+  const fingerprint = location.state === 'work-tree' ? computeTreeFingerprint(cwd, { lstat, env }) : null;
+  const clean = fingerprint == null ? null : isTreeClean(cwd, { lstat, env });
   const receiptsPath = resolveReceiptsPath(cwd, env);
   const receiptsRead = receiptsPath ? readReceipts(receiptsPath) : { receipts: [], malformed: 0 };
   const { receipts, malformed } = receiptsRead;
@@ -340,6 +377,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).
@@ -425,6 +471,8 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     backends: armedBackends,
     plans,
     root,
+    rootAnchored: anchoredTop !== null,
+    location,
     fingerprint,
     clean,
     receiptsPath,
@@ -437,7 +485,8 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     evidenceReadError: degrade.readError,
     evidenceUnavailable: degrade.unavailable,
     degradedExempt,
-    maskedUntracked: countNeverCommittableUntracked(cwd, { lstat }),
+    heldSession,
+    maskedUntracked: countNeverCommittableUntracked(cwd, { lstat, env }),
     detectionWarning,
     flowPresent,
     flowArmed,
@@ -474,9 +523,29 @@ const backendFailurePart = (b, state) => {
   if (b.state === 'unrecognized-verdict') return `${b.backend}: the latest normal receipt carries an unrecognized verdict (${JSON.stringify(b.verdict)}) — an unknown verdict never attests (fail-closed); re-run the review`;
   if (b.state === 'ungrounded') return `${b.backend}: the latest normal receipt is ungrounded — re-run grounded (--facts)`;
   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 === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${escapeForDisplay(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 ${escapeForDisplay(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 }.
@@ -488,11 +557,18 @@ export const decideCheck = (state) => {
   // Store diagnostics ride EVERY check line, early exits (and the unknowable arm) included — a
   // malformed receipt line, an unavailable evidence store, or an unreadable receipts store is
   // never hidden behind any exit.
-  const malformedNote = state.malformed > 0 ? ` — ${state.malformed} malformed receipt line(s) ignored; inspect ${state.receiptsPath}` : '';
+  const malformedNote = state.malformed > 0 ? ` — ${state.malformed} malformed receipt line(s) ignored; inspect ${escapeForDisplay(state.receiptsPath)}` : '';
   const evidenceNote = state.evidenceUnavailable
-    ? ` — evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}); the degrade escape is denied (fail-closed) — inspect ${state.evidenceStorePath}`
+    ? ` — evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}); the degrade escape is denied (fail-closed) — inspect ${escapeForDisplay(state.evidenceStorePath)}`
     : '';
-  const earlyNotes = `${malformedNote}${evidenceNote}${state.receiptsReadError ? ` — receipts store unreadable (${state.receiptsReadError}); inspect ${state.receiptsPath}` : ''}`;
+  const earlyNotes = `${malformedNote}${evidenceNote}${state.receiptsReadError ? ` — receipts store unreadable (${state.receiptsReadError}); inspect ${escapeForDisplay(state.receiptsPath)}` : ''}`;
+  // The git LOCATION (hand-built states carry none; the fingerprint decides there) rules below the solo arm: not-a-repository passes, the four other non-work-tree states refuse by name.
+  const location = state.location ?? { state: state.fingerprint == null ? 'not-a-repository' : 'work-tree', cause: 'no location was resolved for a hand-built state' };
+  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) {
@@ -504,11 +580,14 @@ export const decideCheck = (state) => {
       : `no reviewer backend is ready — the computed ${ACTIVITY}.${SLOT} default is solo`;
     return { code: 0, reason: `${why} — no receipt required${earlyNotes}` };
   }
+  // An UNANCHORED root (git dead everywhere): the bare-cwd plan inventory cannot say "no plan".
+  if (location.state !== 'work-tree' && location.state !== 'not-a-repository' && state.rootAnchored === false) return { code: 1, reason: `the git location is ${location.state} — ${escapeForDisplay(location.cause)} — and the project root cannot be anchored, so the plan arm cannot decide (fail closed)${earlyNotes}` };
   if (state.plans.length === 0) return { code: 0, reason: `no plan in flight (docs/plans/ holds no active plan) — no receipt required${earlyNotes}` };
-  if (state.fingerprint == null) return { code: 0, reason: `not a git work tree — nothing to fingerprint${earlyNotes}` };
-  // A clean tree PASSES, but never silently: the no-plan arm above already returned, so reaching
-  // here means >=1 plan IS in flight and this gate arms the moment the tree turns dirty. Naming
-  // each file forward-looking is what makes the arm discoverable BEFORE it blocks a pending commit.
+  if (location.state !== 'work-tree' && location.state !== 'not-a-repository') return { code: 1, reason: `the git location is ${location.state} — ${escapeForDisplay(location.cause)} — refusing to judge receipts for a tree git cannot name (fail closed)${earlyNotes}` };
+  if (location.state === 'not-a-repository') return { code: 0, reason: `not a git repository (git's own answer: ${escapeForDisplay(location.cause)}) — nothing to fingerprint${earlyNotes}` };
+  if (state.fingerprint == null || state.clean === null) return { code: 1, reason: `the tree ${state.fingerprint == null ? 'fingerprint' : 'clean check'} is undecidable in a work tree (a git query failed or was killed) — refusing to judge receipts (fail closed)${earlyNotes}` };
+  // A clean tree PASSES, but never silently: >=1 plan IS in flight here, and this gate arms the
+  // moment the tree turns dirty — naming each file makes the arm discoverable BEFORE it blocks.
   if (state.clean === true) {
     // Each name is byte-preserving and quoted because this reason is one gate-report line.
     const named = state.plans.map((p) => quoteReportName(p)).join(', ');
@@ -525,7 +604,7 @@ export const decideCheck = (state) => {
   // whatever the recipe consults, so a recipe flip to solo can never bury one.
   if (state.obligations.recipe === 'solo') {
     if (state.receiptsReadError != null) {
-      return { code: 1, reason: `the receipts store is unreadable (${state.receiptsReadError}) — "no standing veto" cannot be established, so the internal-only floor fails closed; inspect ${state.receiptsPath}${earlyNotes}` };
+      return { code: 1, reason: `the receipts store is unreadable (${state.receiptsReadError}) — "no standing veto" cannot be established, so the internal-only floor fails closed; inspect ${escapeForDisplay(state.receiptsPath)}${earlyNotes}` };
     }
     const standing = state.soloVetoRows.filter((b) => (b.state === 'current' && !b.shipClass && !b.overrideLabel) || b.state === 'unrecognized-verdict');
     if (standing.length > 0) {
@@ -571,7 +650,7 @@ export const decideCheck = (state) => {
       .filter((b) => !(printed.has(b.backend) && b.state === 'rejected'))
       .reduce((n, b) => n + (b.markerRejected ?? 0) + (b.unmarkedRejected ?? 0), 0);
     const markerNote = total > 0
-      ? ` — ${total} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${state.receiptsPath}`
+      ? ` — ${total} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${escapeForDisplay(state.receiptsPath)}`
       : '';
     return `${markerNote}${earlyNotes}`;
   };
@@ -646,11 +725,12 @@ const formatHuman = (state, check) => {
   ];
   if (state.detectionWarning) lines.push(`  ⚠ ${state.detectionWarning}`);
   lines.push(`  plan in flight: ${state.plans.length ? state.plans.map((name) => quoteReportName(name)).join(', ') : '(none)'}`);
-  if (state.fingerprint == null) lines.push('  tree: not a git work tree');
+  if (state.fingerprint == null) lines.push(`  tree: ${state.location != null && state.location.state !== 'work-tree' ? `git location ${state.location.state} — ${escapeForDisplay(state.location.cause)}` : 'the fingerprint is undecidable (a git query failed or was killed)'}`);
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
-  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.heldSession != null) lines.push(`  ${decideHeldSession(state.heldSession).line}`);
+  lines.push(`  receipts: ${state.receiptsPath == null ? '(unresolvable — no git dir)' : escapeForDisplay(state.receiptsPath)} (${state.receiptCount} line(s)${state.malformed ? `, ${state.malformed} malformed — inspect the file` : ''})`);
+  if (state.receiptsReadError) lines.push(`  ⚠ receipts store unreadable (${state.receiptsReadError}) — inspect ${escapeForDisplay(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)`);
   const exempt = new Set(state.degradedExempt);
   for (const b of state.backends) {
@@ -700,9 +780,14 @@ 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;
+a cwd where git ITSELF answers not-a-repository (the only passing non-work-tree state; the four others exit 1 by name) / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an
 unrecognized verdict, a missing/stale/ungrounded/probe-only backend without a degrade record,
 an all-degraded tree, or a down detector with no configured recipe.
@@ -728,11 +813,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 +865,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 +885,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.

package/tools/robustness-brief.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { readShippedRobustnessLiterals, parseRobustTag } from './robustness-literals.mjs';
+import { checkPlanStructure, formatFindings, isSweep } from './plan-shape.mjs';
+import { expandSweepPaths } from './plan-shape-facts.mjs';
+import { readFileBytesNoFollowCapped } from './fs-read-nofollow.mjs';
+import { escapeForDisplay, lexicalRepoRelative } from './repo-lex.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const PLAN_READ_CAP = 1_048_576;
+const ROW_ID = /^[A-Za-z0-9._-]+$/u;
+const SEARCHABLE_KINDS = new Set(['env', 'flag', 'ref', 'syscall', 'errno', 'argv']);
+const SHIPPED_LIST_PATH = 'agent-workflow-kit/references/robustness-literals.json';
+const USAGE = 'Usage: node robustness-brief.mjs --plan <plan> [--row <id>] [--coverage]';
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+const isInside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const decodePlan = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+
+const parseArgs = (argv, index = 0, state = { plan: null, row: null, coverage: false }) => {
+  if (index === argv.length) {
+    if (state.plan === null) throw usage('absent --plan');
+    if (state.row !== null && state.coverage) throw usage('--row cannot be combined with --coverage');
+    return state;
+  }
+  const flag = argv[index];
+  if (flag === '--coverage') {
+    if (state.coverage) throw usage('duplicate --coverage');
+    return parseArgs(argv, index + 1, { ...state, coverage: true });
+  }
+  const key = flag === '--plan' ? 'plan' : flag === '--row' ? 'row' : null;
+  const value = argv[index + 1];
+  if (key === null) throw usage(`unknown argument ${flag}`);
+  if (state[key] !== null) throw usage(`duplicate ${flag}`);
+  if (value === undefined || value.startsWith('--') || value.length === 0) throw usage(`absent operand for ${flag}`);
+  if (key === 'row' && !ROW_ID.test(value)) throw usage(`invalid --row ${value}`);
+  return parseArgs(argv, index + 2, { ...state, [key]: value });
+};
+
+const renderClass = (entry) => [
+  `- **${entry.id}** — ${entry.prove}`,
+  ...entry.members.map((member) => `  - \`${member.literal}\` — ${member.note} (${member.source})`),
+];
+
+const isIdentifierByte = (byte) => (byte >= 0x30 && byte <= 0x39) ||
+  (byte >= 0x41 && byte <= 0x5a) || byte === 0x5f || (byte >= 0x61 && byte <= 0x7a);
+const hasBoundedLiteral = (bytes, literal) => {
+  const token = Buffer.from(literal, 'utf8');
+  const cursor = { from: 0 };
+  while (cursor.from <= bytes.length - token.length) {
+    const hit = bytes.indexOf(token, cursor.from);
+    if (hit === -1) return false;
+    const leftBounded = hit === 0 || !isIdentifierByte(bytes[hit - 1]);
+    const rightBounded = literal.endsWith('_') || hit + token.length === bytes.length || !isIdentifierByte(bytes[hit + token.length]);
+    if (leftBounded && rightBounded) return true;
+    cursor.from = hit + 1;
+  }
+  return false;
+};
+export const isCoverageDocument = (path) => /\.(?:md|txt)$/u.test(path) || path === SHIPPED_LIST_PATH;
+const describeReadOutcome = (read) => read.outcome === 'foreign'
+  ? `non-regular ${read.className ?? 'file'}`
+  : read.outcome === 'over-cap' ? `over-cap${read.cap ? ` (cap ${read.cap})` : ''}`
+    : read.outcome === 'error' ? `error${read.code ? ` (${read.code})` : ''}` : String(read.outcome ?? 'unknown');
+const readCoverageFile = (readRowFile, path) => {
+  try {
+    const read = readRowFile(path);
+    if (read == null) return { outcome: 'error', code: 'empty read outcome' };
+    if (read.outcome === 'ok' && !Buffer.isBuffer(read.bytes)) return { outcome: 'error', code: 'ok outcome carried no Buffer' };
+    return read;
+  } catch (error) {
+    return { outcome: 'error', code: error?.code ?? error?.message ?? 'read threw' };
+  }
+};
+export const computeRowCoverage = (planText, list, { expandRowPath, readRowFile }) => {
+  const shape = checkPlanStructure(planText, {});
+  const classes = new Set(list.classes.map(({ id }) => id));
+  const entries = shape.parsed.rows.filter((entry) => entry.valid && !isCoverageDocument(entry.path));
+  return entries.reduce((answer, entry) => {
+    if (answer.refusal !== null) return answer;
+    const robust = parseRobustTag(entry.responsibility);
+    if (robust.refusal) return { ...answer, refusal: { id: entry.id, reason: robust.refusal } };
+    const unknown = robust.classes.find((classId) => !classes.has(classId));
+    if (unknown) return { ...answer, refusal: { id: entry.id, reason: `unknown class ${unknown}` } };
+    const tagged = robust.classes;
+    const emptyRow = { id: entry.id, path: entry.path, tagged, present: [], uncovered: [], absent: false, deleted: false };
+    if (entry.verb === 'delete') {
+      return { ...answer, rows: [...answer.rows, { ...emptyRow, deleted: true }] };
+    }
+    const paths = isSweep(entry.path) ? expandRowPath(entry.path) : [entry.path];
+    const reads = paths.map((path) => ({ path, read: readCoverageFile(readRowFile, path) }));
+    const refused = reads.find(({ read }) => !['ok', 'absent'].includes(read.outcome));
+    if (refused) {
+      return { ...answer, refusal: { id: entry.id, path: refused.path, outcome: describeReadOutcome(refused.read) } };
+    }
+    if (paths.length === 0 || reads.some(({ read }) => read.outcome === 'absent')) {
+      return { ...answer, rows: [...answer.rows, { ...emptyRow, absent: true }] };
+    }
+    const matches = list.classes.flatMap((classEntry) => {
+      const member = classEntry.members.find((candidate) => SEARCHABLE_KINDS.has(candidate.kind) &&
+        reads.some(({ read }) => hasBoundedLiteral(read.bytes, candidate.literal)));
+      return member ? [{ id: entry.id, classId: classEntry.id, literal: member.literal }] : [];
+    });
+    const present = matches.map(({ classId }) => classId);
+    const uncovered = present.filter((classId) => !tagged.includes(classId));
+    return {
+      rows: [...answer.rows, { ...emptyRow, present, uncovered }],
+      evidence: [...answer.evidence, ...matches.filter(({ classId }) => uncovered.includes(classId))],
+      refusal: null,
+    };
+  }, { rows: [], evidence: [], refusal: null });
+};
+
+const renderCell = (value) => escapeForDisplay(value).replaceAll('|', '\\|');
+export const renderCoverage = (rows, displayPath) => [
+  `## Robustness coverage — ${escapeForDisplay(displayPath)}`,
+  '| row | path | tagged | present | uncovered |',
+  '| --- | --- | --- | --- | --- |',
+  ...rows.map((row) => row.deleted
+    ? `| ${row.id} | ${renderCell(row.path)} | delete | — | — |`
+    : row.absent ? `| ${row.id} | ${renderCell(row.path)} | absent | — | — |`
+      : `| ${row.id} | ${renderCell(row.path)} | ${row.tagged.join(',') || '—'} | ${row.present.join(',') || '—'} | ${row.uncovered.join(',') || '—'} |`),
+];
+
+export const renderBrief = (planText, list, { row, displayPath }) => {
+  const shape = checkPlanStructure(planText, {});
+  if (shape.findings.length > 0) return { code: 1, lines: formatFindings(shape, escapeForDisplay(displayPath)).split('\n').map(escapeForDisplay) };
+  const classes = new Map(list.classes.map((entry) => [entry.id, entry]));
+  const rows = shape.parsed.rows.filter((entry) => entry.valid).map((entry) => ({
+    ...entry,
+    robust: parseRobustTag(entry.responsibility),
+  }));
+  const refused = rows.find((entry) => entry.robust.refusal || entry.robust.classes.some((classId) => !classes.has(classId)));
+  if (refused) {
+    const reason = refused.robust.refusal ?? `unknown class ${refused.robust.classes.find((classId) => !classes.has(classId))}`;
+    return { code: 1, lines: [`robustness-brief: ${refused.id}: robust-class — ${reason}`] };
+  }
+  const selected = row === null ? rows.filter((entry) => entry.robust.classes.length > 0) : rows.filter((entry) => entry.id === row);
+  if (row !== null && selected.length === 0) return { code: 1, lines: [`robustness-brief: ${row}: row is absent`] };
+  if (row !== null && selected[0].robust.classes.length === 0) return { code: 1, lines: [`robustness-brief: ${row}: row is untagged`] };
+  if (selected.length === 0) return { code: 0, lines: [`Robustness literals: ${escapeForDisplay(displayPath)} has no robust tags.`] };
+  return {
+    code: 0,
+    lines: [
+      `## Robustness literals — list version ${list.version} · ${escapeForDisplay(displayPath)}`,
+      ...selected.flatMap((entry) => [
+        '',
+        `### ${entry.id} — ${escapeForDisplay(entry.path)}`,
+        ...entry.robust.classes.flatMap((classId) => renderClass(classes.get(classId))),
+      ]),
+    ],
+  };
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  try {
+    const parsed = parseArgs(argv);
+    const cwd = deps.cwd ?? process.cwd();
+    const realpath = deps.realpath ?? realpathSync;
+    const cwdReal = realpath(cwd);
+    if (!isAbsolute(parsed.plan) && !lexicalRepoRelative(parsed.plan).ok) throw usage(`uncontained --plan ${parsed.plan}`);
+    const planPath = resolve(cwd, parsed.plan);
+    let planReal;
+    try {
+      planReal = realpath(planPath);
+    } catch (error) {
+      if (error?.code === 'ENOENT') throw usage(`absent --plan ${parsed.plan}`);
+      throw usage(`unreadable --plan ${parsed.plan} (${error?.code ?? error.message})`);
+    }
+    if (!isInside(cwdReal, planReal)) throw usage(`uncontained --plan ${parsed.plan}`);
+    const read = (deps.readPlan ?? readFileBytesNoFollowCapped)(planPath, PLAN_READ_CAP);
+    if (read.outcome !== 'ok') {
+      const outcome = read.outcome === 'foreign' ? `non-regular ${read.className ?? 'file'}` : read.outcome;
+      throw usage(`${outcome} --plan ${parsed.plan}${read.cap ? ` (cap ${read.cap})` : ''}`);
+    }
+    let planText;
+    try {
+      planText = decodePlan(read.bytes);
+    } catch {
+      throw usage(`malformed-utf8 --plan ${parsed.plan}`);
+    }
+    const list = (deps.readList ?? readShippedRobustnessLiterals)();
+    const brief = renderBrief(planText, list, { row: parsed.row, displayPath: parsed.plan });
+    if (!parsed.coverage || checkPlanStructure(planText, {}).findings.length > 0) return brief;
+    const sweepPaths = checkPlanStructure(planText, {}).parsed.rows
+      .filter((entry) => entry.valid && isSweep(entry.path) && !isCoverageDocument(entry.path))
+      .map((entry) => entry.path);
+    const expansions = deps.expandRowPath === undefined && sweepPaths.length > 0 ? expandSweepPaths(cwd, sweepPaths) : null;
+    const coverage = computeRowCoverage(planText, list, {
+      expandRowPath: deps.expandRowPath ?? ((path) => expansions[path] ?? []),
+      readRowFile: deps.readRowFile ?? ((path) => readFileBytesNoFollowCapped(resolve(cwd, path), PLAN_READ_CAP)),
+    });
+    if (coverage.refusal) {
+      const { id, path, outcome, reason } = coverage.refusal;
+      throw usage(reason === undefined ? `${id}: ${escapeForDisplay(path)} — ${outcome}` : `${id}: robust-class — ${reason}`);
+    }
+    const lines = [...renderCoverage(coverage.rows, parsed.plan), ...coverage.evidence.map(({ id, classId, literal }) => `${id}:${classId}:${literal}`)];
+    return { code: coverage.evidence.length > 0 ? 1 : 0, lines };
+  } catch (error) {
+    return { code: 2, lines: [`robustness-brief: usage — ${escapeForDisplay(error.message)}`, USAGE] };
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main();
+  (result.code === 2 ? console.error : console.log)(result.lines.join('\n'));
+  process.exitCode = result.code;
+}