@sabaiway/agent-workflow-kit 5.0.0 → 5.2.0

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -1880,6 +1880,198 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
     }
   });
 
+  // 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-agy-${nonce}.json`);
+
+    it('a nonce-supplied grounded code dispatch mints the {backend, nonce}-named manifest carrying the captured findings + the receipt fingerprint', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'r1-d2' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'r1-d2'), 'utf8'));
+      rmSync(sb.home, { 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, 'agy');
+      assert.equal(manifest.nonce, 'r1-d2');
+      assert.equal(manifest.fingerprint, receipts[0].fingerprint, 'the manifest binds the SAME reviewed-tree fingerprint as the receipt');
+      assert.equal(manifest.findings, `${VERDICT_OUTPUT}\n`, 'findings = the captured review output VERBATIM');
+      assert.equal(receipts[0].nonce, 'r1-d2', '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, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const receipts = readReceipts(sb.repo);
+      const gitEntries = readdirSync(join(sb.repo, '.git')).filter((n) => n.startsWith('agent-workflow-finding-manifest-'));
+      rmSync(sb.home, { 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('DIFFERENT bytes at the derived name refuse loudly AND EXCLUDE the receipt append (ordering, behaviorally)', () => {
+      const sb = makeSandbox();
+      writeFileSync(manifestPath(sb.repo, 'r1-d2'), '{"schema":1,"backend":"agy","nonce":"r1-d2","fingerprint":null,"findings":"other bytes"}\n');
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'r1-d2' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = readFileSync(manifestPath(sb.repo, 'r1-d2'), 'utf8');
+      rmSync(sb.home, { 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 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, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'sym2' } }).status, 0);
+      const mPath = manifestPath(sb.repo, 'sym2');
+      const target = join(sb.repo, '.git', 'manifest-target-copy.json');
+      writeFileSync(target, readFileSync(mPath));
+      rmSync(mPath);
+      symlinkSync(target, mPath);
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'sym2' } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { 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, 'fifo2');
+      assert.equal(spawnSync('mkfifo', [mPath], { encoding: 'utf8' }).status, 0, 'mkfifo fixture');
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'fifo2' } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { 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 captured output round-trips VERBATIM into the manifest (U+FEFF preserved)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: `\uFEFFpreamble\n${VERDICT_OUTPUT}`, AW_REVIEW_NONCE: 'b2' } });
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'b2'), 'utf8'));
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.findings, `\uFEFFpreamble\n${VERDICT_OUTPUT}\n`, 'the captured output is VERBATIM — a stripped BOM would move the findingDigest');
+    });
+
+    it('an unsafe nonce refuses PRE-SPEND (exit 2, agy never runs) — a non-ASCII letter refuses under a UTF-8 locale too', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AW_REVIEW_NONCE: 'a/b' } });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.invoked, false, '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, { args: ['code', '--facts', 'a tiny fact'], env: { AW_REVIEW_NONCE: 'ré1', LC_ALL: 'en_US.UTF-8', LANG: 'en_US.UTF-8' } });
+      rmSync(utf8.home, { 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('a nonce-supplied CONTINUATION mints its manifest with fingerprint null (the receipt identity is null too)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['--continue'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'r2-c1' } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'r2-c1'), 'utf8'));
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(receipts.length, 1);
+      assert.equal(manifest.fingerprint, null, 'a continuation carries no tree identity — the manifest says so honestly');
+      assert.equal(manifest.findings, `${VERDICT_OUTPUT}\n`);
+    });
+
+    // 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 rides the AW_REVIEW_NONCE seam: manifest minted, receipt nonce-stamped (flag form ≡ env form)', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact', '--nonce', 'f2-d2'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const receipts = readReceipts(sb.repo);
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'f2-d2'), 'utf8'));
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.nonce, 'f2-d2');
+      assert.equal(receipts[0].nonce, 'f2-d2', 'the flag stamps the receipt exactly like the env form');
+    });
+
+    it('an unsafe --nonce value refuses PRE-SPEND (exit 2, agy never runs) — same grammar as the env screen', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact', '--nonce', 'a/b'] });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.invoked, false, 'the containment 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', '--facts', 'a tiny fact', '--nonce'] });
+      assert.equal(missing.status, 2);
+      assert.match(missing.stderr, /--nonce needs a value/);
+      const dup = run(sb, { args: ['code', '--facts', 'a tiny fact', '--nonce', 'n1', '--nonce', 'n2'] });
+      assert.equal(dup.status, 2);
+      assert.match(dup.stderr, /duplicate --nonce/);
+      const clash = run(sb, { args: ['code', '--facts', 'a tiny fact', '--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', '--facts', 'a tiny fact', '--nonce', 'n3'], env: { AW_REVIEW_NONCE: 'n3', AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const exists = existsSync(manifestPath(sb.repo, 'n3'));
+      rmSync(sb.home, { 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('--nonce is valid on a CONTINUATION too — the flag lane covers every seam-honoring form', () => {
+      const sb = makeSandbox();
+      const r = run(sb, { args: ['--continue', '--nonce', 'r2-c2'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const manifest = JSON.parse(readFileSync(manifestPath(sb.repo, 'r2-c2'), 'utf8'));
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(manifest.fingerprint, null, 'a continuation manifest carries no tree identity');
+    });
+
+    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', '--facts', 'a tiny fact', '--nonce', '--n1'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+      const receipts = readReceipts(sb.repo);
+      const exists = existsSync(manifestPath(sb.repo, '--n1'));
+      rmSync(sb.home, { 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', '--facts', 'a tiny fact', '--nonce', ''] });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /safe nonce grammar/);
+      assert.equal(r.invoked, false, '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', '--facts', 'a tiny fact', '--nonce', '', '--nonce', 'n2'] });
+      rmSync(sb.home, { recursive: true, force: true });
+      assert.equal(r.status, 2);
+      assert.match(r.stderr, /duplicate --nonce/);
+      assert.equal(r.invoked, false, 'the refusal fires before any CLI spend');
+    });
+  });
+
   it('a continuation receipt is fresh:false with null identity fields, and the wrapper prints the fresh-run notice', () => {
     const sb = makeSandbox();
     const r = run(sb, { args: ['--continue', '--decided', 'already folded'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
@@ -1966,6 +2158,45 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
   });
 });
 
+// MANIFEST-TMP-ORPHAN-ON-FAILURE: on a FAILURE exit of the finding-manifest mint 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.
+describe('agy-review.sh — finding-manifest failure branches name the orphan (MANIFEST-TMP-ORPHAN-ON-FAILURE)', () => {
+  const manifestPath = (repo, nonce) => join(repo, '.git', `agent-workflow-finding-manifest-agy-${nonce}.json`);
+  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.home, 'orphan-fail-preload.cjs');
+      writeFileSync(preload, failure.preload);
+      const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'orphf1', NODE_OPTIONS: `--require ${preload}` } });
+      const receipts = readReceipts(sb.repo);
+      rmSync(sb.home, { 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, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT, AW_REVIEW_NONCE: 'orphf2' } });
+    const leftovers = readdirSync(join(sb.repo, '.git')).filter((n) => n.endsWith('.tmp'));
+    rmSync(sb.home, { 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');
+  });
+});
+
 // ── bridge settings file (bridges 2.3.0) ─────────────────────────────────────────
 // ${XDG_CONFIG_HOME:-$HOME/.config}/agent-workflow/bridge-settings.conf holds KEY=VALUE
 // lines, PARSED (never sourced). Precedence: explicit env (even empty: KEY= disables the
@@ -2311,18 +2542,43 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
     assert.match(r.stderr, /control/i);
   });
 
-  it('timeout honesty: no timeout/gtimeout on PATH → timeout=uncapped, never a fabricated number', () => {
+  // The two-stage cap guarantee: the parent preflight fails closed, and the seam
+  // (AGY_REQUIRE_TIMEOUT_BIN=1) makes the CHILD's missing-binary lane refuse too — but only a
+  // child that HONORS the seam. A stale installed agy-run that never reads it could run uncapped
+  // past the parent preflight, so the parent verifies the resolved child carries the seam token
+  // and refuses loudly naming the refresh recovery otherwise.
+  it('a STALE agy-run child that does not honor the timeout seam refuses fail-closed (never a silently uncapped dispatch)', () => {
+    const sb = makeSandbox();
+    const staleDir = join(sb.home, 'stale-bin');
+    mkdirSync(staleDir, { recursive: true });
+    writeFileSync(join(staleDir, 'agy-run'), '#!/usr/bin/env bash\nprintf "FAKE_AGY_REVIEW_OUTPUT\\n### Verdict\\nSHIP\\n"\n', { mode: 0o755 });
+    const r = run(sb, {
+      args: ['code', '--facts', 'a tiny fact'],
+      env: { PATH: `${staleDir}:${sb.bin}:${farmFor(['agy-run'])}` },
+    });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 127, 'a seam-blind child is a stale bridge install — refuse, never dispatch uncapped');
+    assert.match(r.stderr, /does not honor the AGY_REQUIRE_TIMEOUT_BIN seam/);
+    assert.equal(receipts.length, 0, 'no dispatch, no receipt');
+  });
+
+  // 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 printed timeout=uncapped and
+  // ran anyway). The shadow-proof resolver discipline now surfaces as the REFUSAL, not a banner.
+  it('fails CLOSED when no timeout/gtimeout is on PATH — refuses by name, agy never runs', () => {
     const sb = makeSandbox();
     const r = run(sb, {
       args: ['code', '--facts', 'a tiny fact'],
       env: { PATH: `${sb.bin}:${farmFor(['agy', 'agy-run', 'timeout', 'gtimeout'])}` },
     });
     rmSync(sb.home, { recursive: true, force: true });
-    assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /^review posture: .* timeout=uncapped$/m);
+    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.invoked, false, 'agy must NOT be invoked when the preflight refuses');
   });
 
-  it('an EXPORTED shell function shadowing timeout never fools the banner (type -P discipline)', () => {
+  it('an EXPORTED shell function shadowing timeout never fools the preflight (type -P discipline)', () => {
     const sb = makeSandbox();
     const r = run(sb, {
       args: ['code', '--facts', 'a tiny fact'],
@@ -2332,8 +2588,8 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
       },
     });
     rmSync(sb.home, { recursive: true, force: true });
-    assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /^review posture: .* timeout=uncapped$/m, 'a shell function is not a capping binary');
+    assert.equal(r.status, 127, 'a shell function is not a capping binary — the preflight still refuses');
+    assert.match(r.stderr, /hard-timeout preflight fails CLOSED/);
   });
 
   it('an EXPORTED `type` function faking a path never fools the resolver (builtin type discipline)', () => {
@@ -2346,8 +2602,8 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
       },
     });
     rmSync(sb.home, { recursive: true, force: true });
-    assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /^review posture: .* timeout=uncapped$/m, 'builtin type bypasses an exported type function');
+    assert.equal(r.status, 127, 'builtin type bypasses an exported type function — the preflight still refuses');
+    assert.match(r.stderr, /hard-timeout preflight fails CLOSED/);
   });
 
   it('a DEL (0x7f) byte in a banner field refuses pre-spend like the C0 range', () => {

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -183,8 +183,9 @@ aw_apply_settings
 
 # --- Effective-timeout resolver (D5 banner honesty; AD-061) --------------------
 # ONE rule, both bridges: the posture banner prints EXACTLY the duration handed to timeout(1) —
-# an integer-seconds value rendered with the `s` suffix, a duration string verbatim — and
-# `timeout=uncapped` when no timeout/gtimeout binary can cap the run; never a fabricated number.
+# an integer-seconds value rendered with the `s` suffix, a duration string verbatim; without a
+# capping binary the EXEC wrappers print `timeout=uncapped` and run, while the REVIEW wrappers
+# refuse pre-spend (fail-closed preflight) — never a fabricated number.
 # The EFFECTIVE value (env included — closing the aw_settings_valid env bypass) is validated by
 # the same per-key rule as the settings file, plus a 7-digit integer-part bound (overflow); an
 # invalid value warns + falls back to the built-in default — a typo never silently masquerades
@@ -331,6 +332,15 @@ agy_cmd=(agy "${model_flag[@]}" --print-timeout "$AGY_TIMEOUT" "${passthrough[@]
 timeout_bin="$(aw_resolve_timeout_bin)"
 
 if [[ -z "$timeout_bin" ]]; then
+  # The review child seam (flow-orchestration Phase 4): agy-review fails CLOSED at its own
+  # preflight and exports this seam so a delete-between race can never void the cap through the
+  # child's re-resolution; the legacy warn+uncapped lane stays for direct agy-run use.
+  if [[ "${AGY_REQUIRE_TIMEOUT_BIN:-}" == "1" ]]; then
+    echo "error: no 'timeout'/'gtimeout' binary on PATH — the hard-timeout preflight fails CLOSED:" >&2
+    echo "       the invoking review wrapper requires a capped run (AGY_REQUIRE_TIMEOUT_BIN=1)." >&2
+    echo "       Install coreutils (timeout; on macOS: brew install coreutils), then re-run." >&2
+    exit 127
+  fi
   echo "warning: no 'timeout'/'gtimeout' on PATH — running agy WITHOUT a hard wall-clock cap" >&2
   echo "         (install coreutils to enable AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT)." >&2
   exec "${agy_cmd[@]}"

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -70,6 +70,24 @@ describe('agy.sh — hard wall-clock cap (timeout(1))', { concurrency: true }, (
     assert.equal(r.status, 3, 'a genuine agy failure code must pass through');
     assert.doesNotMatch(r.stderr, /exceeded the hard cap/, 'must not mislabel a non-timeout failure');
   });
+
+  // The review child seam (flow-orchestration Phase 4): agy-review fails CLOSED at ITS preflight,
+  // but this child re-resolves the binary — the seam closes the delete-between window; the legacy
+  // warn+uncapped lane stays for direct agy-run use.
+  it('AGY_REQUIRE_TIMEOUT_BIN=1 fails CLOSED without a capping binary; the legacy lane stays without the seam', async () => {
+    const home = makeSandbox('#!/usr/bin/env bash\necho "OK reply"\nexit 0\n');
+    const farm = makePathWithout(FARM_ROOT, ['agy', 'timeout', 'gtimeout']);
+    const path = `${join(home, '.local', 'bin')}:${farm}`;
+    const sealed = await runWrapperAsync(home, { PATH: path, AGY_MODEL: '', AGY_REQUIRE_TIMEOUT_BIN: '1' });
+    assert.equal(sealed.status, 127, 'the seam turns the uncapped lane into a refusal');
+    assert.match(sealed.stderr, /fails CLOSED/);
+    assert.doesNotMatch(sealed.stdout, /OK reply/, 'agy never runs under the sealed lane');
+    const legacy = await runWrapperAsync(home, { PATH: path, AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(legacy.status, 0, 'without the seam the legacy warn+uncapped lane is unchanged');
+    assert.match(legacy.stderr, /WITHOUT a hard wall-clock cap/);
+    assert.match(legacy.stdout, /OK reply/);
+  });
 });
 
 // A stub that records (via a SENTINEL file) whether agy was actually invoked, so a

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "provides": ["review", "probe"],
   "posture": { "model": "Gemini 3.1 Pro (High)" },
   "roles": {
@@ -15,25 +15,26 @@
       "output": "advisory",
       "contract": {
         "invocations": [
-          "agy-review code [--facts @f] [--ungrounded] [--decided @f] [--focus \"…\"] [extra focus…]",
-          "agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus \"…\"]",
-          "agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus \"…\"]"
+          "agy-review code [--facts @f] [--ungrounded] [--decided @f] [--focus \"…\"] [--nonce <n>] [extra focus…]",
+          "agy-review plan <plan-file> [--facts @f] [--decided @f] [--focus \"…\"] [--nonce <n>]",
+          "agy-review diff <diff-file> [--facts @f] [--decided @f] [--focus \"…\"] [--nonce <n>]"
         ],
         "grounding": "grounded review — agy reads NOTHING by default, an ungrounded review GUESSES: --facts @f = the verified facts to review AGAINST; --decided @f = decisions already made, do NOT re-raise (anti-circling). code mode REQUIRES a non-empty --facts payload and refuses BEFORE spending a run (escapes: --ungrounded, AGY_PROBE=1); plan/diff proceed with a loud warning",
         "flags": [
           "--facts @f — verified facts the review runs AGAINST (code mode REQUIRES a non-empty payload; plan/diff warn loudly when omitted)",
           "--ungrounded — deliberately ungrounded CODE review, a throwaway opinion (code mode only, contradicts --facts; the receipt records grounded:false and never attests)",
           "--decided @f — already-decided / already-addressed list; do NOT re-raise (anti-circling; the round-2 payload)",
-          "--focus \"…\" — extra focus (repeatable; code mode also takes trailing focus words)"
+          "--focus \"…\" — extra focus (repeatable; code mode also takes trailing focus words)",
+          "--nonce <n> — the flow dispatch nonce, the plain-argument lane onto the AW_REVIEW_NONCE seam (one seam: flag and a non-empty env must agree; a disagreeing pair refuses pre-spend)"
         ],
         "continue": [
-          "agy-review --continue [--decided @f] [--focus \"…\"]",
-          "agy-review --conversation <id> [--decided @f] [--focus \"…\"]"
+          "agy-review --continue [--decided @f] [--focus \"…\"] [--nonce <n>]",
+          "agy-review --conversation <id> [--decided @f] [--focus \"…\"] [--nonce <n>]"
         ],
-        "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; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; 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",
+        "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; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; 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); 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": [
           "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",
+          "the review posture banner appends a banner-only timeout=<duration> field — exactly the duration agy-run hands 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"
         ]
       }
@@ -58,6 +59,7 @@
         { "slot": "[--ungrounded]", "required": false, "description": "deliberately ungrounded code review — a throwaway opinion; the receipt records grounded:false and never attests" },
         { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
         { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" },
+        { "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": [
@@ -86,7 +88,8 @@
         { "slot": "<plan-file>", "required": true, "description": "the plan file under review" },
         { "slot": "[--facts @f]", "required": false, "description": "the verified facts to review AGAINST; omitting it warns loudly and records the review ungrounded" },
         { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
-        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" }
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" },
+        { "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 posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
@@ -110,7 +113,8 @@
         { "slot": "<diff-file>", "required": true, "description": "the diff file under review" },
         { "slot": "[--facts @f]", "required": false, "description": "the verified facts to review AGAINST; omitting it warns loudly and records the review ungrounded" },
         { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
-        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" }
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this review must look at (repeatable)" },
+        { "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 posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
@@ -131,7 +135,8 @@
       "invocationRefs": [{ "contractField": "continue", "index": 0 }],
       "operands": [
         { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
-        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" }
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" },
+        { "slot": "[--nonce <n>]", "required": false, "description": "the flow dispatch nonce — the plain-argument lane onto the AW_REVIEW_NONCE seam (a continuation manifest carries fingerprint null)" }
       ],
       "guardrails": [
         { "value": "--facts is rejected on a continuation — the facts are already in the conversation", "enforcement": "enforced", "source": "bin/agy-review.sh" },
@@ -149,7 +154,8 @@
       "operands": [
         { "slot": "<id>", "required": true, "description": "the conversation id of the review to resume" },
         { "slot": "[--decided @f]", "required": false, "description": "decisions already made; the reviewer must not re-raise them (anti-circling)" },
-        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" }
+        { "slot": "[--focus \"…\"]", "required": false, "description": "what this round must look at (repeatable)" },
+        { "slot": "[--nonce <n>]", "required": false, "description": "the flow dispatch nonce — the plain-argument lane onto the AW_REVIEW_NONCE seam (a continuation manifest carries fingerprint null)" }
       ],
       "guardrails": [
         { "value": "a continuation receipt is fresh:false — informational only, never a gate pass", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -100,8 +100,9 @@ What it does for you, and what YOU must supply:
 - **Posture banner — quote it verbatim.** Every review states its ACTUAL posture on ONE stderr line
   (`review posture: model=… 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 `agy-run` hands to `timeout(1)`, or
-  `uncapped` when no capping binary is on PATH) — informational, never part of the receipt posture.
+  The `timeout=` field is **banner-only** (exactly the duration `agy-run` hands to `timeout(1)`;
+  without a capping binary `agy-review` fails CLOSED pre-spend, so an uncapped review banner no
+  longer exists) — informational, never part of the receipt posture.
 
 ## Escalation policy (edits, network, git)
 

package/bridges/codex-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '3.2.0'
+  version: '3.3.0'
 ---
 
 # codex-cli-bridge
@@ -104,8 +104,9 @@ records the same `posture {model, effort, tier}` (tier `null` on the standard ti
 in a posture value refuse pre-spend in every mode. `codex-exec` states its posture the same way —
 ONE `exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id>
 timeout=…` stderr line before dispatch (the resume id validated pre-spend). The `timeout=` field
-is **banner-only** (exactly the duration handed to `timeout(1)`, or `uncapped`) — informational,
-never a receipt field. **Quote the posture banner verbatim** when labeling a dispatch.
+is **banner-only** (exactly the duration handed to `timeout(1)`; on exec `uncapped` without a
+capping binary, while `codex-review` **fails CLOSED pre-spend** there) — informational, never a
+receipt field. **Quote the posture banner verbatim** when labeling a dispatch.
 
 `codex exec` is headless: there is **no TTY**, so `approval_policy=never` — anything needing
 escalation is refused and reported, never interactively approved. The wrappers capture only codex's
@@ -126,10 +127,11 @@ defeat a policy is guarded — see [§ Models](#models-quality-first-pinned).
 |---|---|---|
 | `CODEX_MODEL` | `gpt-5.6-sol` (pinned) | model; non-default REFUSED unless `CODEX_PROBE=1` |
 | `CODEX_EFFORT` | `xhigh` (pinned) | reasoning effort; non-default REFUSED unless `CODEX_PROBE=1` |
-| `CODEX_HARD_TIMEOUT` | `3600` (exec) / `1800` (review) | hard wall-clock cap (seconds) via `timeout`/`gtimeout`; exit 124/137 ⇒ "exceeded hard cap". No `timeout` binary ⇒ loud warning + uncapped (never silent). |
+| `CODEX_HARD_TIMEOUT` | `3600` (exec) / `1800` (review) | hard wall-clock cap (seconds) via `timeout`/`gtimeout`; exit 124/137 ⇒ "exceeded hard cap". No `timeout` binary ⇒ exec warns loudly + runs uncapped; `codex-review` REFUSES pre-spend (fail-closed preflight). |
 | `CODEX_SERVICE_TIER` | unset (standard tier) | **SPEND knob**: `priority` (catalog name "Fast") = ~1.5× token speed at a **2.5× credit rate** on gpt-5.6-sol — quality-neutral (same model). codex accepts any `-c service_tier` string silently (probe-pinned 2026-07-05), so the wrapper validates: an unsupported value warns and runs standard. Env or settings file. |
 | `CODEX_SESSION_FILE` | `./.codex-last-session` | where `codex-exec` records the session id and where `--resume-last` reads it |
 | `CODEX_REVIEW_MAX_TOTAL_BYTES` | `1500000` | `codex-review code`: above this the assembled diff goes via a git-dir temp file instead of inline — never truncated |
+| `AW_REVIEW_NONCE` | unset | the flow dispatch nonce (safe grammar `[A-Za-z0-9._-]{1,64}` — anything else refuses pre-spend). `codex-review … --nonce <n>` is the plain-argument equivalent (one seam; flag and a non-empty env must agree, a disagreeing pair refuses pre-spend) — the lane for hosts whose dispatch policy has no env-prefix form. When supplied, a successful review first mints the finding MANIFEST `agent-workflow-finding-manifest-codex-<nonce>.json` beside the receipts file (atomic, no-clobber, ORDERED before the receipt append) — a failed mint EXCLUDES the receipt, so a nonce-supplied dispatch never lands a receipt without its readable manifest; nonce-less runs add no nonce field and mint nothing (the `wrapperVersion` field every receipt carries moves with each release) |
 | `CODEX_REVIEW_SCHEMA` | unset | `codex-review`: `=1` returns findings as a validated JSON object (`--output-schema`), with a raw-text fallback. Default off. |
 | `CODEX_PROBE` | unset | `=1` ⇒ throwaway-probe mode: relaxes the model/effort guard AND the tier-2 passthrough guard (echoed loudly). Never for real work. |
 
@@ -223,7 +225,8 @@ The wrappers work in any git repo where `codex` is installed and authenticated.
   restates it via `-c`; only a *raw* `codex exec resume` (bypassing the wrapper) loses the posture.
 - **Hard timeout** — a hung run is killed at `CODEX_HARD_TIMEOUT` (exec 3600s / review 1800s) and
   reported (exit 124/137); raise it for a known-healthy slow run. If neither `timeout` nor `gtimeout`
-  is on `PATH` the wrapper warns loudly and runs uncapped (never silently).
+  is on `PATH`, `codex-exec` warns loudly and runs uncapped; `codex-review` refuses pre-spend
+  (the fail-closed preflight — an uncapped review run no longer exists).
 - **Native `codex review` is out of scope** — it rejects `--ignore-user-config` (would load a personal
   `config.toml` and break the subscription/config-isolation invariant) and can't be cleanly captured;
   `codex-review` runs `codex exec` over a precomputed diff instead.

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -210,8 +210,9 @@ aw_apply_settings
 
 # --- Effective-timeout resolver (D5 banner honesty; AD-061) --------------------
 # ONE rule, both bridges: the posture banner prints EXACTLY the duration handed to timeout(1) —
-# an integer-seconds value rendered with the `s` suffix, a duration string verbatim — and
-# `timeout=uncapped` when no timeout/gtimeout binary can cap the run; never a fabricated number.
+# an integer-seconds value rendered with the `s` suffix, a duration string verbatim; without a
+# capping binary the EXEC wrappers print `timeout=uncapped` and run, while the REVIEW wrappers
+# refuse pre-spend (fail-closed preflight) — never a fabricated number.
 # The EFFECTIVE value (env included — closing the aw_settings_valid env bypass) is validated by
 # the same per-key rule as the settings file, plus a 7-digit integer-part bound (overflow); an
 # invalid value warns + falls back to the built-in default — a typo never silently masquerades