@sabaiway/agent-workflow-kit 10.5.0 → 11.0.0

package/tools/fs-read-nofollow.mjs

@@ -5,7 +5,7 @@
 // no-follow read without a cycle. flow-store-read.mjs re-exports everything here, so every
 // existing consumer keeps its import site. Dependency-free, Node >= 22.
 
-import { readFileSync, lstatSync, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
+import { readFileSync, readSync, lstatSync, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
 
 // Local no-follow lstat (null ONLY on a true ENOENT).
 export const lstatNoFollowRead = (path, lstat = lstatSync) => {
@@ -24,6 +24,14 @@ export const describeNonRegular = (st) =>
 // ignoreBOM: a BOM must surface as malformed line 1, not vanish and get rewritten without it.
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 const hasOpenFlag = (v) => typeof v === 'number' && v !== 0;
+const errCode = (err) => (err && err.code) || (err && err.message) || null;
+// The open failures with a NAME of their own (shared by both readers); null for every other.
+const openFailure = (err) => {
+  if (err && err.code === 'ENOENT') return { outcome: 'absent' };
+  if (err && err.code === 'ELOOP') return { outcome: 'foreign', className: 'symlink', isDirectory: false };
+  if (err && err.code === 'EISDIR') return { outcome: 'foreign', className: 'directory', isDirectory: true };
+  return null;
+};
 
 // The ONE race-free read for store/lock bytes: open O_NOFOLLOW|O_NONBLOCK, fstat the DESCRIPTOR,
 // read through it, decode fatally — a pathname swapped after the open cannot change what the fd
@@ -89,9 +97,8 @@ const readNoFollowCore = (path, io, closeBox) => {
     }
     return { outcome: 'ok', content, dev: st.dev, ino: st.ino };
   } catch (err) {
-    if (err && err.code === 'ENOENT') return { outcome: 'absent' };
-    if (err && err.code === 'ELOOP') return { outcome: 'foreign', className: 'symlink', isDirectory: false };
-    if (err && err.code === 'EISDIR') return { outcome: 'foreign', className: 'directory', isDirectory: true };
+    const known = openFailure(err);
+    if (known !== null) return known;
     try {
       const st = lstatNoFollowRead(path, lstat);
       if (st && !st.isFile()) return { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
@@ -108,6 +115,51 @@ const readNoFollowCore = (path, io, closeBox) => {
   }
 };
 
+// readFileBytesNoFollowCapped(path, cap, io?) → ok { bytes } | over-cap { cap } | absent | foreign |
+// error — the control-byte gate's read: open O_NOFOLLOW|O_NONBLOCK, fstat the DESCRIPTOR for its
+// kind, read on it in bounded chunks until EOF or cap+1 bytes; the fstat SIZE is never consulted (a
+// file growing after the fstat still refuses); no decode (a lone 0xE9 is ok bytes); no lstat fallback.
+// ONE skeleton: no open without both flags; fstat the DESCRIPTOR; the body runs on a regular file only.
+const READ_CHUNK = 64 * 1024;
+const withRegularDescriptor = (path, io, body) => {
+  const consts = io.constants ?? fsConstants;
+  const open = io.open ?? openSync;
+  const fstat = io.fstat ?? fstatSync;
+  const close = io.close ?? closeSync;
+  if (!hasOpenFlag(consts.O_NONBLOCK) || !hasOpenFlag(consts.O_NOFOLLOW)) {
+    return { outcome: 'error', code: 'this platform exposes no usable O_NOFOLLOW|O_NONBLOCK open flags — refusing to open (fail closed)' };
+  }
+  let fd = null;
+  let result;
+  try {
+    fd = open(path, (consts.O_RDONLY ?? 0) | consts.O_NOFOLLOW | consts.O_NONBLOCK);
+    const st = fstat(fd);
+    result = st.isFile() ? body(fd) : { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
+  } catch (err) {
+    result = openFailure(err) ?? { outcome: 'error', code: errCode(err) ?? 'read failed' };
+  } finally {
+    if (fd !== null) {
+      try { close(fd); } catch (err) { result = { outcome: 'error', code: `descriptor close failed (${errCode(err) ?? 'close failed'}) — fail closed` }; }
+    }
+  }
+  return result;
+};
+// probeRegularFileNoFollow(path, io?) → ok | absent | foreign | error: the kind check alone, no read.
+export const probeRegularFileNoFollow = (path, io = {}) => withRegularDescriptor(path, io, () => ({ outcome: 'ok' }));
+export const readFileBytesNoFollowCapped = (path, cap, io = {}) => withRegularDescriptor(path, io, (fd) => {
+  const read = io.read ?? readSync;
+  const chunks = [];
+  let total = 0;
+  while (total <= cap) {
+    const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK, cap + 1 - total));
+    const n = read(fd, chunk, 0, chunk.length, null);
+    if (n === 0) break;
+    chunks.push(chunk.subarray(0, n));
+    total += n;
+  }
+  return total > cap ? { outcome: 'over-cap', cap } : { outcome: 'ok', bytes: Buffer.concat(chunks, total) };
+});
+
 // readFileBytesNoFollow(path, io?) → { outcome: 'ok', bytes } | absent | foreign | error — the
 // BYTES twin of the reader above for consumers whose domain is byte offsets (the Phase-4
 // receipt-deadline watermark, the finding-manifest digest domain): keepFd internally so the raw

package/tools/git-env.mjs

@@ -0,0 +1,120 @@
+// git-env.mjs — the kit's git-location leaf: WHICH repository a git spawn will talk to, judged by
+// AGREEMENT, never by a variable ban (measured 2026-08-31, git 2.43: an ambient GIT_DIR made three
+// consumers judge ANOTHER repository in silence; a killed git read as "not a git work tree", a pass).
+// The six-state table, the GIT_* strip, the hermetic env, the ls-files parser. A pure LEAF.
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+export const GIT_LOCATION_STATES = Object.freeze(['work-tree', 'not-a-repository', 'error', 'redirected', 'no-work-tree', 'env-only']);
+const LOCATION_VARIABLES = 'GIT_DIR / GIT_WORK_TREE / GIT_COMMON_DIR';
+
+// ASCII-case-insensitive prefix (a case-insensitive host honours `git_dir` as GIT_DIR) — an ASCII
+// class, never toUpperCase(): Unicode case folding would also strip a foreign `g<dotless-i>t_dir`.
+export const stripGitLocationEnv = (env) => Object.fromEntries(Object.entries(env).filter(([key]) => !/^[Gg][Ii][Tt]_/.test(key)));
+
+// The test fixtures' env, never a consumer's: the strip plus every host-reaching knob pinned.
+export const hermeticGitEnv = (env, home) => ({
+  ...stripGitLocationEnv(env),
+  HOME: home, XDG_CONFIG_HOME: home, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1', GIT_ATTR_NOSYSTEM: '1', LC_ALL: 'C',
+});
+
+// An env naming no PATH (a partial override, a test's `{}`) borrows the process PATH; one naming a PATH is honoured as is.
+export const withGitPath = (env) => (env.PATH === undefined && process.env.PATH !== undefined ? { ...env, PATH: process.env.PATH } : env);
+
+// `ls-files -s -z` records: mode, object, stage, TAB, then the path BYTES up to the NUL — undecoded.
+export const parseIndexEntries = (buf) => {
+  const entries = [];
+  for (let start = 0; start < buf.length;) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    const record = buf.subarray(start, end);
+    const tab = record.indexOf(0x09);
+    if (tab !== -1) {
+      const [mode, sha, stage] = record.subarray(0, tab).toString('utf8').split(' ');
+      entries.push({ mode, sha, stage: Number(stage), path: record.subarray(tab + 1) });
+    }
+    start = end + 1;
+  }
+  return entries;
+};
+
+const NOT_A_REPOSITORY = /not a git repository/u;
+const NO_WORK_TREE = /must be run in a work tree/u;
+
+// ONE rev-parse identity per spawn → ok { line } | not-a-repository | no-work-tree | error (a throw,
+// ENOENT, a signal, any other exit, an EMPTY answer). The answer is the stdout minus exactly one
+// terminating LF — never a split: a path may carry a newline. LC_ALL=C pins git's own wording.
+const probe = (arg, { cwd, env, spawn }) => {
+  let r;
+  try {
+    r = spawn('git', ['rev-parse', arg], { cwd, env: { ...withGitPath(env), LC_ALL: 'C' }, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    return { kind: 'error', cause: `git threw synchronously (${err?.message ?? err})` };
+  }
+  if (r == null || typeof r !== 'object') return { kind: 'error', cause: 'the git runner returned no result' };
+  if (r.error) return { kind: 'error', cause: `git could not run (${r.error.code ?? r.error.message ?? r.error})` };
+  if (r.signal) return { kind: 'error', cause: `git rev-parse ${arg} was killed by ${r.signal}` };
+  const stderr = String(r.stderr ?? '').trim();
+  if (r.status === 128 && NOT_A_REPOSITORY.test(stderr)) return { kind: 'not-a-repository', cause: stderr };
+  if (r.status === 128 && NO_WORK_TREE.test(stderr)) return { kind: 'no-work-tree', cause: stderr };
+  if (r.status !== 0) return { kind: 'error', cause: `git rev-parse ${arg} exited ${r.status}${stderr ? ` (${stderr})` : ''}` };
+  const line = String(r.stdout ?? '').replace(/\n$/u, '');
+  if (line.length === 0) return { kind: 'error', cause: `git rev-parse ${arg} answered nothing` };
+  return { kind: 'ok', line };
+};
+
+const identity = (cwd, line, realpath) => {
+  try { return { ok: true, path: realpath(resolve(cwd, line)) }; } catch (err) { return { ok: false, cause: `${line} cannot be resolved (${err?.code ?? err?.message ?? err})` }; }
+};
+
+const located = (state, cause, facts = {}) => ({ state, cause, top: null, gitDir: null, commonDir: null, ...facts });
+
+// resolveGitLocation(cwd, { spawn, env, realpath }) → { state, cause, top, gitDir, commonDir }: the
+// REALPATH identity of the git dir, the common dir and the work-tree top, ambient env vs the
+// GIT_-stripped discovery from cwd. Only `work-tree` proceeds.
+export const resolveGitLocation = (cwd, deps = {}) => {
+  const spawn = deps.spawn ?? spawnSync;
+  const env = deps.env ?? process.env;
+  const realpath = deps.realpath ?? realpathSync;
+  const ambient = { cwd, env, spawn };
+  const stripped = { cwd, env: stripGitLocationEnv(env), spawn };
+  // Precedence (fail closed): the GIT DIR probes decide whether each discovery reaches a repository;
+  // the COMMON DIR and TOP probes then owe ok (or no-work-tree for the top) — anything else is error.
+  const a = probe('--absolute-git-dir', ambient);
+  const s = probe('--absolute-git-dir', stripped);
+  if (a.kind === 'error' || a.kind === 'no-work-tree') return located('error', a.cause);
+  if (s.kind === 'error' || s.kind === 'no-work-tree') return located('error', `under the GIT_-stripped discovery from ${cwd}: ${s.cause}`);
+  if (a.kind === 'not-a-repository' && s.kind === 'not-a-repository') return located('not-a-repository', a.cause);
+  if (a.kind === 'not-a-repository') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) reaches no repository (${a.cause}) while the discovery from ${cwd} does`);
+  if (s.kind === 'not-a-repository') return located('env-only', `the ambient git environment (${LOCATION_VARIABLES}) reaches the git dir ${a.line} while the GIT_-stripped discovery from ${cwd} reaches no repository (${s.cause})`);
+  const ids = {};
+  const ac = probe('--git-common-dir', ambient);
+  const sc = probe('--git-common-dir', stripped);
+  if (ac.kind !== 'ok') return located('error', `the common dir under the ambient git environment: ${ac.cause}`);
+  if (sc.kind !== 'ok') return located('error', `the common dir under the GIT_-stripped discovery: ${sc.cause}`);
+  for (const [name, ax, sx] of [['git dir', a, s], ['common dir', ac, sc]]) {
+    const x = identity(cwd, ax.line, realpath);
+    const y = identity(cwd, sx.line, realpath);
+    if (!x.ok) return located('error', `the ${name} under the ambient git environment: ${x.cause}`);
+    if (!y.ok) return located('error', `the ${name} under the GIT_-stripped discovery: ${y.cause}`);
+    if (x.path !== y.path) return located('redirected', `the ${name} differs: the ambient git environment (${LOCATION_VARIABLES}) resolves it to ${x.path}, the discovery from ${cwd} to ${y.path}`);
+    ids[name] = x.path;
+  }
+  const at = probe('--show-toplevel', ambient);
+  const st = probe('--show-toplevel', stripped);
+  if (at.kind === 'error' || at.kind === 'not-a-repository') return located('error', at.cause);
+  if (st.kind === 'error' || st.kind === 'not-a-repository') return located('error', `under the GIT_-stripped discovery from ${cwd}: ${st.cause}`);
+  if (at.kind === 'no-work-tree' && st.kind === 'no-work-tree') return located('no-work-tree', `the git dir ${ids['git dir']} agrees but git names no work tree (${at.cause})`);
+  if (at.kind === 'no-work-tree') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) names no work tree (${at.cause}) while the discovery from ${cwd} reaches one`);
+  if (st.kind === 'no-work-tree') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) reaches a work tree at ${at.line} while the discovery from ${cwd} names none (${st.cause})`);
+  const x = identity(cwd, at.line, realpath);
+  const y = identity(cwd, st.line, realpath);
+  if (!x.ok) return located('error', `the work-tree top under the ambient git environment: ${x.cause}`);
+  if (!y.ok) return located('error', `the work-tree top under the GIT_-stripped discovery: ${y.cause}`);
+  if (x.path !== y.path) return located('redirected', `the work-tree top differs: the ambient git environment (${LOCATION_VARIABLES}) resolves it to ${x.path}, the discovery from ${cwd} to ${y.path}`);
+  return located('work-tree', null, { top: at.line, gitDir: ids['git dir'], commonDir: ids['common dir'] });
+};

package/tools/grounding.mjs

@@ -33,6 +33,7 @@ import { spawnSync } from 'node:child_process';
 import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { stripGitLocationEnv } from './git-env.mjs';
 // (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
 // READ core only — never autonomy-write.mjs (the import-split invariant).
 import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
@@ -163,9 +164,9 @@ const systemTempRoots = () => [...new Set([tmpdir(), process.env.TMPDIR, '/tmp']
 
 const gitLine = (args, cwd) => {
   // Ambient GIT_* location vars (GIT_DIR / GIT_WORK_TREE / …) would let rev-parse prove a FOREIGN
-  // tree — every location answer must come from cwd alone, for every gitLine consumer.
-  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/i.test(k)));
-  const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', windowsHide: true });
+  // tree — every location answer must come from cwd alone, for every gitLine consumer. The strip
+  // is the git-env leaf's (GIT_* only — never the test fixtures' hermetic pins).
+  const r = spawnSync('git', args, { cwd, env: stripGitLocationEnv(process.env), encoding: 'utf8', windowsHide: true });
   return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
 };
 

package/tools/held-session.mjs

@@ -0,0 +1,165 @@
+import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mjs';
+import { wrapperCmdFor } from './detect-backends.mjs';
+import { DISPLAY_ALIASES } from './recipes.mjs';
+
+const CODE_STEP = 'code';
+const FOLD_KIND = 'fold';
+const RETURN_KIND = 'return';
+const EXECUTE_BACKEND = 'codex-cli-bridge';
+const UNPOPULATED_HELD_ID = '<held id>';
+
+export const HELD_RECEIPT_BACKEND = DISPLAY_ALIASES[EXECUTE_BACKEND];
+export const HELD_EXECUTE_WRAPPER = wrapperCmdFor(EXECUTE_BACKEND, 'execute');
+
+const readsInsideEpoch = (dispatch, head) => {
+  if (head.state === 'unborn') return true;
+  const instant = Date.parse(dispatch.timestamp);
+  return Number.isFinite(instant) && Math.floor(instant / 1000) > head.seconds;
+};
+
+const updatesThread = (threads, nonce, update) =>
+  threads.map((thread) => (thread.nonce === nonce ? { ...thread, ...update } : thread));
+
+const findsDispatch = (dispatches, nonce) => dispatches.find((dispatch) => dispatch.nonce === nonce) ?? null;
+const findsReturn = (returns, nonce) => returns.find((returned) => returned.nonce === nonce) ?? null;
+const hasCoveredReplacement = (returned, degrades) =>
+  degrades.some((degrade) => degrade.fingerprint === returned.postTreeDigest);
+const collectsRetryChainNonces = (dispatches, nonce, collected = new Set()) => {
+  if (nonce === null || collected.has(nonce)) return collected;
+  const next = new Set(collected).add(nonce);
+  return collectsRetryChainNonces(dispatches, findsDispatch(dispatches, nonce)?.retryOf ?? null, next);
+};
+
+const accumulatesFacts = (degrades) => (state, record) => {
+  if (record.kind === 'dispatch' && state.epochNonces.has(record.nonce)) {
+    const expectedId = state.heldId;
+    return {
+      ...state,
+      dispatches: [...state.dispatches, record],
+      threads: [...state.threads, { nonce: record.nonce, expectedId, actualId: null, status: 'OPEN' }],
+      open: record.baselineClean === false ? [...state.open, { nonce: record.nonce, expectedId }] : state.open,
+    };
+  }
+  if (record.kind === RETURN_KIND && state.epochNonces.has(record.nonce)) {
+    const dispatch = findsDispatch(state.dispatches, record.nonce);
+    if (dispatch === null) return state;
+    const expectedId = state.threads.find((thread) => thread.nonce === record.nonce)?.expectedId ?? null;
+    const status = record.sessionId === null ? 'FAILED'
+      : expectedId === null ? 'FIRST'
+      : dispatch.retryOf !== null || record.sessionId === expectedId ? 'CONTINUED'
+        : 'SUBSTITUTED';
+    const substitution = status === 'SUBSTITUTED' && dispatch.baselineClean === false
+      && !hasCoveredReplacement(record, degrades)
+      ? {
+        nonce: record.nonce, expectedId, actualId: record.sessionId,
+        postTreeDigest: record.postTreeDigest, folded: false,
+      }
+      : null;
+    return {
+      ...state,
+      returns: [...state.returns, record],
+      threads: updatesThread(state.threads, record.nonce, { actualId: record.sessionId, status }),
+      open: state.open.filter((thread) => thread.nonce !== record.nonce),
+      substitutions: substitution === null
+        ? state.substitutions
+        : [...state.substitutions, substitution],
+    };
+  }
+  if (record.kind === FOLD_KIND && state.epochNonces.has(record.nonce)) {
+    const dispatch = findsDispatch(state.dispatches, record.nonce);
+    const returned = findsReturn(state.returns, record.nonce);
+    if (dispatch === null || returned === null || returned.sessionId === null) return state;
+    const establishes = state.heldId === null;
+    const retries = dispatch.retryOf !== null;
+    const replaces = returned.sessionId !== state.heldId && hasCoveredReplacement(returned, degrades);
+    const retryChain = retries ? collectsRetryChainNonces(state.dispatches, dispatch.retryOf) : new Set();
+    const foldedSubstitutions = state.substitutions.map((substitution) =>
+      (substitution.nonce === record.nonce ? { ...substitution, folded: true } : substitution));
+    const substitutions = retries
+      ? foldedSubstitutions.filter((substitution) => !retryChain.has(substitution.nonce))
+      : foldedSubstitutions;
+    if (establishes || retries || replaces) return { ...state, heldId: returned.sessionId, substitutions };
+    return { ...state, substitutions };
+  }
+  return state;
+};
+
+const countsHeldFolds = (records, epochNonces, heldId) => {
+  if (heldId === null) return 0;
+  return records.filter((record) => {
+    if (record.kind !== FOLD_KIND || !epochNonces.has(record.nonce)) return false;
+    return records.find((candidate) => candidate.kind === RETURN_KIND && candidate.nonce === record.nonce)?.sessionId === heldId;
+  }).length;
+};
+
+export const judgeHeldSession = (records, { head, backend, degrades = [] }) => {
+  if (head.state === 'error') {
+    return { state: 'error', cause: 'head', reason: head.reason, heldId: null, folds: 0, substitution: null, threads: [], open: [] };
+  }
+  const dispatches = records.filter((record) =>
+    record.kind === 'dispatch'
+    && record.stepClass === CODE_STEP
+    && record.backend === backend
+    && readsInsideEpoch(record, head));
+  const epochNonces = new Set(dispatches.map((dispatch) => dispatch.nonce));
+  const initial = { epochNonces, dispatches: [], returns: [], heldId: null, substitutions: [], threads: [], open: [] };
+  const accumulated = records.reduce(accumulatesFacts(degrades), initial);
+  return {
+    state: 'ok',
+    heldId: accumulated.heldId,
+    folds: countsHeldFolds(records, epochNonces, accumulated.heldId),
+    substitution: accumulated.substitutions[0] ?? null,
+    threads: accumulated.threads,
+    open: accumulated.open,
+  };
+};
+
+export const judgeLedger = (ledger, { backend, degrades = [] }) => {
+  if (ledger.state === 'absent') {
+    return { state: 'absent', heldId: null, folds: 0, substitution: null, threads: [], open: [] };
+  }
+  if (ledger.state === 'error') {
+    return { state: 'error', cause: 'ledger', reason: ledger.reason, heldId: null, folds: 0, substitution: null, threads: [], open: [] };
+  }
+  return judgeHeldSession(ledger.records, { head: ledger.head, backend, degrades });
+};
+
+export const decideHeldSession = (facts) => {
+  if (facts.state === 'absent') {
+    const reason = 'no delegation ledger was recorded';
+    return { code: 0, reason, line: `held session: none — ${reason}` };
+  }
+  if (facts.state === 'error') {
+    return { code: 1, reason: facts.reason, line: `held session: unavailable — ${facts.reason}` };
+  }
+  if (facts.substitution !== null) {
+    const { nonce, expectedId, actualId } = facts.substitution;
+    const reason = `delegated code thread "${nonce}" substituted held session "${escapeForDisplay(expectedId)}" with "${escapeForDisplay(actualId)}"`;
+    return { code: 1, reason, line: `held session: SUBSTITUTED — ${reason}` };
+  }
+  if (facts.heldId === null) return { code: 0, reason: 'no folded code thread in the commit epoch carries a session yet', line: 'held session: none' };
+  const heldId = escapeForDisplay(facts.heldId);
+  return { code: 0, reason: `held session "${heldId}" is continuous`, line: `held session: ${heldId} — ${facts.folds} fold(s) rode it` };
+};
+
+const describesLaneCaveat = (facts) => {
+  if (facts.state === 'absent') return decideHeldSession(facts).reason;
+  if (facts.state === 'error') return decideHeldSession(facts).reason;
+  if (facts.substitution !== null) return decideHeldSession(facts).reason;
+  if (facts.heldId === null) return decideHeldSession(facts).reason;
+  if (!isRenderableLine(facts.heldId)) return 'the held session id cannot be rendered on one command line';
+  return null;
+};
+
+export const foldLaneLines = (facts) => {
+  const caveat = describesLaneCaveat(facts);
+  const heldId = caveat === null ? shellQuoteArg(facts.heldId) : UNPOPULATED_HELD_ID;
+  const lines = [
+    'Fold lane (execute = delegated) — a fold rides the delegate\'s HELD session:',
+    `  run:  ${HELD_EXECUTE_WRAPPER} --resume ${heldId} --nonce <nonce> <fold-brief>`,
+    '  the fold brief is a dispatch file carrying the finding and the accepted fold; dispatch open precedes the run, then dispatch return and fold follow it',
+    '  the orchestrator runs the suites, verifies the returned diff, re-mints the red-proofs and owns the commit',
+    '  a fresh session is a forbidden substitution; a retry of a failed thread or a recorded execute degrade is the exception; the wrapper sidecar is never read',
+  ];
+  return caveat === null ? lines : [...lines, `  caveat: ${caveat}`];
+};

package/tools/plan-shape-facts.mjs

@@ -1,6 +1,7 @@
 import { lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { classIds, readShippedRobustnessLiterals } from './robustness-literals.mjs';
 import { segmentPrefixOf, validateSourceSizeConfig } from './source-size-config.mjs';
 import { getLineCount, isSweep, resolveAnchorCandidates, unique } from './plan-shape.mjs';
 
@@ -83,6 +84,14 @@ const loadPractice = (root) => {
   }
 };
 
+const loadRobustClasses = (deps) => {
+  try {
+    return classIds(readShippedRobustnessLiterals(deps));
+  } catch (error) {
+    throw usageError(`robustness-literals list is unreadable (${error.message})`);
+  }
+};
+
 const isInScope = (path, config) => Boolean(config &&
   config.roots.some((root) => segmentPrefixOf(root, path)) &&
   !config.exclude.some((excluded) => segmentPrefixOf(excluded, path)) &&
@@ -111,6 +120,12 @@ const compileGlob = (pattern) => {
   }
 };
 
+const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
+  const compiled = compileGlob(pattern);
+  if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
+  return [pattern, repoFiles.filter((path) => compiled.test(path))];
+}));
+
 const matchFilesEntry = (entry, ownedPath) => {
   const normalized = entry.replace(/^\.\//, '').replace(/\/$/, '');
   if (normalized === '' || normalized === '.') return { known: true, matches: true };
@@ -185,20 +200,18 @@ const describePath = (root, path, practice, repoFiles, packageCache) => {
   };
 };
 
-export const openRepo = (root) => {
+export const openRepo = (root, { robustnessDeps } = {}) => {
   const repoRoot = realpathSync(root);
-  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), packageCache: new Map() };
+  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps), packageCache: new Map() };
 };
 
-export const buildFacts = (root, { paths = [], repo = openRepo(root) } = {}) => {
-  const { repoRoot, repoFiles, practice, packageCache } = repo;
-  const expansions = Object.fromEntries(paths.filter(isSweep).map((pattern) => {
-    const compiled = compileGlob(pattern);
-    if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
-    return [pattern, repoFiles.filter((path) => compiled.test(path))];
-  }));
+export const expandSweepPaths = (root, patterns) => expandPatterns(walkRegularFiles(realpathSync(root)), patterns);
+
+export const buildFacts = (root, { paths = [], robustnessDeps, repo = openRepo(root, { robustnessDeps }) } = {}) => {
+  const { repoRoot, repoFiles, practice, robustClasses, packageCache } = repo;
+  const expansions = expandPatterns(repoFiles, paths.filter(isSweep));
   const allPaths = unique([...paths, ...Object.values(expansions).flat()]);
   const pathFacts = Object.fromEntries(allPaths.map((path) => [path, describePath(repoRoot, path, practice, repoFiles, packageCache)]));
   const candidates = (suffix, precedingPaths = []) => resolveAnchorCandidates(repoFiles, suffix, precedingPaths);
-  return { capDeclared: practice.capDeclared, cap: practice.cap, pathFacts, expansions, repoFiles, candidates };
+  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates };
 };

package/tools/plan-shape.mjs

@@ -1,4 +1,5 @@
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { parseRobustTag } from './robustness-literals.mjs';
 
 export const PLAN_TITLE_PREFIX = '# Plan: ';
 export const PLAN_HEADINGS = Object.freeze([
@@ -243,8 +244,15 @@ const getCurrentLines = (rows, facts, verbs) => rows
 const checkAuthoring = (parsed, facts) => {
   const findings = [];
   const bullets = getVerificationBullets(parsed.document);
+  const robustClasses = new Set(facts.robustClasses ?? []);
   for (const [index, row] of parsed.rows.entries()) {
     if (!row.valid) continue;
+    const robust = parseRobustTag(row.responsibility);
+    const unknownRobustClass = robust.classes?.find((classId) => !robustClasses.has(classId));
+    if (robust.refusal || unknownRobustClass !== undefined) {
+      const reason = robust.refusal ? `tag grammar refused ${robust.refusal}` : `class ${unknownRobustClass} is not in the shipped list`;
+      findings.push(makeFinding(row.line, 'robust-class', `${row.id} robust tag: ${reason}`, row.id));
+    }
     const paths = getConcretePaths(row, facts);
     const expectedKind = row.verb === 'create' ? 'absent' : 'regular';
     if (paths.length === 0 && isSweep(row.path)) findings.push(makeFinding(row.line, 'kind', `${row.id} sweep resolves to no regular path`, row.id));

package/tools/procedures.mjs

@@ -46,6 +46,8 @@ import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from
 // orchestration-write (the import-split test pins both direct rules; the TRANSITIVE claim is
 // structural — test/read-graph-purity.test.mjs pins it).
 import { resolveFlowStorePath, readFlowStore } from './flow-store-read.mjs';
+import { readDelegationLedger } from './dispatch-store-read.mjs';
+import { foldLaneLines, HELD_RECEIPT_BACKEND, judgeLedger } from './held-session.mjs';
 import { CHAIN_KIND } from './flow-record.mjs';
 import { readRegistration } from './mcp-registration.mjs';
 // The declared source-size practice (D-17 U1), read through the practice's PURE READ core — never
@@ -422,6 +424,7 @@ const foldScopeAdvice = (activity, config, plans) => {
 // only what no canon can: the POPULATED checker commands, and the session register they read. The
 // register is NEVER defaulted by the tool — naming it here is the whole point of the block.
 export const SPEC_CHECK_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'spec-check-cli.mjs');
+export const ROBUSTNESS_BRIEF_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'robustness-brief.mjs');
 const SPEC_OPS_REGISTER = `${PLANS_REL}/spec-ops.list`;
 const specCheckAdvice = (activity) => {
   if (activity !== 'plan-execution') return [];
@@ -433,6 +436,16 @@ const specCheckAdvice = (activity) => {
   ];
 };
 
+const robustnessBriefAdvice = (activity, plans) => {
+  if (activity !== 'plan-execution') return [];
+  const operand = populatedPlan(plans);
+  return [
+    'Robustness brief (every tagged ledger row) — generate the concrete literals before dispatch:',
+    `  • node ${renderToolPath(ROBUSTNESS_BRIEF_TOOL)} --plan ${operand ?? '<plan-file>'}`,
+    ...planDiscoveryCaveat(plans, '--plan', 'populate --plan with the plan in flight.', operand === null ? ['--plan'] : []),
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -579,7 +592,22 @@ const contractLines = ({ cmd, contract, settings }) => {
   return lines;
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck }) => {
+const foldLaneAdvice = ({
+  activity,
+  slots,
+  cwd,
+  env,
+  resolveStore,
+  readStore,
+  audit,
+  readHead,
+}) => {
+  if (activity !== 'plan-execution' || slots.find((slot) => slot.slot === 'execute')?.recipe !== 'delegated') return [];
+  const ledger = readDelegationLedger(cwd, env, { resolveStore, readStore, audit, readHead });
+  return foldLaneLines(judgeLedger(ledger, { backend: HELD_RECEIPT_BACKEND, degrades: [] }));
+};
+
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }) => {
   const lines = [
     section,
     '',
@@ -599,6 +627,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
       for (const line of dispatchForm({ activity, slot: s.slot, state: v.state })) lines.push(`      ${line}`);
     }
     for (const c of s.contracts ?? []) lines.push(...contractLines(c));
+    if (s.slot === 'execute' && foldLane.length) lines.push('', ...foldLane);
   }
   if ((flowHalves ?? []).length) lines.push('', ...flowHalves);
   const autonomyBlock = autonomyAdvice(activity, autonomy);
@@ -610,6 +639,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if (advice.length) lines.push('', ...advice);
   if (foldScope.length) lines.push('', ...foldScope);
   if (specCheck.length) lines.push('', ...specCheck);
+  if (robustnessBrief.length) lines.push('', ...robustnessBrief);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -619,7 +649,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -640,6 +670,8 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   foldScope,
   // ADDITIVE (spec layer 2b): the spec-store block, structured (empty outside plan-execution).
   specCheck,
+  robustnessBrief,
+  foldLane,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
   // ADDITIVE (D-17 U1): the SAME composed lines the human render prints — one array, two renders, so
@@ -733,9 +765,20 @@ export const main = (argv, ctx = {}) => {
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
     const foldScope = foldScopeAdvice(activity, config, plans);
     const specCheck = specCheckAdvice(activity);
+    const robustnessBrief = robustnessBriefAdvice(activity, plans);
+    const foldLane = foldLaneAdvice({
+      activity,
+      slots,
+      cwd,
+      env,
+      resolveStore: ctx.resolveDelegationStorePath,
+      readStore: ctx.readDelegationStore,
+      audit: ctx.auditDelegationStoreSemantics,
+      readHead: ctx.readHeadInstant,
+    });
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

package/tools/repo-lex.mjs

@@ -39,6 +39,35 @@ const LINE_BREAKING_ALL = new RegExp(LINE_BREAKING_SOURCE, 'gu');
 export const isRenderableLine = (value) => typeof value === 'string' && !LINE_BREAKING.test(value);
 export const escapeForDisplay = (value) => String(value).replace(LINE_BREAKING_ALL, (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`);
 
+// The control-byte gate's predicate over ONE byte (an integer 0..255, a Buffer element): C0 minus
+// TAB, LF and CR, plus DEL. Bytes at or above 0x80 are never judged here (UTF-8 validity and C1
+// controls are the gate's stated non-goals). ONE home, beside the artifact-path rule below, which
+// keeps refusing TAB, LF and CR as its bash twins do.
+export const isRefusedControlByte = (byte) => byte <= 0x08 || byte === 0x0b || byte === 0x0c || (byte >= 0x0e && byte <= 0x1f) || byte === 0x7f;
+
+// The injective renderer of a path's raw BYTES for a report line: bytes decode as UTF-8 where a
+// sequence is valid, every LINE_BREAKING code point and a valid U+FFFD render as \u{XXXX}, an invalid
+// byte as \xNN and a backslash as \\ — so two names differing only in an unrenderable byte render differently,
+// a name carrying a raw byte differs from a name spelling its escape, and no output line carries a
+// raw control byte or U+FFFD. Separate from escapeForDisplay, whose string-rendering consumers keep their contract.
+const utf8SequenceLength = (lead) => (lead < 0x80 ? 1 : (lead & 0xe0) === 0xc0 ? 2 : (lead & 0xf0) === 0xe0 ? 3 : (lead & 0xf8) === 0xf0 ? 4 : 0);
+export const renderPathForDisplay = (bytes) => {
+  let out = '';
+  for (let i = 0; i < bytes.length;) {
+    const length = utf8SequenceLength(bytes[i]);
+    const slice = length > 0 && i + length <= bytes.length ? bytes.subarray(i, i + length) : null;
+    const decoded = slice === null ? null : slice.toString('utf8');
+    if (decoded === null || !Buffer.from(decoded, 'utf8').equals(slice)) {
+      out += `\\x${bytes[i].toString(16).padStart(2, '0')}`;
+      i += 1;
+      continue;
+    }
+    out += decoded === '\\' ? '\\\\' : LINE_BREAKING.test(decoded) || decoded.codePointAt(0) === 0xfffd ? `\\u{${decoded.codePointAt(0).toString(16)}}` : decoded;
+    i += length;
+  }
+  return out;
+};
+
 // The receipt encoder's carriability rule for an artifact path (S21), the JS twin of the wrappers'
 // refuse_uncarriable_artifact_byte: a quote, a backslash, a C0 control or DEL — deliberately NOT
 // \p{Cc} (C1 is the declared residual, and the two normalizations are parity-pinned on this set).