@sabaiway/agent-workflow-kit 3.0.0 → 3.2.0

package/references/scripts/check-docs-size-cli.test.mjs

@@ -0,0 +1,41 @@
+// check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
+// in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
+// colocated file): the unknown-argument refusal and the written-empty-index guard.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from './check-docs-size.mjs';
+
+const cli = async (argv) => {
+  const { code, stdout, stderr } = await runCli(argv);
+  return { code, stdout, stderr };
+};
+
+describe('check-docs-size runCli — refusal branches', () => {
+  it('an unknown argument exits 2 naming it', async () => {
+    const { code, stderr } = await cli(['--bogus']);
+    assert.equal(code, 2);
+    assert.match(stderr, /Unknown argument: --bogus/);
+  });
+
+  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
+    try {
+      mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+      writeFileSync(
+        join(root, 'docs', 'ai', 'a.md'),
+        '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
+      );
+      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
+      // the guard must refuse loudly instead of reporting a written index.
+      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /index\.md was written empty/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/references/scripts/check-docs-size.mjs

@@ -103,25 +103,19 @@ export const discoverMeta = async (root = ROOT) => {
   return { projectName, hierarchicalLinks, onDemandLinks };
 };
 
+// Pure argv parser (no I/O, no exit): `help` / `error` ride out as data for runCli to render.
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
   const opts = { today: null, root: null };
-  for (const arg of argv.slice(2)) {
+  for (const arg of argv) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
     else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
-    else if (arg === '--help' || arg === '-h') {
-      console.log(
-        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]',
-      );
-      process.exit(0);
-    } else {
-      console.error(`Unknown argument: ${arg}`);
-      process.exit(2);
-    }
+    else if (arg === '--help' || arg === '-h') return { flags, opts, help: true };
+    else return { flags, opts, error: `Unknown argument: ${arg}` };
   }
   return { flags, opts };
 };
@@ -218,7 +212,7 @@ const formatRow = (row) => {
   return { status, sizeCell, ...row };
 };
 
-const printReport = (rows, quiet) => {
+const printReport = (rows, quiet, log = console.log) => {
   const widths = {
     status: 2,
     path: Math.max(4, ...rows.map((r) => r.path.length)),
@@ -228,15 +222,15 @@ const printReport = (rows, quiet) => {
   };
   const printable = quiet ? rows.filter((r) => r.errors.length || r.warnings.length) : rows;
   if (printable.length > 0) {
-    console.log(
+    log(
       `${'S'.padEnd(widths.status)}  ${'PATH'.padEnd(widths.path)}  ${'SIZE/MAX'.padEnd(widths.size)}  ${'TYPE'.padEnd(widths.type)}  ${'UPDATED'.padEnd(widths.updated)}`,
     );
     for (const row of printable) {
-      console.log(
+      log(
         `${row.status.padEnd(widths.status)}  ${row.path.padEnd(widths.path)}  ${row.sizeCell.padEnd(widths.size)}  ${(row.frontmatter?.type ?? '').padEnd(widths.type)}  ${(row.frontmatter?.lastUpdated ?? '').padEnd(widths.updated)}`,
       );
-      for (const err of row.errors) console.log(`     - ERROR  ${err}`);
-      for (const warn of row.warnings) console.log(`     - WARN   ${warn}`);
+      for (const err of row.errors) log(`     - ERROR  ${err}`);
+      for (const warn of row.warnings) log(`     - WARN   ${warn}`);
     }
   }
 };
@@ -361,9 +355,29 @@ export const regenerateIndex = async (root, todayStr = null) => {
   return { indexPath, files: rows.length };
 };
 
-const main = async () => {
-  const { flags, opts } = parseArgs(process.argv);
-  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : ROOT);
+// The return-code entry point (no process.argv / process.exit / console inside): argv[] →
+// { code, stdout, stderr }. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+
+  const { flags, opts, help, error } = parseArgs(argv);
+  if (help) {
+    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
+    return result(0);
+  }
+  if (error) {
+    logError(error);
+    return result(2);
+  }
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : (deps.root ?? ROOT));
   const today = computeToday(opts.today);
   const files = (await walkMarkdownFiles(docsDir)).sort();
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
@@ -373,11 +387,11 @@ const main = async () => {
 
   if (flags.writeIndex) {
     await writeIndex(rows, today, meta, indexPath);
-    console.log(`Wrote ${relative(root, indexPath)}`);
+    log(`Wrote ${relative(root, indexPath)}`);
     const after = await stat(indexPath);
     if (after.size === 0) {
-      console.error('index.md was written empty');
-      process.exit(2);
+      logError('index.md was written empty');
+      return result(2);
     }
   }
 
@@ -385,28 +399,31 @@ const main = async () => {
     const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
-      console.error(
+      logError(
         `[check-docs-size] FAIL: ${relative(root, indexPath)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
       );
-      process.exit(1);
+      return result(1);
     }
-    console.log(
+    log(
       `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
-    return;
+    return result(0);
   }
 
-  printReport(rows, flags.quiet);
+  printReport(rows, flags.quiet, log);
   const errorCount = rows.reduce((n, r) => n + r.errors.length, 0);
   const warnCount = rows.reduce((n, r) => n + r.warnings.length, 0);
-  console.log(
+  log(
     `\n${rows.length} files inspected  —  ${errorCount} error(s), ${warnCount} warning(s)`,
   );
 
-  if (errorCount > 0 && !flags.report) process.exit(1);
+  return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
-  await main();
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
 }

package/references/shared/command-shapes.md

@@ -0,0 +1,22 @@
+### Command shapes — the promptless bar for instructed reads & probes
+
+When a mode doc tells you to read a file or probe project state WITHOUT prescribing the exact
+command (a recon read, the version-stamp read, any "check X" instruction), the shape is yours —
+and improvised shapes are where approval prompts come from. The bar:
+
+- **Reads ride the host's file-read tool** (Read/Grep/Glob in Claude Code, or your agent's
+  equivalent) whenever one exists — a file-read tool never fires a shell approval prompt.
+- **No file-read tool → ONE plain undecorated command per probe:** no `;`/`&&` compounds, no
+  redirects, no pipes, no command substitution — one probe per invocation. This applies the
+  deployed agent-rules lens’s «plain pipeline per call» discipline here as a stricter
+  single-command shape. Any decorated or chained form falls outside this contract’s baseline
+  guarantee; behavior is then host/config-dependent — it may prompt, an opt-in read-lane may
+  auto-approve a vetted compound, and command substitution may even slip past a prefix allow
+  rule. The plain single-command shape is the only shell fallback this contract treats as
+  promptless by construction.
+- **Improvised file writes ride the host's file-edit tools** (Write/Edit or the equivalent) —
+  never an ad-hoc heredoc or shell-redirect write.
+
+**Scope — improvised shapes only.** The executable commands a mode doc itself prescribes (the
+`node …/tools/…` dispatch lines, `--apply` lanes, install/symlink steps) are OUTSIDE this
+contract: run them exactly as prescribed, as plain single invocations.

package/references/shared/composition-handoff.md

@@ -43,7 +43,7 @@ duplicate anchor → **STOP with an error**, never edit (the file is left byte-f
 exceed the 100-line cap, the engine is too old to ship its fragment, or (autonomy only) its anchor
 (the orchestration pair) is absent: every prior pointer still lands and the upgrade continues.
 
-**Agent-rules lens refresh (runs in BOTH paths).** Its precondition is its own target file — run it
+**Agent-rules lens + Communication refresh (runs in BOTH paths).** Its precondition is its own target file — run it
 only after `<project>/docs/ai/agent_rules.md` exists: after the substrate deploy in the
 **delegated** path, after the fallback-template copy in the **kit** path (never anchored to the
 `AGENTS.md` step above). ONE command:
@@ -53,4 +53,9 @@ prior canonical body is refreshed from the installed engine; a current seed repo
 current* (zero-diff). Relay its outcome in plain language (*refreshed* / *already current* /
 *custom edit preserved + note* / *file absent — skipped* / *engine too old — skipped* / *over the
 line cap — refused*); a fully absent/invalid engine is the same loud STOP + one-line install
-command as the pointer reconcile.
+command as the pointer reconcile. The same invocation also reconciles the **Communication
+(user-facing messages)** section from the kit's own bundled template canon (no engine involved):
+a body matching the current canon is reported *already current*; a body matching a known prior
+is refreshed; a custom body is preserved + noted; an absent section is a stated note (never an
+insert); an over-cap refresh is refused; and an unreadable bundled template canon is its own
+loud STOP naming the kit reinstall command.

package/references/templates/agent_rules.md

@@ -63,7 +63,16 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
-### 2.5. Planning, review & process-fidelity invariants
+### 2.5. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **Plain language.** User-facing narration is short, clear, plain words of the dialogue language; when the dialogue language is not English, transliterated English jargon is banned — an English term survives only as the NAME of a thing (a flag / command / file / test), glossed in plain words when helpful; plain English stays plain for English-dialogue users.
+- **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
+- **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
+- **No condescension, no filler.** Own a miss plainly and fix it in the same message.
+- **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
+- **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.
+
+### 2.6. Planning, review & process-fidelity invariants
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.

package/tools/autonomy-doctor.mjs

@@ -254,7 +254,7 @@ const renderDiagnosis = ({ plan, probeResult, log }) => {
   }
 };
 
-// The untrusted degrade every lane runs FIRST (codex R1): while any sandbox binary resolves only
+// The untrusted degrade every lane runs FIRST: while any sandbox binary resolves only
 // outside the trusted dirs, no offer, no consent invitation, and no privileged path may proceed —
 // an install cannot make such a host verify-ready.
 const refuseUntrusted = ({ plan, log }) => {

package/tools/bridge-settings-read.mjs

@@ -148,6 +148,17 @@ export const duplicateKeys = (parsed) => [...parsed.byKey.entries()].filter(([,
 
 // ── effective-value resolution (env > file > built-in default) ────────────────────────
 
+// The env keys the wrappers resolver-validate AFTER precedence (AD-061 aw_effective_timeout) —
+// exactly these mirror the wrapper's invalid-env → warn + built-in-default lane.
+const RESOLVER_VALIDATED_ENV = new Set(['CODEX_HARD_TIMEOUT', 'AGY_HARD_TIMEOUT']);
+// A control byte (C0 range + DEL) in a screened knob makes the wrapper EXIT 2 pre-spend — the
+// advisor must report that refusal, never a benign fallback, and never echo the raw byte into
+// the report (a newline could otherwise forge a `review posture:`/status line). safeShow escapes
+// every note value: JSON.stringify handles C0, an explicit pass handles DEL (JSON leaves it raw).
+const hasControlByte = (s) => /[\x01-\x1f\x7f]/.test(s);
+const safeShow = (s) => JSON.stringify(s).slice(1, -1).replace(/\x7f/g, '\\u007f');
+const REFUSED = (key, v) => ({ value: null, source: 'default', note: `env value "${safeShow(v)}" carries control bytes for ${key} — the wrapper REFUSES the run pre-spend` });
+
 // The effective value of one knob + where it comes from. Fact-only; never a model claim.
 export const effectiveOf = (entry, parsed, getenv) => {
   const key = entry.key;
@@ -159,13 +170,22 @@ export const effectiveOf = (entry, parsed, getenv) => {
     // add-dir knobs fall to their real built-in default). Report the manifest default (null ⇒ "wrapper
     // built-in applies"), not a misleading null-for-everything.
     if (v === '') return { value: entry.default, source: 'default', note: 'the env KEY= suppresses the file override — the wrapper built-in applies' };
+    // A control byte in a SCREENED knob (the tier + the resolver-validated timeouts) is a pre-spend
+    // refusal in the wrapper — report it as such (the default value is inert; the run never happens).
+    if (hasControlByte(v) && (entry.kind === 'enum' || RESOLVER_VALIDATED_ENV.has(key))) {
+      return REFUSED(key, v);
+    }
     // Mirror the wrapper: an ENUM knob (the service tier) validates its ENV value too — codex accepts
     // any `-c service_tier` string silently, so the wrapper drops an unsupported one to the built-in
-    // default (codex-exec.sh:188). A non-enum env value is the operator's documented RAW override (e.g.
-    // a timeout(1) duration like `2h` the wrapper passes straight through) — shown as-is (D3 scopes
-    // typed validation to FILE lines; the Phase-1 council refuted validating non-enum env usage).
+    // default (codex-exec.sh:188). The TIMEOUT knobs are resolver-validated env INCLUDED since AD-061
+    // (aw_effective_timeout closed the old env bypass, with a 7-digit integer-part overflow bound) —
+    // the advisor must never display a dead override as active. Every OTHER non-enum env value stays
+    // the operator's RAW override (the wrappers run no resolver on it), shown as-is.
     if (entry.kind === 'enum' && !settingValueValid(entry, v)) {
-      return { value: entry.default, source: 'default', note: `env value "${v}" is not a supported ${key} — the wrapper runs the built-in default` };
+      return { value: entry.default, source: 'default', note: `env value "${safeShow(v)}" is not a supported ${key} — the wrapper runs the built-in default` };
+    }
+    if (RESOLVER_VALIDATED_ENV.has(key) && (!settingValueValid(entry, v) || v.match(/^\d*/)[0].length > 7)) {
+      return { value: entry.default, source: 'default', note: `env value "${safeShow(v)}" is invalid for ${key} — the wrapper falls back to the built-in default` };
     }
     return { value: v, source: 'env' };
   }
@@ -173,7 +193,7 @@ export const effectiveOf = (entry, parsed, getenv) => {
   if (fileEntries && fileEntries.length) {
     const v = fileEntries[fileEntries.length - 1].value; // last occurrence wins
     if (settingValueValid(entry, v)) return { value: v, source: 'file' };
-    return { value: entry.default, source: 'default', note: `file value "${v}" is invalid — falls back to the built-in default` };
+    return { value: entry.default, source: 'default', note: `file value "${safeShow(v)}" is invalid — falls back to the built-in default` };
   }
   return { value: entry.default, source: 'default' };
 };

package/tools/changed-surface.mjs

@@ -37,7 +37,7 @@ export const classifyChangedPath = (rel) => {
 
 // Strip the quotes and decode escapes BYTE-wise (octal escapes are UTF-8 bytes) — an unparsed
 // quoted path compares unequal to its classifier/testId form and would silently escape the
-// coverage/cap surface (agy R5, AD-047).
+// coverage/cap surface (AD-047).
 const CQUOTE_SIMPLE = { n: 10, t: 9, r: 13, f: 12, v: 11, b: 8, a: 7, '"': 34, '\\': 92 };
 export const unquoteDiffPath = (p) => {
   if (!(p.length >= 2 && p.startsWith('"') && p.endsWith('"'))) return p;
@@ -47,7 +47,7 @@ export const unquoteDiffPath = (p) => {
     const c = inner[i];
     if (c !== '\\') {
       // Consume a full CODE POINT — 16-bit-unit iteration would split a surrogate pair (an
-      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes (agy R6).
+      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes.
       const ch = String.fromCodePoint(inner.codePointAt(i));
       for (const b of Buffer.from(ch, 'utf8')) bytes.push(b);
       i += ch.length - 1;
@@ -89,7 +89,7 @@ export const parseUnifiedDiff = (diffText) => {
     }
     if (inHeader && line.startsWith('--- ')) continue;
     if (inHeader && line.startsWith('+++ ')) {
-      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes (agy R6)
+      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes
       current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
       inHeader = false;
       continue;
@@ -114,7 +114,7 @@ export const parseUnifiedDiff = (diffText) => {
 // ── the changed surface (git-driven; the ONE computation both consumers read) ─────────────────────
 
 // The one diff-invocation shape every surface pass uses. The a/ b/ prefixes are pinned EXPLICITLY
-// (agy R6): a user's global diff.noprefix=true would otherwise drop them and the parsers would eat
+// A user's global diff.noprefix=true would otherwise drop them and the parsers would eat
 // a real directory named "a" — user git config must never bend the parse.
 export const DIFF_FLAGS = ['--unified=0', '--no-color', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/'];
 
@@ -134,7 +134,7 @@ export const readFileSafe = (path) => {
 };
 // A changed LEAF is read only if it is a REGULAR file. lstat (no-follow): a symlinked or non-regular
 // leaf must NEVER be read/followed — following it could read outside the work tree or HANG on a
-// FIFO/device (codex R2, AD-046). A non-regular leaf fails closed (routed to `unsupported`).
+// FIFO/device (AD-046). A non-regular leaf fails closed (routed to `unsupported`).
 export const isRegularLeaf = (abs) => {
   try {
     return lstatSync(abs).isFile();
@@ -150,13 +150,13 @@ export const isRegularLeaf = (abs) => {
 // pure deletions cost nothing, subtractive folds stay free); an untracked file is wholly new, so all
 // its lines are "changed". `unsupportedLines` is the D4 cap's view of the SAME pass: unsupported
 // SOURCE files carry their new-side lines too (excluding them would gift a large-TS-fold bypass,
-// codex R2 / BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
+// BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
 // coverage gate still fails closed on it). excluded-test and out-of-domain never carry lines.
 export const computeChangedSurface = (root) => {
   // Unborn branch (no HEAD yet): the plain diff alone misses files STAGED for the initial commit —
   // they sit in the index, so they are neither worktree-vs-index changes nor untracked. Merge the
   // --cached diff (index vs the empty tree) with the plain one; parseUnifiedDiff unions per-file
-  // lines across concatenated diffs (codex R1).
+  // lines across concatenated diffs.
   const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
     ?? `${gitStdout(['diff', '--cached', ...DIFF_FLAGS], root) ?? ''}\n${gitStdout(['diff', ...DIFF_FLAGS], root) ?? ''}`;
   const trackedLines = parseUnifiedDiff(trackedDiff);
@@ -207,7 +207,7 @@ export const computeChangedSurface = (root) => {
 // ── the shared fail-closed positive-integer knob parser (AD-047 precedent) ───────────────────────
 
 // Zero / negative / fractional / non-numeric values are refusals by name — the parseInt(...)||default
-// idiom would silently accept bad truthy values (codex R2, AD-046). Unset → the default; set → a
+// idiom would silently accept bad truthy values (AD-046). Unset → the default; set → a
 // positive integer, exactly. `makeError` lets each caller throw its OWN typed STOP.
 export const parsePositiveIntKnob = (env, name, fallback, makeError = (m) => new Error(m)) => {
   const raw = env[name];

package/tools/commands.mjs

@@ -231,6 +231,15 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that the documented contract tokens still match the live code constants they describe — a read-only lint that fails closed on drift; --check turns it into a gate exit code.',
   },
+  {
+    // NEVER `guarded` — that kind promises dry-run-first, which these writers do not have; the
+    // honest strongest caution is `writer` with the destructive arm named in the line itself.
+    key: 'worktrees',
+    invocation: invocationOf('worktrees'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Run features in parallel git worktrees: provision an isolated sibling copy, list them, stage a finished one back onto clean main (the commit still asks in dialogue), and remove a live-verified landed one. No preview step; list is read-only; cleanup --abandon destroys unlanded work.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

package/tools/delegation.mjs

@@ -89,7 +89,7 @@ export const handoffPlan = (delegate) =>
         memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
         // The lens region runs AFTER the substrate deploy (its own precondition: the file exists)
         // — it converges a stale-memory seed to the installed engine's canon (AD-041).
-        kitWrites: ['AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens + Communication regions', 'docs/ai/.workflow-version'],
         stampsPresent: ['.memory-version', '.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',
@@ -101,7 +101,7 @@ export const handoffPlan = (delegate) =>
         // the kit reconciles them (ensure-slot + inject-because-empty) exactly like the delegate
         // path — so both paths end with FILLED slots, not inline methodology. The lens region
         // runs after the fallback-template copy of docs/ai (same reconcile, both paths — AD-041).
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens region', 'docs/ai/.workflow-version'],
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md pointer slots (methodology / orchestration / autonomy)', 'docs/ai/agent_rules.md lens + Communication regions', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/detect-backends.mjs

@@ -82,6 +82,10 @@ const RAW_BACKENDS = [
         },
         notes: [
           'nested-sandbox limit: codex-exec ships its OWN OS sandbox (bwrap workspace-write) and cannot run nested inside a harness sandbox (the FS turns read-only) — route it OUTSIDE the harness sandbox (excludedCommands / a per-run consented bypass) on the OBSERVED bwrap/EPERM failure, never a preemptive blanket',
+          'exec posture banner: ONE stderr line before dispatch states the ACTUAL run posture — exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> timeout=… — from RESOLVED post-validation values; the resume id is validated pre-spend, and control bytes in any banner field refuse pre-spend',
+          'threat model: the sidecar byte and grammar screens detect corrupted input under a trusted parent environment. A hostile parent environment — including exported shell functions or PATH substitution of core/backend commands — is outside the threat model and can substitute the backend itself. Targeted shadow-proof resolution protects banner/dispatch honesty from accidental shadowing; it is not an environment security boundary',
+          'the exec posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it is never persisted in a receipt or session sidecar',
+          'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
         ],
       },
       review: {
@@ -92,6 +96,10 @@ const RAW_BACKENDS = [
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
         receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review',
+        notes: [
+          'the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity',
+          'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
+        ],
       },
     },
     bin: 'codex',
@@ -128,6 +136,8 @@ const RAW_BACKENDS = [
         receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review",
         notes: [
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
+          'the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration agy-run hands to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity',
+          'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
         ],
       },
     },

package/tools/grounding.mjs

@@ -102,7 +102,7 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
 // Trim `payload` to `budget` bytes, tail-first, with a loud in-band marker. The budget is a HARD
 // ceiling: when it is smaller than the marker itself, the marker is truncated too (the output may
 // never exceed `budget` — a facts file over the reserved share would push the final wrapper prompt
-// past the argv ceiling; codex R1 finding). Returns { text, trimmedBytes }. Never a silent cut.
+// past the argv ceiling). Returns { text, trimmedBytes }. Never a silent cut.
 export const trimToBudget = (payload, budget) => {
   const bytes = Buffer.byteLength(payload, 'utf8');
   if (bytes <= budget) return { text: payload, trimmedBytes: 0 };
@@ -164,17 +164,17 @@ const gitLine = (args, cwd) => {
 // EXISTING in-repo file, even gitignored, is a project file — the .env clobber class). Refused:
 // tracked paths, in-repo not-ignored paths (a new untracked file would move the fingerprint),
 // every other outside-repo destination, symlink and existing non-regular leaves, and any
-// unverifiable lstat. The check runs on the REAL destination, never the lexical path (codex R1):
+// unverifiable lstat. The check runs on the REAL destination, never the lexical path:
 // the parent directory is realpath-resolved first, so a symlink can never route the write onto a
 // tracked/in-repo file. Returns { path, kind: 'temp' | 'repo-fresh' } — a repo-fresh caller MUST
-// write with the exclusive flag ('wx'), sealing the guard→write race (codex R11).
+// write with the exclusive flag ('wx'), sealing the guard→write race.
 export const assertScratchDestination = (outPath, cwd) => {
   const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
   let leaf = null;
   try {
     leaf = lstatSync(lexical);
   } catch (err) {
-    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (codex R9 — this
+    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (this
     // writer is bridge-tier auto-allowable, so an unverifiable leaf must never be written).
     if (err?.code !== 'ENOENT') {
       throw fail(1, `--out cannot inspect the destination (${outPath}: ${err?.code ?? err?.message ?? err}) — refusing to write an unverifiable leaf`);
@@ -185,7 +185,7 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
   }
   if (leaf != null && !leaf.isFile()) {
-    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file (codex R9); name a fresh or regular scratch path`);
+    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file; name a fresh or regular scratch path`);
   }
   let realParent;
   try {
@@ -194,8 +194,8 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
   }
   const full = join(realParent, basename(lexical));
-  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root (codex R8
-  // blocker): the bridge tier auto-allows this tool with an args wildcard, so "anything outside
+  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root: the bridge
+  // tier auto-allows this tool with an args wildcard, so "anything outside
   // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
   // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
   const assertTempScratch = () => {
@@ -215,7 +215,7 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (top == null || top.status !== 0) return { path: assertTempScratch().path, kind: 'temp' }; // no git tree → temp-only scratch
   const root = top.stdout.replace(/\r?\n$/, '');
   const rel = relative(root, full);
-  // Segment-safe outside test (the Issue-004 class, codex R5): an in-repo file literally named
+  // Segment-safe outside test (the Issue-004 class): an in-repo file literally named
   // `..facts` has rel `..facts` — `startsWith('..')` would misread it as outside and BYPASS the
   // tracked/ignored refusals below. Only `..` exactly or a `..${sep}`-prefixed rel is outside.
   if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { path: assertTempScratch().path, kind: 'temp' };
@@ -227,11 +227,11 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (ignored == null || ignored.status !== 0) {
     throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
   }
-  // An in-repo destination must be a FRESH file (codex R10): even a gitignored existing file is a
+  // An in-repo destination must be a FRESH file: even a gitignored existing file is a
   // project file (.env is the canonical victim) — an auto-allowable writer must never clobber one.
   // The rewritable scratch surface is the system temp; in-repo gitignored writes are create-only —
   // the CALLER must open with the exclusive flag ('wx'): the kind seals the pre-check against the
-  // guard→write race (codex R11).
+  // guard→write race.
   if (leaf != null) {
     throw fail(1, `--out refuses to OVERWRITE an existing in-repo file (${rel}) — even gitignored, it is a project file (the .env class); write rewritable scratch under $TMPDIR//tmp, or remove the file first`);
   }
@@ -328,7 +328,7 @@ export const main = (argv, ctx = {}) => {
     };
     const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
     const autonomyText = autonomy ? resolveAutonomyFacts({ cwd }) : null;
-    // --plan is CONFINED to the git work tree (codex R4): the bridge tier auto-allows this tool
+    // --plan is CONFINED to the git work tree: the bridge tier auto-allows this tool
     // with an args wildcard, so an unattended invocation could otherwise point --plan at ANY
     // readable file and ship it into the facts payload. Plans are in-repo by contract
     // (docs/plans); an outside-tree path is a loud refusal, never a silent read.
@@ -360,7 +360,7 @@ export const main = (argv, ctx = {}) => {
     if (out != null) {
       const dest = assertScratchDestination(out, cwd);
       // repo-fresh writes are EXCLUSIVE ('wx'): the create-only pre-check would otherwise race a
-      // file created between the guard and this write (codex R11); temp scratch stays rewritable.
+      // file created between the guard and this write; temp scratch stays rewritable.
       // ctx.writeFile is a TEST seam (the EEXIST race arm is not constructible without it).
       const writeFile = ctx.writeFile ?? writeFileSync;
       try {
@@ -380,7 +380,7 @@ export const main = (argv, ctx = {}) => {
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
   const r = main(process.argv.slice(2));
-  // Exact writes + a natural exit (codex R2): console.log would append a stray newline to the
+  // Exact writes + a natural exit: console.log would append a stray newline to the
   // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node
   // flushes. The payload already ends with '\n' (sliceSection normalizes); only a non-payload
   // message (help / the --out report) gains the terminating newline it lacks.