@sabaiway/agent-workflow-kit 1.46.0 → 1.48.0

package/tools/recommendations.mjs

@@ -19,10 +19,11 @@
 // below) and VERDICT-FIRST (D1): every non-optimal state opens with ONE composed verdict line.
 // Registry strings are frozen tool DATA, fact-true, one line under the shape cap (D2); posture/
 // risk prose lives in the mode doc at the consent moment (D3). A probe failure is a stated
-// skipped-item line — never a crash, never a fabricated item. The sandbox-lane item is HAND-APPLY
-// by design (bridge council 2026-07-11, both backends concur): the kit never seeds
-// sandbox.network.allowedDomains / filesystem.allowWrite; its convergence is a NEUTRAL
-// fingerprint-bound acknowledgement, never a security key (D4).
+// skipped-item line — never a crash, never a fabricated item. The kit never seeds
+// sandbox.network.allowedDomains / filesystem.allowWrite (HAND-APPLY territory; bridge council
+// 2026-07-11, both backends concur); the sandbox-lane item's convergence is a NEUTRAL
+// fingerprint-bound acknowledgement recorded by the consent-gated ack writer into the family-owned
+// docs/ai/acks.json (AD-055 relocated it off the host settings schema), never a security key (D4).
 //
 // Read-only: never writes, never commits, never runs a subscription CLI. The reused probes are all
 // exported read-only surfaces of their owning tools (velocity/autonomy/doctor/backends/recipes/
@@ -55,6 +56,7 @@ import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { DEFAULT_BUNDLE_ROOT, SETTINGS_FILENAME, settingsPath, parseSettings, duplicateKeys } from './bridge-settings-read.mjs';
+import { assertContainedRealPath } from './fs-safe.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -95,6 +97,9 @@ export const SEVERITIES = Object.freeze({
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gate-hook': SEVERITY_OPTIONAL,
+  'read-lane': SEVERITY_OPTIONAL,
+  'read-lane.stale': SEVERITY_ATTENTION,
+  'read-lane.missing': SEVERITY_ATTENTION,
   'family-freshness': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
   'agy-adddir': SEVERITY_OPTIONAL,
@@ -147,6 +152,9 @@ export const WHATS = Object.freeze({
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
+  'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
+  'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
+  'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
   'family-freshness': '{parts}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
@@ -197,6 +205,7 @@ export const BENEFITS = Object.freeze({
   'review-recipe': 'review coverage — the review recipe you configured actually runs instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
+  'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
   'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
@@ -334,6 +343,43 @@ const probeGates = ({ root, deps, add, skip }) => {
   }
 };
 
+// The read-lane offer (AD-055 Part II, Help-through-Recommendations): once the gate hook is PLACED
+// and WIRED, offer to enable the opt-in read-only compound lane. Mutually exclusive with the
+// gate-hook item BY CONSTRUCTION — that item keys on `!wired`, this one on `wired` — so an unplaced
+// or un-wired hook is covered there, never double-offered here. The apply is the gate-hook
+// --read-lane PREVIEW one-liner (its own currency check + posture note fire at the writer; it may
+// prompt once — it IS a consent flow). Converges once lanes.json enables the lane.
+const probeReadLane = ({ root, deps, add, skip }) => {
+  try {
+    const sg = surveyGateHook(root, deps);
+    if (sg.error) throw new Error(sg.error);
+    if (!sg.wired) return; // not wired → the gate-hook item covers (no double-fire)
+    if (!sg.filePlaced) {
+      // Wired but the placed hook FILE is missing — the hook errors on every Bash call and the lane
+      // is silently dark; surface it as attention with a place-first recovery (council R2-M2).
+      add('read-lane', fillTemplate(WHATS['read-lane.missing'], {}), `node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`, 'read-lane.missing');
+      return;
+    }
+    if (readReadLaneToggle(root, deps)) {
+      // The lane is ON: converged IFF the placed hook is byte-current — a stale (pre-1.48) hook never
+      // reads lanes.json, so the enabled lane is a silent no-op the user must reseed (council B7). The
+      // rm target is ABSOLUTE (council R2-M3) so running the recovery from any cwd can only delete this
+      // repo's hook.
+      if (isPlacedHookCurrent(root, deps)) return; // converged
+      add(
+        'read-lane',
+        fillTemplate(WHATS['read-lane.stale'], {}),
+        `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+        'read-lane.stale',
+      );
+      return;
+    }
+    add('read-lane', fillTemplate(WHATS['read-lane'], {}), `node ${q(toolPath('gate-hook.mjs'))} --read-lane --cwd ${q(root)}`);
+  } catch (err) {
+    skip('read-lane', err);
+  }
+};
+
 const probeFamilyFreshness = ({ deps, add, skip }) => {
   try {
     const survey = deps.surveyFamily ?? surveyFamily;
@@ -485,15 +531,102 @@ export const recipeFingerprint = ({ hosts, dirs, home }) => {
   return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
 };
 
-// The kit-owned neutral ack namespace (D4): project-scoped, hand-applicable as one line, read from
-// BOTH settings scopes; the sandbox/permissions security keys are NEVER consulted as an ack.
+// The kit-owned neutral ack store (D4; AD-055 Part I): a FAMILY-OWNED strict-JSON file no host
+// validator guards — top-level key `sandboxLaneAck` (+ optional `_README`), unknown keys tolerated
+// on read (future acks are siblings). This is the PRIMARY ack channel; the legacy settings-scope
+// keys below are read for one deprecation window. The sandbox/permissions security keys are NEVER
+// consulted as an ack.
+export const ACKS_FILE = 'docs/ai/acks.json';
+export const ACKS_LANE_KEY = 'sandboxLaneAck';
+
+// The opt-in read-lane toggle file (AD-055 Part II) — the SAME kit-owned docs/ai/lanes.json the
+// placed hook reads live. The read-lane item offers to enable it once the hook is placed+wired.
+export const LANES_FILE = 'docs/ai/lanes.json';
+export const READ_LANE_KEY = 'readLane';
+
+// The placed gate hook + the bundled runtime the read-lane item byte-compares for currency (AD-055
+// Part II, council B7): an enabled lane over a STALE hook is a silent no-op — the pre-1.48 hook never
+// reads lanes.json — so it must surface as an ATTENTION reseed, not a silent convergence.
+const GATE_HOOK_REL = '.claude/hooks/agent-workflow-gates.mjs';
+const BUNDLED_HOOK_ABS = join(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
+
+// Byte-compare the placed gate hook against the bundled runtime. A read error (an unreadable placed
+// hook, a broken kit bundle) propagates → the probe states a skip, never a wrong currency verdict.
+const isPlacedHookCurrent = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const placed = readFile(join(root, GATE_HOOK_REL), 'utf8');
+  const bundle = readFile(deps.bundledHookPath ?? BUNDLED_HOOK_ABS, 'utf8');
+  return placed === bundle;
+};
+
+// The LEGACY neutral ack namespace (pre-AD-055): read from BOTH settings scopes until the next kit
+// MAJOR (2.0.0) so a never-migrated host stays converged across the deprecation window (Decisions 3).
 export const SANDBOX_LANE_ACK_PARENT = 'agentWorkflow';
 export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
 
+// Read the family-owned ack store. An ABSENT file (or absent docs/ai) is the NORMAL not-yet-acked
+// state → null (plain fall-through, never a skip). A parse/IO error on an EXISTING file THROWS — the
+// probe's catch turns it into a stated skip line (Decisions 2). A non-object root is a malformed
+// store (fail-closed skip); a non-string value at the key is tolerated → null (the item re-fires).
+// The WHOLE path chain (root / docs / ai / acks.json) is guarded WITHOUT following symlinks
+// BEFORE any read: a symlinked ANCESTOR could otherwise read an ack from OUTSIDE the project (the
+// writer refuses such a deployment — the reader must too), a symlinked/dangling LEAF must not read as
+// not-yet-acked, and a non-regular target (FIFO/dir/device) is a fail-closed SKIP — never read it (a
+// FIFO would BLOCK the advisor). ENOENT-safe: an absent file/dir is the NORMAL not-yet-acked null.
+const readAcksLane = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, ACKS_FILE);
+  let st;
+  try {
+    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
+    st = lstat(absPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null; // genuinely absent (file or docs/ai) — normal not-yet-acked
+    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
+  }
+  if (!st.isFile()) {
+    throw new Error(`${ACKS_FILE} is not a regular file — refusing to read it`);
+  }
+  const parsed = JSON.parse(readFile(absPath, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${ACKS_FILE}: expected a JSON object`);
+  }
+  const value = parsed[ACKS_LANE_KEY];
+  return typeof value === 'string' ? value : null;
+};
+
+// Read the opt-in read-lane toggle for the read-lane item. An ABSENT file (or absent docs/ai) →
+// false (the lane is off — offer it). `readLane === true` → enabled (converged). A parse/IO error on
+// an EXISTING file, a symlinked ancestor/leaf, an escape, or a non-object root THROWS — the probe
+// turns it into a stated skip (a BROKEN toggle the writer would refuse to overwrite is not "off").
+// A present-but-non-boolean `readLane` is a valid store the writer merges → false (offer), never a skip.
+const readReadLaneToggle = (root, deps) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const absPath = join(root, LANES_FILE);
+  let st;
+  try {
+    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
+    st = lstat(absPath);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false; // genuinely absent — the lane is off, offer it
+    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
+  }
+  if (!st.isFile()) {
+    throw new Error(`${LANES_FILE} is not a regular file — refusing to read it`);
+  }
+  const parsed = JSON.parse(readFile(absPath, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${LANES_FILE}: expected a JSON object`);
+  }
+  return parsed[READ_LANE_KEY] === true;
+};
+
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane']);
+export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane', 'read-lane']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -522,14 +655,28 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
       if (!dirs.includes(resolved)) dirs.push(resolved);
     }
     const fingerprint = recipeFingerprint({ hosts, dirs, home });
-    // Convergence is the NEUTRAL fingerprint-bound acknowledgement, read from BOTH scopes — a
-    // changed recipe (hosts, dirs, or an env override) re-fires the item (D4).
-    const acks = [settings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY], localSettings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY]];
+    // Convergence is the NEUTRAL fingerprint-bound acknowledgement: the item converges iff the
+    // CURRENT fingerprint equals the ack in ANY consulted store — the family-owned acks.json FIRST,
+    // then the legacy settings scopes; a stale value in one store is ignored when another matches
+    // (Decisions 2). A changed recipe (hosts, dirs, or an env override) re-fires the item (D4).
+    const acks = [
+      readAcksLane(root, deps),
+      settings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
+      localSettings.data?.[SANDBOX_LANE_ACK_PARENT]?.[SANDBOX_LANE_ACK_KEY],
+    ];
     if (acks.includes(fingerprint)) return; // the acknowledged recipe — the item converged
+    // The item joins the CONSENT-GATED WRITER class (Decisions 4): the apply is the ack writer's
+    // PREVIEW one-liner (pure executable, cwd-independent), carrying the neutral fingerprint — never
+    // a security key. The LIVE recipe (egress hosts + resolved writable dirs) rides a separate
+    // rendered `recipe:` line (the fill source for the mode doc's lane-(2) hand-apply block); the
+    // fingerprint encodes it, so a changed recipe re-fires with a fresh command.
+    const recipe = `egress hosts [${hosts.join(', ')}]; writable state dirs [${dirs.join(', ')}] (observed-minimal; a blocked host names itself at run time)`;
     add(
       'sandbox-lane',
       fillTemplate(WHATS['sandbox-lane'], {}),
-      `HAND-APPLY (a neutral acknowledgement, never a security key): recipe — egress hosts [${hosts.join(', ')}]; writable state dirs [${dirs.join(', ')}] (observed-minimal; a blocked host names itself at run time); what to DO with it per host class: the mode doc's sandbox-lanes section; once handled, record the ack: set "${SANDBOX_LANE_ACK_PARENT}"."${SANDBOX_LANE_ACK_KEY}" to "${fingerprint}" in .claude/settings.json or settings.local.json — a MERGE into the existing ${SANDBOX_LANE_ACK_PARENT} object (keep its other keys; create it only if absent)`,
+      `node ${q(toolPath('ack-write.mjs'))} --fingerprint ${fingerprint} --cwd ${q(root)}`,
+      'sandbox-lane',
+      recipe,
     );
   } catch (err) {
     skip('sandbox-lane', err);
@@ -543,6 +690,7 @@ const PROBES = Object.freeze([
   probeSandboxProvision,
   probeReviewRecipe,
   probeGates,
+  probeReadLane,
   probeFamilyFreshness,
   probeMasksItem,
   probeAgyAdddir,
@@ -560,18 +708,22 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // violation surfaces through the stated-skip lane, never a crash, never a rendered violation.
   // severityKey defaults to the item key; a per-site arm passes its `<key>.<variant>` entry when
   // its class differs from the base (the invalid-env attention arm).
-  const add = (key, what, apply, severityKey = key) => {
+  // `detail` (optional) is an extra rendered `recipe:` line — factual context that is TOO LONG for
+  // the capped WHAT and does NOT belong in the pure-command apply (the sandbox-lane live recipe:
+  // egress hosts + resolved writable dirs). Single-line like apply; absent for every other item.
+  const add = (key, what, apply, severityKey = key, detail = null) => {
     const problems = [];
     if (!(key in BENEFITS)) problems.push(`unregistered item key ${JSON.stringify(key)}`);
     if (!(severityKey in SEVERITIES)) problems.push(`unregistered severity key ${JSON.stringify(severityKey)}`);
     if (/[\r\n]/.test(what)) problems.push('WHAT is not a single line');
     else if (what.length > ITEM_LINE_CAP) problems.push(`WHAT exceeds the ${ITEM_LINE_CAP}-char cap (${what.length})`);
     if (/[\r\n]/.test(apply)) problems.push('apply is not a single line');
+    if (detail != null && /[\r\n]/.test(detail)) problems.push('recipe detail is not a single line');
     if (problems.length > 0) {
       skip(key, new Error(`item shape violation — ${problems.join('; ')}`));
       return;
     }
-    items.push({ key, severity: SEVERITIES[severityKey], what, benefit: BENEFITS[key], apply });
+    items.push({ key, severity: SEVERITIES[severityKey], what, benefit: BENEFITS[key], apply, detail });
   };
   for (const probe of deps.probes ?? PROBES) probe({ root, deps, add, skip });
   return { root, items, skips };
@@ -599,6 +751,7 @@ export const formatRecommendations = ({ items, skips }) => {
     ordered.forEach((item, i) => {
       lines.push(`${i + 1}. ${SEVERITY_LABELS[item.severity] ?? SEVERITY_LABELS[SEVERITY_OPTIONAL]}: ${item.what}`);
       lines.push(`   benefit: ${item.benefit}`);
+      if (item.detail) lines.push(`   recipe: ${item.detail}`);
       lines.push(`   apply: ${item.apply}`);
     });
   }
@@ -615,15 +768,16 @@ Usage:
 
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
-sub-optimal · the benefit in one plain line · the exact consent-gated apply one-liner}. --cwd is
+sub-optimal · the benefit in one plain line · an optional \`recipe:\` line (the sandbox-lane live
+recipe only) · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;
 the doctor item pins via a cd prefix; the ONE exception is the set-autonomy item — a
 conversational skill invocation labeled "run IN the target project") and preserve each writer's
-own consent semantics; the sandbox-lane item is HAND-APPLY by design — this tool and the kit
-writers never seed sandbox network/filesystem allowances, and its convergence is a neutral
-fingerprint acknowledgement, never a security key.
+own consent semantics; the kit never seeds sandbox network/filesystem allowances (HAND-APPLY
+territory), and the sandbox-lane convergence is a neutral fingerprint acknowledgement recorded by
+the consent-gated ack writer into docs/ai/acks.json (never a security key).
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;

package/tools/review-ledger-write.mjs

@@ -406,7 +406,91 @@ export const recordTriage = (params, deps = {}) => {
   return appendRecord(ledgerPath, record, deps);
 };
 
-// ── CLI (record / classify) ──────────────────────────────────────────────────────────────────────
+// ── batch (D4/D5 — one invocation applies an ordered list of record/classify/override ops) ────────
+// The prompt-economy lane (WRITER-BURST-BATCH): the ledger triad a records stage would otherwise
+// fire one writer call at a time — records, classifications, overrides — rides ONE `batch`
+// invocation. Every op runs the SAME single-verb code path (no forked validator, D4), so a batch of
+// N ops is record-equivalent to the same N single-verb invocations. TWO passes (D5): pass 1
+// validates the WHOLE envelope structurally with ZERO writes (a bad envelope stops before any op
+// runs); pass 2 applies the ops sequentially — a DOMAIN failure (a tooth, a missing receipt, a
+// malformed record) stops the batch with an honest report, and the ops already applied stay recorded
+// (the ledger is append-only — no rollback pretense).
+
+// The verbs a batch operation may carry — the SAME functions the single verbs dispatch.
+const BATCH_VERBS = new Set(['record', 'classify', 'override']);
+
+// Pass 1 — structural envelope validation, ZERO writes (a usage failure, exit 2). Deep per-op payload
+// validity is NOT checked here (that is pass 2's single-verb code path — checking it here would fork
+// the validator); pass 1 proves only the envelope shape + a known verb per op, so no raw TypeError
+// and no silent success reaches pass 2.
+export const validateBatchEnvelope = (payload) => {
+  if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw usageFail('batch payload must be an object of the form { "operations": [ … ] }');
+  }
+  const operations = payload.operations;
+  if (!Array.isArray(operations)) throw usageFail('batch payload.operations must be an array of operations');
+  if (operations.length === 0) throw usageFail('batch payload.operations is empty — nothing to record');
+  operations.forEach((op, i) => {
+    if (op == null || typeof op !== 'object' || Array.isArray(op)) {
+      throw usageFail(`batch operation [${i}] must be an object of the form { "verb": …, … }`);
+    }
+    if (!BATCH_VERBS.has(op.verb)) {
+      throw usageFail(`batch operation [${i}] names an unknown verb "${op.verb}" (expected: record | classify | override)`);
+    }
+    // The batch resolves cwd/env from the INVOCATION, never per operation — a per-op override could
+    // read one project's state and write another's ledger. Reject it loudly.
+    for (const forbidden of ['cwd', 'env']) {
+      if (forbidden in op) {
+        throw usageFail(`batch operation [${i}] carries a "${forbidden}" field — the batch resolves cwd/env from the invocation, never per operation`);
+      }
+    }
+    // fromReceipts must be a real boolean: a string "false" is truthy and would silently enable the
+    // draft. Reject any non-boolean when the field is present.
+    if ('fromReceipts' in op && typeof op.fromReceipts !== 'boolean') {
+      throw usageFail(`batch operation [${i}] has a non-boolean fromReceipts (${JSON.stringify(op.fromReceipts)}) — it must be the literal true or false`);
+    }
+    if ('fromReceipts' in op && op.verb !== 'record') {
+      throw usageFail(`batch operation [${i}] sets fromReceipts on "${op.verb}" — it applies only to record (even the literal false does not belong here)`);
+    }
+  });
+  return operations;
+};
+
+// Apply ONE operation through the SAME single-verb code path main() dispatches (including the
+// --from-receipts backends[] draft for a record op). deps is threaded so a batch is as hermetic as
+// the single verbs.
+const applyOperation = (op, { cwd, env }, deps = {}) => {
+  const { verb, fromReceipts, ...payload } = op;
+  // The invocation's cwd/env WIN (spread last) — validateBatchEnvelope already forbids them in the
+  // payload, so this is defense-in-depth against a direct runBatch call bypassing the preflight.
+  if (verb === 'classify') return recordTriage({ ...payload, cwd, env }, deps);
+  if (verb === 'override') return recordOverride({ ...payload, cwd, env }, deps);
+  const params = { ...payload };
+  if (fromReceipts) {
+    const state = deps.buildState ? deps.buildState({ cwd, env }) : buildState({ cwd, env });
+    params.backends = draftBackendsFromReceipts({ state, findings: params.findings, explicitBackends: params.backends ?? [] }, deps);
+  }
+  return recordRound({ ...params, cwd, env }, deps);
+};
+
+// runBatch({ cwd, env, operations }, deps) → { applied: [ per-op results ], count }. Pass 2: apply
+// sequentially, fail-fast on the first typed STOP; the ops already appended stay recorded.
+export const runBatch = ({ cwd = process.cwd(), env = process.env, operations }, deps = {}) => {
+  const applied = [];
+  for (const [i, operation] of operations.entries()) {
+    try {
+      applied.push(applyOperation(operation, { cwd, env }, deps));
+    } catch (err) {
+      // Honest partial-success (D5): the STOP itself names the failing op index + the applied count.
+      // The ledger is append-only, so those ops are durable — resume by re-running the REMAINING ops.
+      err.message = `${err.message} [batch stopped at operation [${i}]: ${applied.length} of ${operations.length} operation(s) recorded before the stop and durable (append-only ledger); re-run the remaining operations]`;
+      throw err;
+    }
+  }
+  return { applied, count: applied.length };
+};
+
+// ── CLI (record / classify / override / batch) ─────────────────────────────────────────────────────
 
 const HELP = `review-ledger-write — the review-round ledger WRITER (agent-workflow family, AD-045 + AD-047 + AD-048).
 
@@ -414,6 +498,7 @@ Usage:
   node review-ledger-write.mjs record   --json '<round-payload>' [--from-receipts] [--cwd <dir>]
   node review-ledger-write.mjs classify --json '<triage-payload>'   [--cwd <dir>]
   node review-ledger-write.mjs override --json '<override-payload>' [--cwd <dir>]
+  node review-ledger-write.mjs batch    --json '<{ "operations": [ … ] }>' [--cwd <dir>]
   (every verb also accepts --json @<file> — the payload read from a file, keeping the command
    line PLAIN: an inline JSON argv falls outside plain-invocation allow heuristics and prompts)
 
@@ -448,10 +533,24 @@ override appends one override record — the LOUD, durable waiver the gates cons
          sanctions, SEGMENT-scoped — it dies at the next commit, D4).
          REFUSES for a loop that is not the in-flight plan. QUARANTINE (a flaky/timed-out probe)
          has NO override lane.
+batch    applies an ordered list of record / classify / override operations in ONE invocation — the
+         prompt-economy lane for a records stage (one writer call, not one per op). The payload is
+         { "operations": [ { "verb": "record"|"classify"|"override", …that verb's payload } ] }; a
+         record op may carry "fromReceipts": true (the SAME draft as --from-receipts). Each op runs
+         the SAME per-verb code path (no forked validator), so a batch of N ops is record-equivalent
+         to the same N single invocations. TWO passes: the WHOLE envelope is validated structurally
+         first with ZERO writes (a bad envelope stops before any op runs); then ops apply sequentially
+         and fail-fast on the first typed STOP — the ops already applied stay recorded (the ledger is
+         append-only, no rollback), and the STOP names the failing op index + the applied count.
+         Resume by re-running the REMAINING operations.
 
 The read-only checker is a SEPARATE tool: node review-ledger.mjs --check / --status / --json / --telemetry.
 Exit codes: 0 written; 1 a typed STOP (teeth / malformed / missing receipt / fs error); 2 usage.`;
 
+// The CLI subcommand set — the SINGLE source the dispatch and the doc-contract pin both read, so a
+// documented verb list can never lag the dispatch (Phase 2.3 — the contract-test class).
+export const SUBCOMMANDS = ['record', 'classify', 'override', 'batch'];
+
 const parseArgs = (argv) => {
   const opts = { cwd: undefined, json: undefined, fromReceipts: false };
   for (let i = 0; i < argv.length; i += 1) {
@@ -500,11 +599,18 @@ export const main = (argv, ctx = {}) => {
   try {
     if (argv.includes('--help') || argv.includes('-h') || argv.length === 0) return { code: argv.length === 0 ? 2 : 0, stdout: HELP, stderr: '' };
     const sub = argv[0];
-    if (sub !== 'record' && sub !== 'classify' && sub !== 'override') throw usageFail(`unknown subcommand "${sub}" (expected: record | classify | override)`);
+    if (!SUBCOMMANDS.includes(sub)) throw usageFail(`unknown subcommand "${sub}" (expected: ${SUBCOMMANDS.join(' | ')})`);
     const opts = parseArgs(argv.slice(1));
-    if (opts.fromReceipts && sub !== 'record') throw usageFail('--from-receipts applies only to `record`');
+    if (opts.fromReceipts && sub !== 'record') throw usageFail('--from-receipts applies only to `record` (a batch carries fromReceipts per operation)');
     const payload = parsePayload(opts.json);
     const cwd = opts.cwd ?? cwd0;
+    if (sub === 'batch') {
+      // Pass 1 (structural, ZERO writes) → pass 2 (sequential apply, fail-fast — prior ops durable).
+      const operations = validateBatchEnvelope(payload);
+      const { applied, count } = runBatch({ cwd, env, operations });
+      const writtenPath = applied.length ? applied[applied.length - 1].writtenPath : '(none)';
+      return { code: 0, stdout: `review-ledger-write: recorded ${count} operation(s) in one batch → ${writtenPath}`, stderr: '' };
+    }
     if (opts.fromReceipts) {
       // Draft backends[] from the current-fingerprint receipts + the supplied findings; origins /
       // findings stay explicit. The drafted array then rides the normal recordRound teeth.
@@ -513,10 +619,10 @@ export const main = (argv, ctx = {}) => {
     }
     const result =
       sub === 'record'
-        ? recordRound({ cwd, env, ...payload })
+        ? recordRound({ ...payload, cwd, env })
         : sub === 'classify'
-          ? recordTriage({ cwd, env, ...payload })
-          : recordOverride({ cwd, env, ...payload });
+          ? recordTriage({ ...payload, cwd, env })
+          : recordOverride({ ...payload, cwd, env });
     return { code: 0, stdout: `review-ledger-write: recorded a ${result.record.kind} for loop "${result.record.loop}" round ${result.record.round} → ${result.writtenPath}`, stderr: '' };
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `review-ledger-write: ${err.message}` };

package/tools/review-ledger.mjs

@@ -568,7 +568,7 @@ gated commit, so the round-counter reset is earned, never declared.
   rounds, override usage by scope, gate-run counts (quality-green / red-by-gate), fold runs,
   observed-red receipts, quarantined probes. Counts only — interpretation stays with you.
 
-The writer is a SEPARATE tool (review-ledger-write.mjs record/classify/override) — this read-only
+The writer is a SEPARATE tool (review-ledger-write.mjs record/classify/override/batch) — this read-only
 checker never imports it. Sandbox-safe: runs fully inside an OS sandbox (fs + git reads, no
 network) — the D4 sandbox lane. Human residual: git commit --no-verify, ledger-file editing, and
 forged counts remain possible — a self-discipline mechanism, not a security boundary.

package/tools/velocity-profile.mjs

@@ -163,9 +163,12 @@ const RUN_GATES_CWD_FLAG = '--cwd';
 // ── the opt-in --bridge-tier (AD-044 Plan 4, Decision 2) ────────────────────────────────
 // The FROZEN membership source: review-role wrapper NAMES only, spelled bare — that is how the
 // wrappers are invoked (setup-backends places them as symlinks in ~/.local/bin). Roles come from
-// THIS constant, never from the detector's wrapperCmds (which carries no role labels):
-// codex-exec (execution role) and agy-run (probe role) are deliberately ABSENT — delegated
-// execution keeps its human prompt; the velocity pain this tier closes is council REVIEW runs.
+// THIS constant, never from the detector's wrapperCmds (which carries no role labels): codex-exec
+// (execution role) and agy-run (probe role) are deliberately ABSENT. The velocity pain this tier
+// closes is council REVIEW runs; codex-exec's nested-sandbox recovery is handled the canon way —
+// route it outside ON the OBSERVED failure (orchestration.md §5), NOT a preemptive tier seed (AD-054
+// final council: a blanket exclusion at opt-in contradicts «never a preemptive blanket»), guided by
+// codex-exec.sh's own nested-sandbox detection hint.
 export const BRIDGE_REVIEW_WRAPPERS = Object.freeze(['codex-review', 'agy-review']);
 // Only the `code` review mode is auto-allowed (codex R2, Segment A): a bare `Bash(<wrapper>:*)`
 // prefix would also cover the plan/diff file-argument modes, whose targets can point OUTSIDE the
@@ -190,13 +193,12 @@ const isQuotedGroundingToken = (token) => {
 };
 
 /**
- * Derive the opt-in bridge-wrappers tier: one bare-name wildcard allow rule per PLACED review
- * wrapper (the frozen constant is the membership source; placement is a probe, never a role
- * source), the SAME wrapper names for sandbox.excludedCommands (the harness runs an excluded
- * command OUTSIDE the sandbox, so a plain allowlisted invocation needs no sandbox-bypass
- * approval — the zero-prompt wiring), and the grounding pre-step rule in its rendered quoted
- * byte-form (derived only when ≥1 review bridge is placed; an unseedable kit path is a stated
- * skip). An absent bridge is a stated skip — its entry never derives.
+ * Derive the opt-in bridge-wrappers tier: one code-mode allow rule per PLACED review wrapper (the
+ * frozen constant is the membership source; placement is a probe, never a role source), the SAME
+ * wrapper names for sandbox.excludedCommands (the harness runs an excluded command OUTSIDE the
+ * sandbox, so a plain allowlisted invocation needs no sandbox-bypass approval — the zero-prompt
+ * wiring), and the grounding pre-step rule in its rendered quoted byte-form (derived only when
+ * agy-review is placed; an unseedable kit path is a stated skip). An absent bridge is a stated skip.
  */
 export const deriveBridgeTierAllowlist = ({ findWrapper, groundingAbsPath } = {}) => {
   const probe = findWrapper ?? ((cmd) => findOnPath(cmd).state === WRAPPER_PLACED);
@@ -253,8 +255,19 @@ export const RUNTIME_RESIDUAL_FORMS = Object.freeze({
   writeRedirections: Object.freeze(['>', '>>', '1>', '2>', '&>', '>|']),
   // `$(…)` + backtick + process substitution `<(…)` all RUN a nested command (`>(…)` is caught by
   // the `>` redirection scan). Bare `<` is input redirection (reads a file — read-only commands may
-  // already do that), so it is deliberately NOT here.
-  commandSubstitutions: Object.freeze(['$(', '`', '<(']),
+  // already do that), so it is deliberately NOT here. The bash-5.3 function substitutions `${ cmd; }`
+  // (a blank — space/tab/newline/CR — right after `${`) and `${| cmd; }` (runs a command, assigns
+  // REPLY) also execute a nested command — matched as the literal openers `${ ` / `${\t` / `${\n` /
+  // `${\r` / `${|` (AD-055 Part II; the `\r` opener guards CRLF payloads — council agy nit). An
+  // ordinary `${VAR}` parameter expansion has NO blank after `${`, so it trips none of these — kept
+  // rung-(b)-silent on a settings-allowed single (rung (c) excludes all `$`).
+  commandSubstitutions: Object.freeze(['$(', '`', '<(', '${ ', '${\t', '${\n', '${\r', '${|']),
+  // A backslash immediately before a newline/CR is a bash LINE CONTINUATION: bash removes it and
+  // splices the two lines into ONE word, which can reconstruct a residual token (`--output`, `$(`,
+  // `${ …; }`) that a raw substring scan on the pre-splice string misses (`--outp\<newline>ut=f` →
+  // `--output=f`). Guards a settings-allowed SINGLE (rung c already forbids backslash in every
+  // segment). AD-055 Part II council fold (codex B3).
+  lineContinuations: Object.freeze(['\\\n', '\\\r']),
   // The `--output` write-flag family, matched as a raw SUBSTRING of the whole command (never a
   // whitespace-token check): the hook sees the pre-shell command string, so `--output=f`,
   // `"--output=f"`, `'--output' f`, and `\--output` must all trip it — over-asking on a benign