@sabaiway/agent-workflow-kit 5.1.0 → 5.3.0

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -315,14 +315,16 @@ describe('codex-review.sh — hard timeout (1.3)', { concurrency: true }, () =>
     assert.match(r.stderr, /exceeded the hard cap/);
   });
 
-  it('warns and runs uncapped when neither timeout nor gtimeout is on PATH', () => {
+  // Flow-orchestration Phase 4.2 (#26): the uncapped lane is CLOSED — without a capping binary the
+  // preflight refuses by name BEFORE any CLI run (the pre-fix wrapper warned and ran uncapped).
+  it('fails CLOSED when neither timeout nor gtimeout is on PATH — refuses by name, codex never runs', () => {
     const sb = makeSandbox();
     const path = `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`;
     const r = run(sb, { path });
     rmSync(sb.root, { recursive: true, force: true });
-    assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /WITHOUT a hard wall-clock cap/);
-    assert.match(r.stdout, /FAKE_FINAL_MESSAGE/);
+    assert.equal(r.status, 127, 'the hard-timeout preflight is a refusal, never a warned uncapped run');
+    assert.match(r.stderr, /hard-timeout preflight fails CLOSED/);
+    assert.equal(r.capStdin, '', 'codex must NOT be invoked when the preflight refuses');
   });
 });
 
@@ -524,7 +526,7 @@ describe('codex-review.sh — mode dispatch & plan validation', () => {
     const r = run(sb, { args: ['bogus'] });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 2);
-    assert.match(r.stderr, /usage: .* plan <plan-file> \| code/);
+    assert.match(r.stderr, /usage: .* plan <plan-file> \[--nonce <n>\] \| code \[--nonce <n>\]/);
   });
 
   it('no mode prints usage and STOPs (exit 2)', () => {
@@ -1035,6 +1037,275 @@ describe('codex-review.sh — review receipts (AD-038)', () => {
     assert.match(atOverride, /"backend":"codex"/);
   });
 
+  // The wrapper-minted finding manifest (flow-orchestration Phase 4.2, Decision 2/P5/P24-25):
+  // nonce-supplied dispatches mint {schema, backend, nonce, fingerprint, findings} beside the
+  // receipt, atomic + no-clobber + ORDERED — a failed mint EXCLUDES the receipt append.
+  describe('finding manifest (AW_REVIEW_NONCE)', () => {
+    const manifestPath = (repo, nonce) => join(repo, '.git', `agent-workflow-finding-manifest-codex-${nonce}.json`);
+    // Capture files ride /dev/null so repeated runs see an UNCHANGED tree (the manifest binds the
+    // fingerprint — a moved tree would legitimately change its bytes).
+    const quiet = { CODEX_FAKE_ARGV: '/dev/null', CODEX_FAKE_ENV: '/dev/null', CODEX_FAKE_STDIN: '/dev/null', CODEX_FAKE_FINAL: 'Verdict: ship' };
+
+    it('a nonce-supplied code dispatch mints the {backend, nonce}-named manifest carrying the captured findings + the receipt fingerprint', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'r1-d1' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'r1-d1'), 'utf8'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(receipts.length, 1, 'the receipt landed beside the manifest');
+      assert.deepEqual(Object.keys(manifest), ['schema', 'backend', 'nonce', 'fingerprint', 'findings'], 'the closed manifest key set, in order');
+      assert.equal(manifest.schema, 1);
+      assert.equal(manifest.backend, 'codex');
+      assert.equal(manifest.nonce, 'r1-d1');
+      assert.equal(manifest.fingerprint, receipts[0].fingerprint, 'the manifest binds the SAME reviewed-tree fingerprint as the receipt');
+      assert.equal(manifest.findings, 'Verdict: ship\n', 'findings = the captured final message VERBATIM');
+      assert.equal(receipts[0].nonce, 'r1-d1', 'a nonce-supplied receipt carries the dispatch nonce — the flow round-land matcher requires exact equality (dispatch identity end-to-end)');
+    });
+
+    it('a nonce-less invocation mints NO manifest and adds NO nonce field — the receipt field set is unchanged (Decision 2 both branches)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { ...quiet } });
+      const receipts = readReceipts(sb.repo);
+      const gitEntries = readdirSync(join(sb.repo, '.git')).filter((n) => n.startsWith('agent-workflow-finding-manifest-'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(gitEntries.length, 0, 'no nonce, no manifest');
+      assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'the receipt line field set is unchanged');
+    });
+
+    it('a byte-identical re-mint is an idempotent no-op — the second receipt still lands', () => {
+      const sb = makeSandbox();
+      assert.equal(run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'r1-d1' } }).status, 0);
+      const before = readFileSync(manifestPath(sb.repo, 'r1-d1'), 'utf8');
+      const r2 = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'r1-d1' } });
+      const receipts = readReceipts(sb.repo);
+      const after = readFileSync(manifestPath(sb.repo, 'r1-d1'), 'utf8');
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r2.status, 0, r2.stderr);
+      assert.equal(receipts.length, 2, 'both receipts landed — the idempotent manifest no-op never excludes');
+      assert.equal(after, before, 'the manifest bytes are untouched');
+    });
+
+    it('DIFFERENT bytes at the derived name refuse loudly AND EXCLUDE the receipt append (ordering, behaviorally)', () => {
+      const sb = makeSandbox();
+      writeFileSync(manifestPath(sb.repo, 'r1-d1'), '{"schema":1,"backend":"codex","nonce":"r1-d1","fingerprint":null,"findings":"other bytes"}\n');
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'r1-d1' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = readFileSync(manifestPath(sb.repo, 'r1-d1'), 'utf8');
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, 'the review itself still succeeds (the artifact lane failed loudly)');
+      assert.match(r.stderr, /DIFFERENT bytes or is not a regular file — no-clobber refuses loudly/);
+      assert.match(r.stderr, /receipt append is EXCLUDED/);
+      assert.equal(receipts.length, 0, 'a nonce-supplied dispatch never lands a receipt without its manifest');
+      assert.match(manifest, /other bytes/, 'the pre-existing manifest is never clobbered');
+    });
+
+    it('a tmp-unlink failure after a successful mint warns with the ORPHAN PATH and still appends the receipt (preload-forced; parity carries the agy twin)', () => {
+      const sb = makeSandbox();
+      const preload = join(sb.root, 'unlink-fail-preload.cjs');
+      writeFileSync(preload, "const fs = require('node:fs');\nconst real = fs.unlinkSync;\nfs.unlinkSync = (p) => { if (String(p).includes('.tmp')) { const e = new Error('EPERM'); e.code = 'EPERM'; throw e; } return real(p); };\n");
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'orph1', NODE_OPTIONS: `--require ${preload}` } });
+      const receipts = readReceipts(sb.repo);
+      const manifestExists = existsSync(manifestPath(sb.repo, 'orph1'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.match(r.stderr, /orphan left at: \S*\.tmp/, 'the warning names the exact orphan path — never a silent leftover');
+      assert.equal(manifestExists, true, 'the manifest itself was published');
+      assert.equal(receipts.length, 1, 'the pair guarantee holds — minted + receipted, the orphan stated');
+    });
+
+    // MANIFEST-TMP-ORPHAN-ON-FAILURE: on a FAILURE exit whose temp unlink ALSO fails, the error
+    // names the orphan path — parameterized over BOTH failure codes (rc 3 no-clobber, rc 1 fs
+    // failure); a failure whose temp IS removable stays orphan-silent.
+    const UNLINK_FAIL = "const fs = require('node:fs');\nconst real = fs.unlinkSync;\nfs.unlinkSync = (p) => { if (String(p).includes('.tmp')) { const e = new Error('EPERM'); e.code = 'EPERM'; throw e; } return real(p); };\n";
+    const LINK_FAIL = "const fsLink = require('node:fs');\nfsLink.linkSync = () => { const e = new Error('EPERM'); e.code = 'EPERM'; throw e; };\n";
+    for (const failure of [
+      { rc: 3, name: 'no-clobber (rc 3)', preload: UNLINK_FAIL, plant: true, errRe: /DIFFERENT bytes or is not a regular file/ },
+      { rc: 1, name: 'fs failure (rc 1)', preload: UNLINK_FAIL + LINK_FAIL, plant: false, errRe: /could not compose or write the finding manifest/ },
+    ]) {
+      it(`a FAILURE exit (${failure.name}) whose temp unlink also fails names the ORPHAN PATH in the error`, () => {
+        const sb = makeSandbox();
+        if (failure.plant) writeFileSync(manifestPath(sb.repo, 'orphf1'), 'planted different bytes\n');
+        const preload = join(sb.root, 'orphan-fail-preload.cjs');
+        writeFileSync(preload, failure.preload);
+        const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'orphf1', NODE_OPTIONS: `--require ${preload}` } });
+        const receipts = readReceipts(sb.repo);
+        rmSync(sb.root, { recursive: true, force: true });
+        assert.equal(r.status, 0, 'the review itself still succeeds (the artifact lane failed loudly)');
+        assert.match(r.stderr, failure.errRe);
+        assert.match(r.stderr, /orphan left at: \S*\.tmp/, 'the failure branch names the exact orphan path — never a silent leftover');
+        assert.equal(receipts.length, 0, 'a failed mint still EXCLUDES the receipt');
+      });
+    }
+
+    it('a FAILURE exit whose temp IS removable stays orphan-silent (no leftover, no orphan line)', () => {
+      const sb = makeSandbox();
+      writeFileSync(manifestPath(sb.repo, 'orphf2'), 'planted different bytes\n');
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'orphf2' } });
+      const leftovers = readdirSync(join(sb.repo, '.git')).filter((n) => n.endsWith('.tmp'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, 'the review itself still succeeds (the artifact lane failed loudly)');
+      assert.match(r.stderr, /DIFFERENT bytes or is not a regular file/);
+      assert.doesNotMatch(r.stderr, /orphan left at:/, 'a removed temp is not an orphan — the line would train readers to ignore it');
+      assert.deepEqual(leftovers, [], 'the temp really was removed');
+    });
+
+    it('a SYMLINK at the derived manifest path refuses and EXCLUDES the receipt — even when its target is byte-identical', () => {
+      const sb = makeSandbox();
+      assert.equal(run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'sym1' } }).status, 0);
+      const mPath = manifestPath(sb.repo, 'sym1');
+      const target = join(sb.repo, '.git', 'manifest-target-copy.json');
+      writeFileSync(target, readFileSync(mPath));
+      rmSync(mPath);
+      symlinkSync(target, mPath);
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'sym1' } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, 'the review itself still succeeds (the artifact lane failed loudly)');
+      assert.match(r.stderr, /receipt append is EXCLUDED/);
+      assert.equal(receipts.length, 1, 'the second receipt is EXCLUDED — a symlinked manifest is never read through as the idempotent no-op');
+    });
+
+    it('a FIFO at the derived manifest path refuses fast and EXCLUDES the receipt (O_NONBLOCK — no hang; fix characterization)', () => {
+      const sb = makeSandbox();
+      const mPath = manifestPath(sb.repo, 'fifo1');
+      assert.equal(spawnSync('mkfifo', [mPath], { encoding: 'utf8' }).status, 0, 'mkfifo fixture');
+      const r = run(sb, { env: { ...quiet, AW_REVIEW_NONCE: 'fifo1' } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.match(r.stderr, /receipt append is EXCLUDED/);
+      assert.equal(receipts.length, 0, 'a FIFO manifest is never read (fstat-first) and the receipt is excluded');
+    });
+
+    it('a BOM-prefixed findings payload round-trips VERBATIM into the manifest (U+FEFF preserved)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { ...quiet, CODEX_FAKE_FINAL: '\uFEFFFinding A\nVerdict: ship', AW_REVIEW_NONCE: 'b1' } });
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'b1'), 'utf8'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.findings, '\uFEFFFinding A\nVerdict: ship\n', 'the captured findings are VERBATIM — a stripped BOM would move the findingDigest');
+    });
+
+    it('an unsafe nonce refuses PRE-SPEND (exit 2, codex never runs) — a non-ASCII letter refuses under a UTF-8 locale too', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { AW_REVIEW_NONCE: '../escape' } });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.capStdin, '', 'the containment refusal fires before any CLI spend');
+      // The grammar ENUMERATES the ASCII set (no ranges): a locale-collated [A-Za-z] could admit a
+      // non-ASCII letter the kit's JS reader then refuses, breaking correlation after a paid run.
+      const utf8 = makeSandbox();
+      const r2 = run(utf8, { env: { AW_REVIEW_NONCE: 'ré1', LC_ALL: 'en_US.UTF-8', LANG: 'en_US.UTF-8' } });
+      rmSync(utf8.root, { recursive: true, force: true });
+      assert.equal(r2.status, 2, 'a non-ASCII nonce letter refuses whatever the locale collation says');
+      assert.match(r2.stderr, /safe nonce grammar/);
+    });
+
+    it('plan mode with a nonce mints the manifest too (fingerprint = the artifact sha256)', () => {
+      const sb = makeSandbox();
+      const planBytes = readFileSync(join(sb.repo, 'plan.md'));
+      const r = run(sb, { args: ['plan', 'plan.md'], env: { CODEX_FAKE_FINAL: 'Verdict: ship', AW_REVIEW_NONCE: 'p1' } });
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'p1'), 'utf8'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.fingerprint, sha256Hex(planBytes));
+    });
+
+    it('a FAILED review (no verdict) mints neither receipt nor manifest — the pair rides success only', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { env: { CODEX_FAKE_FINAL: 'no verdict here', AW_REVIEW_NONCE: 'r9' } });
+      const receipts = readReceipts(sb.repo);
+      const exists = existsSync(manifestPath(sb.repo, 'r9'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.notEqual(r.status, 0);
+      assert.equal(receipts.length, 0);
+      assert.equal(exists, false, 'no success, no manifest');
+    });
+
+    // The --nonce flag (FLOW-NONCE-DISPATCH-LANE): the plain-argument lane onto the SAME seam —
+    // for hosts whose dispatch policy has no env-prefix form.
+    it('--nonce in code mode rides the AW_REVIEW_NONCE seam: manifest minted, receipt nonce-stamped, focus words intact', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--nonce', 'f1-d1', 'look', 'harder'], env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'f1-d1'), 'utf8'));
+      const stdin = r.capStdin;
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.nonce, 'f1-d1');
+      assert.equal(receipts[0].nonce, 'f1-d1', 'the flag stamps the receipt exactly like the env form');
+      assert.match(stdin, /Extra focus: look harder/, 'the flag pair is stripped — trailing focus words still ride');
+    });
+
+    it('--nonce in plan mode mints the manifest (the consult-dispatch lane) — the flag never trips the no-extra-args refusal', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['plan', 'plan.md', '--nonce', 'p2'], env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+      const exists = existsSync(manifestPath(sb.repo, 'p2'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(exists, true);
+    });
+
+    it('an unsafe --nonce value refuses PRE-SPEND (exit 2, codex never runs) — same grammar as the env screen', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--nonce', 'a/b'] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.capStdin, '', 'the refusal fires before any CLI spend');
+    });
+
+    it('a missing value, a duplicate flag, and a disagreeing env+flag pair each refuse (exit 2); an agreeing pair proceeds', () => {
+      const sb = makeSandbox();
+      const missing = run(sb, { args: ['code', '--nonce'] });
+      assert.equal(missing.status, 2);
+      assert.match(missing.stderr, /--nonce needs a value/);
+      const dup = run(sb, { args: ['code', '--nonce', 'n1', '--nonce', 'n2'] });
+      assert.equal(dup.status, 2);
+      assert.match(dup.stderr, /duplicate --nonce/);
+      const clash = run(sb, { args: ['code', '--nonce', 'n1'], env: { AW_REVIEW_NONCE: 'n2' } });
+      assert.equal(clash.status, 2);
+      assert.match(clash.stderr, /disagrees with the AW_REVIEW_NONCE environment value/);
+      const agree = run(sb, { args: ['code', '--nonce', 'n3'], env: { AW_REVIEW_NONCE: 'n3', CODEX_FAKE_FINAL: 'Verdict: ship' } });
+      const exists = existsSync(manifestPath(sb.repo, 'n3'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(agree.status, 0, agree.stderr);
+      assert.equal(exists, true, 'an agreeing pair is ONE seam value — the dispatch proceeds');
+    });
+
+    it('a grammar-valid leading-dash --nonce value is ACCEPTED — the flag lane spans the whole declared grammar', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--nonce', '--n1'], env: { CODEX_FAKE_FINAL: 'Verdict: ship' } });
+      const receipts = readReceipts(sb.repo);
+      const exists = existsSync(manifestPath(sb.repo, '--n1'));
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(exists, true, 'the {backend, nonce}-named manifest lands under the leading-dash nonce');
+      assert.equal(receipts[0].nonce, '--n1', 'the receipt carries the exact grammar-valid value — flag lane ≡ env lane');
+    });
+
+    it('an EMPTY --nonce value refuses pre-spend under the grammar screen (presence is tracked separately from the value)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--nonce', ''] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.capStdin, '', 'the refusal fires before any CLI spend');
+    });
+
+    it('a duplicate --nonce after an EMPTY first value still refuses as a duplicate — an empty value never erases presence', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--nonce', '', '--nonce', 'n2'] });
+      rmSync(sb.root, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /duplicate --nonce/);
+      assert.equal(r.capStdin, '', 'the refusal fires before any CLI spend');
+    });
+  });
+
   it('a receipt write failure warns loudly but never fails the review (fail-safe direction)', () => {
     const sb = makeSandbox();
     const r = run(sb, {

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "posture": { "model": "gpt-5.6-sol", "effort": "xhigh", "tier": null },
   "provides": ["execute", "review"],
   "roles": {
@@ -31,7 +31,8 @@
           "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"
+          "quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts",
+          "every-run nested-sandbox scan (DUAL policy, deliberately two different rules): the scan runs on EVERY completed run, not only a failed one, because a run that SURVIVES the nested-sandbox failure exits 0 with an ungrounded answer and nothing said so. Failed run (rc != 0): the existing loose whole-trace combination rule prints the recovery hint. Successful run (rc == 0): a warning fires ONLY on precise per-item evidence — both a sandbox-mechanism token AND a permission/read-only failure token inside the aggregated_output of ONE command_execution item whose failure is PROVEN (a nonzero exit_code, or the serialized status \"failed\"); a null exit_code is never failure by itself, tokens split across two items never fire, and a successful command's output never fires. The answer is printed FIRST on stdout, then the warning on stderr. HONEST RESIDUAL: the exit status does NOT change on that lane (a distinct nonzero exit would give a heuristic scan DENY polarity, refusing real work whenever the scan over-warns), so an orchestrator keying on exit status alone can still bank an ungrounded answer — the stderr warning is the signal"
         ]
       }
     },
@@ -42,14 +43,14 @@
       "output": "advisory",
       "contract": {
         "invocations": [
-          "codex-review plan <plan-file>",
-          "codex-review code [extra focus...]"
+          "codex-review plan <plan-file> [--nonce <n>]",
+          "codex-review code [--nonce <n>] [extra focus...]"
         ],
         "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",
+        "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); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); 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",
+          "the review posture banner appends a banner-only timeout=<duration> field — exactly the duration handed to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field 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"
         ]
       }
@@ -130,7 +131,8 @@
       "whenNotTo": ["a working-tree change set — that is review.code"],
       "invocationRefs": [{ "contractField": "invocations", "index": 0 }],
       "operands": [
-        { "slot": "<plan-file>", "required": true, "description": "the plan file under review" }
+        { "slot": "<plan-file>", "required": true, "description": "the plan file under review" },
+        { "slot": "[--nonce <n>]", "required": false, "description": "the flow dispatch nonce — the plain-argument lane onto the AW_REVIEW_NONCE seam (round-open prints the value; flag and a non-empty env must agree)" }
       ],
       "guardrails": [
         { "value": "read-only sandbox — codex cannot edit, create or delete a file", "enforcement": "enforced", "source": "bin/codex-review.sh" },
@@ -152,6 +154,7 @@
       "whenNotTo": ["a clean tree — the wrapper exits before spending a run"],
       "invocationRefs": [{ "contractField": "invocations", "index": 1 }],
       "operands": [
+        { "slot": "[--nonce <n>]", "required": false, "description": "the flow dispatch nonce — the plain-argument lane onto the AW_REVIEW_NONCE seam (round-open prints the value; flag and a non-empty env must agree)" },
         { "slot": "[extra focus...]", "required": false, "description": "extra focus words appended to the review directive" }
       ],
       "guardrails": [

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -35,8 +35,8 @@ Every dispatch states its ACTUAL posture on ONE stderr line: `codex-exec` emits
 `review posture: model=… effort=… tier=… timeout=…`. When you label a dispatch for a user or a
 record, **quote the posture banner verbatim** — the banner is the machine-stated posture; a prose
 re-type drifts. The `timeout=` field is **banner-only** (exactly the duration handed to
-`timeout(1)`, or `uncapped` when no capping binary is on PATH) — informational, never part of a
-receipt or the banner↔receipt parity.
+`timeout(1)`; on exec `uncapped` when no capping binary is on PATH, while `codex-review` fails
+CLOSED pre-spend there) — informational, never part of a receipt or the banner↔receipt parity.
 
 ## Exec vs review
 
@@ -75,9 +75,11 @@ codex-review code "focus on the reducer and its tests"
 `codex-exec` prepends an **orchestrator execution contract**: work in the current tree, never
 git-write, *obey* the already-merged `AGENTS.md` (Hard Constraints + declared gates), self-review the
 diff (incl. untracked files), run the project's declared gates (STOP if none are declared), don't
-commit, report blockers. It captures only codex's **final message** (`-o`; the JSON event stream +
-reasoning are discarded to a trace) and, on a **non-resume** run, records the session id to
-`${CODEX_SESSION_FILE:-./.codex-last-session}`.
+commit, report blockers. It captures only codex's **final message** (`-o`) and, on a **non-resume**
+run, records the session id to `${CODEX_SESSION_FILE:-./.codex-last-session}`. The JSON event stream
++ reasoning go to a run trace that is **read before it is discarded** — fresh runs and resumes share
+ONE capture posture, and the wrapper scans that trace on every completed run for a nested-sandbox
+failure the run SURVIVED (see [`sandbox-and-flags.md`](sandbox-and-flags.md#clean-output-capture)).
 
 ## Resume — iterate without re-sending context
 

package/bridges/codex-cli-bridge/references/sandbox-and-flags.md

@@ -39,14 +39,27 @@ and passes no separate network flag — the `sandbox_workspace_write.*` config (
 
 ### Clean output capture
 
-`-o`/`--output-last-message` writes ONLY codex's final message; `--json` streams the structured event
-stream (incl. `thread.started`, which carries the session id) to a discarded trace; `--color never` +
+**ONE capture posture, fresh runs and resumes alike.** `-o`/`--output-last-message` writes ONLY
+codex's final message; `--json` streams the structured event stream (incl. `thread.started`, which
+carries the session id) into the run trace, with stderr merged into it; `--color never` +
 `-c hide_agent_reasoning=true` + `-c model_reasoning_summary=none` strip colour and chain-of-thought.
-Net effect: the wrapper prints just the final answer. **Reasoning still runs at `xhigh`** — quality is
-unchanged; only the *noise* is dropped. On success `codex-exec` extracts the session id from the trace
-and records it to `${CODEX_SESSION_FILE:-./.codex-last-session}` (so `--resume-last` can find it) and
-echoes `session: <id>` to stderr. On a missing/empty final-message file it falls back to the trace tail
-(loud, never silent).
+`codex exec resume` accepts `-o` and `--json` too (live-probed on codex-cli 0.147.0), so the resume
+lane is no longer the odd one out — it used to print its final message straight to stdout with the
+event stream nowhere, which left the very mode a nested-sandbox incident fired on with no evidence
+surface at all. Net effect: the wrapper prints just the final answer. **Reasoning still runs at
+`xhigh`** — quality is unchanged; only the *noise* is dropped. On success `codex-exec` extracts the
+session id from the trace and records it to `${CODEX_SESSION_FILE:-./.codex-last-session}` (so
+`--resume-last` can find it) and echoes `session: <id>` to stderr. On a missing/empty final-message
+file it falls back to the trace tail (loud, never silent).
+
+The trace is **read before it is discarded**, on every completed run. A `command_execution` item in
+the `--json` stream carries `{command, aggregated_output, exit_code, status}`, and `aggregated_output`
+is that tool call's combined stdout+stderr — exactly where an absorbed `bwrap` failure lands. The
+scan is line-oriented and tolerant of the mixed stream the merge produces: a line that is not a
+well-formed item is simply not evidence, never a parse error. See the dual policy in
+[`../capability.json`](../capability.json) `roles.execute.contract.notes` — the failed-run arm keeps
+its loose whole-trace rule, and the successful-run arm demands both tokens inside ONE item whose
+failure is proven.
 
 ## Quality-first guard (pinned model & effort)
 
@@ -134,20 +147,21 @@ the prompt fence ("do not read outside the working tree, except the precomputed-
 
 `codex exec resume` re-dispatches an existing session without re-sending context. It **rejects the
 posture flags** `-s`/`--add-dir`/`-C` and **resets** the sandbox/approval/network posture (it DOES
-accept `-c`/`-m`/`--last`/`-o`/`--json` on 0.142.3 — the wrapper just doesn't need `-o`/`--json` here).
+accept `-c`/`-m`/`--last`/`-o`/`--json`/`--color`, live-probed on codex-cli 0.147.0).
 The `codex-exec --resume`/`--resume-last` entrypoint handles the reset: it restates the entire policy
 via `-c` (`sandbox_mode=workspace-write`, `approval_policy=never`,
 `sandbox_workspace_write.network_access=false`) plus the pinned `-m`/effort and `--ignore-user-config`,
-reads the session id from the sidecar (or an argument), and captures codex's final message straight
-from stdout (no `-o` needed). Only a *raw* `codex exec resume` outside the wrapper loses the posture.
+reads the session id from the sidecar (or an argument), and applies the **same** capture posture as a
+fresh run — `-o` for the final message, `--json` + `--color never` into the trace. Only a *raw*
+`codex exec resume` outside the wrapper loses the posture.
 
 ## Hard timeout
 
 A backgrounded/hung run survives otherwise, so both wrappers wrap codex in `timeout`/`gtimeout`
 (`--kill-after=15s`): `CODEX_HARD_TIMEOUT` defaults to **3600s (exec)** / **1800s (review)**, sized for a
 slow `xhigh` run. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
-`timeout` nor `gtimeout` is on `PATH`, the wrapper **warns loudly and runs uncapped** — never a silent
-no-op.
+`timeout` nor `gtimeout` is on `PATH`, `codex-exec` **warns loudly and runs uncapped** — never a silent
+no-op — while `codex-review` **refuses pre-spend** (the fail-closed hard-timeout preflight).
 
 ## Subscription / config invariant
 

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/flow-writer.md

@@ -0,0 +1,37 @@
+### Mode: flow-writer
+
+<!-- opt-in-capability: none — the writer serves an already-armed flow (arming is set-flow's, adoption is explicit); the advisor-offer decision rides the Plan-4 dogfood/release wave -->
+
+The **explicit flow-store writer** — the answer to every `flow-check` refusal that names a mintable record class. The checker's refusals print the **exact pasteable command** this tool runs; the store's own semantic preflight (lock-serialized, validated, atomic) is the **single legality door** — the writer adds NO second validator, and an illegal transition surfaces the store's own refusal **verbatim**.
+
+Run **`node ${CLAUDE_SKILL_DIR}/tools/flow-writer.mjs <arm> …`** — the arm set (Decision 8; every record class a flow refusal names as recovery):
+
+| arm | what it records |
+|---|---|
+| `adoption <plan-file> [--label <l>] [--cycle <n>]` | a chain's FIRST record — binds the plan's frontmatter `planId` + content digest (#58); the plan file is only read |
+| `park <planId>` / `resume <planId>` / `complete <planId>` | the explicit plan-lane transitions (#59) — park is a resumable suspension, complete is the plan terminal |
+| `refresh <planId> --cause <text> --refreshed-record <digest>` | a within-step re-attestation binding an existing record (bookkeeping-delta re-attestations ride this) |
+| `re-baseline <planId>` | the disjoint-base-motion recovery — records the pre-motion base (#62) |
+| `rerun-cause --attempt <id> --cause <text>` | legalizes exactly one confirmed final-gates retry (#65) — mint it on the RETRY tree |
+| `down-mark --backend <b> --reason <r> --expires-at <ISO>` | a sticky reviewer down-mark with an explicit TTL instant |
+| `down-mark-up --backend <b> [--target <digest>]` | closes the backend's ACTIVE mark upward (auto-resolved when `--target` is omitted) |
+| `down-mark-clear --backend <b> [--target <digest>]` | clears the backend's ACTIVE mark (auto-resolved when `--target` is omitted) |
+| `degrade-justification --backend <b> [--down-mark <d>] [--degrade-digest <d>]` | binds a core degrade to a then-active down-mark (#25) — both digests resolve automatically; an explicit digest only VERIFIES the resolved authority (a foreign digest never mints), and the store's locked preflight re-refuses a mark closed in the race window |
+| `maintainer-override <planId> --backend <b> --checkpoint-approved` | the checkpoint-approved ship-over-veto record — it **prints the FULL bound set** it is about to record and **requires the explicit flag** (#38); without the flag the bound set still prints and nothing is written |
+| `consult-attestation <planId> --backend <b> --nonce <n> --proposed-fix-digest <d>` | binds a consult to a real dispatch's findings (#11/#33): `findingDigest` is **computed from the `{backend, nonce}`-named finding manifest** beside the receipts file (never hand-supplied); `proposedFixDigest` is the explicit consult-time input; refuses without an open step, or without a readable identity-matching manifest |
+| `round-open <planId> --backend <b> [--backend <b> …] [--step <stepId>] [--new-cycle] [--justification <t>]` | the round's **pre-dispatch half** (#41): mints the round record BEFORE any backend runs — per `--backend` a fresh nonce + the receipts-file byte-length watermark; stdout prints one `dispatch backend=<b> nonce=<n> watermark=<w>` line per dispatch (pass the nonce as `--nonce <n>` on the wrapper invocation — the plain-argument lane onto the `AW_REVIEW_NONCE` seam; hand the pair to `receipt-deadline`). Boundary invocations need `--step`; `--new-cycle` reopens a converged step in the NEXT cycle (the redesign valve); in-step invocations open the NEXT round — **a fingerprint move never rides a revision**. Refuses while the current round holds a pending unjustified dispatch or an undispositioned non-ship receipt (a new round would strand it permanently) |
+| `round-land <planId> [--dispose folded\|queued\|rejected --finding <quote> …]` | the round's **post-arrival half** (#42/#13/#33): revises the ONE round record in place — exactly one fresh code-artifact non-probe line of the dispatched backend **carrying the dispatch's exact nonce** (the wrapper stamps `AW_REVIEW_NONCE` into the receipt — a delayed or cross-chain answer can never cross-bind) past the watermark is the candidate, and only the canonical **ATTESTING** class binds (`receiptDigest` = its canonical digest; `findingManifestDigest` = sha256 of the manifest bytes; both **computed from the files**); a defective answer (unmarked/malformed/ungrounded/unrecognized-verdict) refuses naming its class and the justified-degrade recovery; an ambiguous newer set, a foreign-tree receipt/manifest, or a missing/malformed/symlinked/foreign-identity manifest refuses. `--dispose` appends one disposition whose `findingDigest` = sha256 of the **quoted finding**, verified a substring of a landed manifest whose **byte digest still equals the ledger's** (folded proofs must resolve: a consult-attestation in the flow store or a red-proof in the core store) |
+| `freeze <planId>` / `converged <planId>` | the step terminals, gated on **completeness + the sanctioned-move rule** (no premature terminal): every dispatch landed or **justified-degraded** at the dispatched tree (a core degrade + a mint-time-valid `degrade-justification` at the round's `{base, fingerprint}` — a bare degrade is not base-bound); every landed non-ship receipt rides a round with a non-empty disposition ledger (a form floor — semantic per-finding completeness is an honest limit); the tree sits at the last round's fingerprint or reached it through an **anchored** declared bookkeeping-delta chain + refresh (a pre-round chain never re-certifies a later move). Both walks **re-run on the locked store snapshot** at append time |
+| `unfreeze <planId> [--justification <t>]` | reopens the frozen step (in-step) or the just-converged terminal (boundary); **cap 1 per cycle** — the design's post-freeze checkpoint |
+| `internal-attestation <planId> --lens <l> … [--degraded <b> …] --model <m> [--effort <e>] [--tier <t>] --authority <a>` | the #28 internal-review attestation at the open step's round — **gated on the #68 arming predicate**: EVERY in-flight plan must be covered by an adopted chain (planId + content digest + owner); an uncovered plan refuses **naming the file**, never a relaxation |
+| `write-plan-id <plan-file> --plan-id <id>` | adds the frontmatter `planId` line — bounded to an EXISTING regular file under `docs/plans/` (never a symlink), contained-atomic, same-id idempotent, **different-id refuses** (#58) |
+
+Operand shapes: a positional operand may follow a literal `--` and a value flag accepts `--flag=<value>` — the lanes a leading-dash id or value rides; the checker's printed recoveries compose exactly these shapes. Every arm computes its **tree context** (owner, base, fingerprint; cycle/round from the chain walk) — you never hand-supply tree identity. Chain arms **refuse a foreign worktree's chain** (#57): move a chain only from the worktree that adopted it.
+
+**Round-machinery caps (enforced at the arms; the store owns transition legality):** HARD_MAX **3 rounds per {cycle, step}** and **1 post-freeze unfreeze per cycle**. Every cap refusal is **self-servable** (Decision 8 — never a human wait-state): the over-cap mint requires an explicit non-empty `--justification <text>`, echoed in the mint report — the over-cap record itself is the durable trail, and the justification surfaces at the phase's commit ask; an in-cap `--justification` refuses (an input that binds nothing is never silently dropped). `round-open` also refuses while the current round holds a pending undegraded dispatch — a new round would strand it unlandable.
+
+**Exit codes:** `0` success (incl. the `write-plan-id` idempotent no-op); `2` usage; `1` refusal (a store STOP verbatim, a derivation failure, or the missing checkpoint flag).
+
+Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
+
+**Invariants:** writer (appends to the git-common-dir flow store; `write-plan-id` writes one plan file) · never commits · never runs a subscription CLI · the store preflight is the single legality door · refusal recoveries paste back into this tool.

package/references/modes/gates.md

@@ -2,14 +2,14 @@
 
 <!-- opt-in-capability: gates-declaration -->
 
-The **generic project gate runner** — it batches the project's OWN declared verification commands into one run. The runner itself **writes nothing on a plain run, never commits, and never runs a subscription CLI**; what it EXECUTES is the project's own declaration, with the caller's privileges (trust posture: a batching convenience over commands the project already runs by hand — **not a sandbox**). **`--final`** is the ONE writing mode: it runs the FULL declared matrix as the D3(a) final verification run and mints the receipt the commit guard consumes (step 4).
+The **generic project gate runner** — it batches the project's OWN declared verification commands into one run. The runner itself **writes nothing on a plain run, never commits, and never runs a subscription CLI**; what it EXECUTES is the project's own declaration, with the caller's privileges (trust posture: a batching convenience over commands the project already runs by hand — **not a sandbox**). Two modes write state: **`--final`** runs the FULL declared matrix as the D3(a) final verification run and mints the receipt the commit guard consumes (step 4), and an ARMED **`--pre-review`** records its subset attempt in the flow store (step 3; unarmed repos byte-unchanged).
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs [--cwd <project>] [--only <id>]… [--final]`:
 
 1. **Reads `docs/ai/gates.json`** (strict JSON, hand-editable; seeded from `references/templates/gates.json`). Each gate is `{ id, title, cmd }` — `id` a unique kebab handle, `cmd` **ONE bash command line** (brace/glob expansion works; a host without bash gets a loud preflight error, exit 6 — never a silent reinterpretation under another shell). The declaration names **WHAT to check, never who executes it** — the schema has no lane/model/routing fields and rejects unknown keys loudly.
 2. **Runs each gate from the project root** and prints a per-gate **PASS/FAIL table** plus **one machine-readable summary line** as the last line (`[run-gates] status=… gates=… passed=… failed=… failed_ids=…`). A failing gate's own output is preserved **verbatim** (triage without re-running); a green gate's output is not echoed; gates after a failure still run. **Exit 0 iff all selected gates are green.**
-3. **Honest outcomes, each distinct — never a silent green:** a **missing** declaration (exit 3 — the report names the recovery: create `docs/ai/gates.json` from the template; `upgrade` re-seeds a missing one), an **empty** `gates` list (exit 4), a **malformed/invalid** declaration (exit 5, loud `path: reason`). Repeatable **`--only <id>`** re-runs a subset; an unknown id is a loud usage error (exit 2).
-4. **`--final`** — the D3(a) final verification run: it REFUSES `--only` (a subset never attests) and a declaration lacking the canonical core checks (ONE plain invocation each of the kit's OWN `review-state.mjs --check` and `coverage-check.mjs --check`, the checker declared LAST — a masked form, a compound, or a lookalike path never counts); deletes the stale git-dir lcov before the suite; exports `AW_GIT_DIR` + `AW_LCOV_FILE` to every gate cmd; records EVERY attempt (start + completed green/red) in the core-evidence store via its sole writer; and binds the receipt to { fingerprint before/after · the full declaration · per-gate results · the canonical red-proof + degrade evidence hashes · the sha of the lcov the checker actually read (exactly ONE `lcov-sha256` machine line, end-re-hashed) }. An artifact moving UNDER the run is a named `integrityFailure` — the receipt lands red. A receipt that cannot be written is its own distinct outcome (exit 8): green gates never read as success without it. `${CLAUDE_SKILL_DIR}/references/modes/commit-guard.md` consumes the receipt at commit time.
+3. **Honest outcomes, each distinct — never a silent green:** a **missing** declaration (exit 3 — the report names the recovery: create `docs/ai/gates.json` from the template; `upgrade` re-seeds a missing one), an **empty** `gates` list (exit 4), a **malformed/invalid** declaration (exit 5, loud `path: reason`). Repeatable **`--only <id>`** re-runs a subset; an unknown id is a loud usage error (exit 2). **`--pre-review`** runs the DERIVED mechanical subset (#66): the full matrix minus every gate whose cmd is a canonical kit checker invocation — derivation **matches canonical checker paths in the cmd strings** (realpath-resolved `--check` forms of review-state / commit-guard / coverage-check / flow-check, never a project-authored id), so a project abstracting a checker behind its own script declares it in `flow.pregateExclude` (an unknown id refuses loudly, exit 5). A failing subset gate gets the review-dependent diagnosis, naming the mechanical reset (a declared exclude changes the `subsetDigest`). **Under an ARMED flow (exactly one open adopted chain owned by this worktree) every subset run is RECORDED** as a `subset-attempt` via the flow store's locked append factory — the context keys `{planId, cycle, stepId, foldBatch, subsetDigest}`; index + hard-stop state are computed under the lock against the pre-run identity. **Hard stop (Decision 7/8):** the SECOND red records and exits red; past two reds every attempt needs `--diagnosis "<non-empty, byte-distinct from the prior>"` (recorded, self-servable); the THIRD red EXHAUSTS the context — further solo runs refuse, and only a recorded fresh-eyes consult verdict (a grounded bridge consult-attestation at this round context) reopens ONE further attempt. Armed-but-unrecordable (zero/several open chains, broken store) refuses loudly; a spawn failure records NO attempt; unarmed repos stay byte-unchanged. Mutually exclusive with `--only`/`--final` (exit 2); plain and `--final` runs never load the config.
+4. **`--final`** — the D3(a) final verification run: it REFUSES `--only` (a subset never attests) and a declaration lacking the canonical core checks (ONE plain invocation each of the kit's OWN `review-state.mjs --check` and `coverage-check.mjs --check`, the checker declared LAST — a masked form, a compound, or a lookalike path never counts); deletes the stale git-dir lcov before the suite; exports `AW_GIT_DIR` + `AW_LCOV_FILE` to every gate cmd; records EVERY attempt (start + completed green/red) in the core-evidence store via its sole writer; and binds the receipt to { fingerprint before/after · the full declaration · per-gate results · the canonical red-proof + degrade evidence hashes · the sha of the lcov the checker actually read (exactly ONE `lcov-sha256` machine line, end-re-hashed) · **`evidenceHashes.flow`** when a flow store exists (D10: the sha of the OWNER-SCOPED flow projection — foreign worktrees never move it, except same-fingerprint planId-less globals, which share this tree's decision context; absent store → absent field; a broken store refuses up front) }. An artifact moving UNDER the run — the flow projection included — is a named `integrityFailure`; the receipt lands red. Stated residual: the movement arm is best-effort — an append racing the receipt write is refused at commit by the guard. A receipt that cannot be written is its own distinct outcome (exit 8): green gates never read as success without it. `${CLAUDE_SKILL_DIR}/references/modes/commit-guard.md` consumes the receipt at commit time (the guard re-hashes the live projection against it — a post-final append, or the store vanishing, refuses the commit).
 
 The declaration is **seeded at bootstrap** (the template loop, `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md` step 6) and **ensured-if-missing on upgrade** from THIS kit's own template twin (`${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3) — independent of the installed memory substrate's age; an existing file is always **preserved byte-for-byte**. It is deliberately **not** a delegation-required memory asset: gates are optional, and absence is an honest runner outcome, not a deployment failure.
 
@@ -21,4 +21,4 @@ Declared gates can also be **auto-approved** (no permission prompt on a byte-exa
 
 **Consent-gated filling — the init preview, not part of the runner (D9).** The template `gates.json` is seeded EMPTY; FILLING it is a consented preview at init (`node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>`, dry-run by default — prints the derived entries and **writes NOTHING**; `--apply [--only <id>]…` appends exactly the consented entries on your explicit yes; append-only, id collisions refused). The offer derivation is **closed-world** (AD-052): only a terminating-class script NAME (test / lint / type-check / build — never dev/watch/serve, never a write-mode or release/publish/deploy variant) whose BODY is a member of the literal runner allowlist is offered — membership, never blocklist screening: the worst case is a legit command not offered, never a dangerous one offered. The offered cmd is the uniform hook-free **`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`** — `exec` runs a command, not a named script, so no pre/post hook can fire (npm/pnpm/yarn alike; never `<pm> run <name>`, which re-exposes hooks), and the Corepack env prefix blocks a hostile `packageManager` pin from fetching the PM binary before exec. npm is pinned `--offline --script-shell /bin/sh`; pnpm/yarn refuse an absent runner without network (a user-installed cache/global/PATH runner executing is user machine state — part of the disclosed residual); a family without a verified fail-closed exec contract is WITHHELD loudly. **Disclose before the yes** (the preview prints it): gates.json is a PRIVILEGED file — the wired hook auto-approves byte-exact declared commands — and a script gate runs project-controlled tooling the preview does not sandbox (safe-by-construction = the OFFER DERIVATION). At upgrade the only gates.json writer is the consented legacy migration (`${CLAUDE_SKILL_DIR}/references/modes/upgrade.md`).
 
-**Invariants:** the runner writes nothing on a plain run; `--final`'s ONE evidence write rides the core-evidence sole writer (the runner never opens the store itself) · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets · gates-init is a separate consent-per-run preview — append-only, never pre-approved by any velocity tier.
+**Invariants:** the runner writes nothing on a plain run; `--final`'s ONE evidence write rides the core-evidence sole writer (the runner never opens the store itself) · an ARMED `--pre-review`'s ONE flow write rides the flow store's locked append factory (unarmed: byte-unchanged) · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets · gates-init is a separate consent-per-run preview — append-only, never pre-approved by any velocity tier.

package/references/modes/procedures.md

@@ -11,9 +11,11 @@ The two v1 activities (canon in the **installed engine**, `references/procedures
 
 Run **`node ${CLAUDE_SKILL_DIR}/tools/procedures.mjs <activity> [--override <slot>=<recipe>]… [--json]`**. It reads the activity's steps live from the engine and prints them **verbatim**, then the **resolved effective recipe per slot** from the per-project config + the read-only backend detector:
 
-1. **Config = `docs/ai/orchestration.json`** — strict JSON, **agent-writable via `/agent-workflow-kit set-recipe` (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`) OR hand-edited** (the kit reads + validates it; `procedures`/`recipes` stay read-only — the writer is `set-recipe`). Shape: `{ "<activity>": { "<slot>": "<recipe>" } }`; all slots optional (an absent slot → its computed default, stated); an optional `"_README"` string is allowed + ignored; a reserved `"flow"` object is tolerated + carried uninterpreted when it carries the NUMERIC `"schema": 1` (the kit's accepted flow schema version — any other form or value refuses loudly). `review` accepts `solo|reviewed|council`; `execute` accepts `solo|delegated`. Seeded by `init` (a user-editable template) — see `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`.
+1. **Config = `docs/ai/orchestration.json`** — strict JSON, **agent-writable via `/agent-workflow-kit set-recipe` (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`) OR hand-edited** (the kit reads + validates it; `procedures`/`recipes` stay read-only — the writer is `set-recipe`). Shape: `{ "<activity>": { "<slot>": "<recipe>" } }`; all slots optional (an absent slot → its computed default, stated); an optional `"_README"` string is allowed + ignored; a `"flow"` object must carry the NUMERIC `"schema": 1` (the kit's accepted flow schema version) and validates against the CLOSED structural schema-1 key set (unknown flow keys and malformed per-key shapes refuse loudly; deep environment floors stay on the `set-flow` arming path). `review` accepts `solo|reviewed|council`; `execute` accepts `solo|delegated`. Seeded by `init` (a user-editable template) — see `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`.
 2. **Default resolution (config silent):** `review` → Reviewed if any review-capable backend is `ready`, else Solo (never Council by default); `execute` → Solo (Delegated is opt-in). **Degradation:** a config/computed default degrades **gracefully with a stated reason** (Council → Reviewed → Solo; Delegated → Solo); a per-run **`--override <slot>=<recipe>`** that can't be satisfied degrades **loudly** (a flagged warning, so you tell the user) — but is **still exit 0** (a valid request that gracefully degraded).
-3. **Exit codes:** `0` success; `2` usage (unknown `<activity>` / bad `--override` — a bare `--override <recipe>`, an unknown slot, an invalid recipe-for-slot, or a duplicate slot); `1` config error (malformed / schema-invalid / unreadable `orchestration.json`) **or** engine error (the installed engine is absent / invalid / **too old** to ship `references/procedures.md` — upgrade it with `npx @sabaiway/agent-workflow-engine@latest init`). A `1`/`2` failure is loud (`path: reason`), never a silent fallback. **Lagging-kit honesty:** a kit predating the `"flow"` key that reads a config carrying one fails this config load loudly (exit `1`, reddening its full gate matrix); this kit release enforces NO version floor against such a pre-flow reader — tolerate-first ordering is the only mitigation until a flow-aware release arms enforcement on the `set-flow` path.
+3. **Exit codes:** `0` success; `2` usage (unknown `<activity>` / bad `--override` — a bare `--override <recipe>`, an unknown slot, an invalid recipe-for-slot, or a duplicate slot); `1` config error (malformed / schema-invalid / unreadable `orchestration.json`) **or** engine error (the installed engine is absent / invalid / **too old** to ship `references/procedures.md` — upgrade it with `npx @sabaiway/agent-workflow-engine@latest init`). A `1`/`2` failure is loud (`path: reason`), never a silent fallback. **Lagging-kit honesty:** a kit predating the `"flow"` key that reads a config carrying one fails this config load loudly (exit `1`, reddening its full gate matrix); the `set-flow` arming path now enforces the declared `kitMinVersion` floor with a null-guarded comparison (an unparseable version never passes), while tolerate-first ordering remains the only protection for readers older than the `"flow"` key itself — no in-config floor can reach a kit that dies on the unknown key.
+
+**Flow armed-halves block (session-start read side).** When the config carries a `flow` block, the advisor also renders `Flow (schema 1) — armed halves (config · chain · bookkeeping):` — the **config half** (preset · councilRounds · kitMinVersion), the **chain half** (a light read-only probe of the flow store on the checker's fixed path: ARMED at an adoption record, UNARMED for an absent or unadopted store, fail-closed BROKEN wording for a malformed one), and the **bookkeeping half** (each declared path: declared non-excluded — the tracked-file floor verifies on the `set-flow` arming path — vs loudly DECLARED-EXCLUDED). A config with no `flow` block renders byte-identically to before and pays no store probe.
 
 **Cap-soft-skip degradation (the feature's only AUTO route).** The activity procedures are auto-discoverable only through the one-line **`workflow:methodology`** pointer (this kit + the engine carry `disable-model-invocation:true`, so NL like "write a plan" does **not** auto-load this skill). On a deployment whose methodology pointer was cap-soft-skipped — or whose pre-existing customized pointer lacks the procedures clause — the procedures are still reachable by **explicitly** invoking `/agent-workflow-kit procedures`; surface that plainly rather than treating it as a gap.