@sabaiway/agent-workflow-kit 1.48.0 → 2.0.0

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "provides": ["review", "probe"],
   "roles": {
     "review": {
@@ -28,7 +28,7 @@
           "agy-review --continue [--decided @f] [--focus \"…\"]",
           "agy-review --conversation <id> [--decided @f] [--focus \"…\"]"
         ],
-        "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 (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); 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 (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); 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"
         ]
@@ -36,6 +36,164 @@
     },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
   },
+  "modeCatalog": [
+    {
+      "key": "review.code",
+      "kind": "primary",
+      "role": "review",
+      "submode": "code",
+      "purpose": "Review the uncommitted working-tree change set against facts you supply.",
+      "whenToUse": [
+        "a finished segment heading into its review round",
+        "a second opinion on real code before the commit ask"
+      ],
+      "whenNotTo": ["a clean tree — the wrapper exits before spending a run"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 0 }],
+      "operands": [
+        { "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": "[extra focus…]", "required": false, "description": "extra focus words appended to the review directive" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "receives no ambient repo/file context by default — the wrapper passes no --add-dir", "enforcement": "enforced", "source": "bin/agy-review.sh" },
+        { "value": "an ungrounded review guesses — stale-model and partial-diff false positives", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "an ungrounded run records grounded:false and the review-state gate rejects it", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" },
+        { "value": "an oversized prompt refuses rather than truncate", "enforcement": "enforced", "condition": "unless AGY_REVIEW_ALLOW_ADDDIR=1 offloads it to a private --add-dir staging dir", "source": "capability.json settings.AGY_REVIEW_ALLOW_ADDDIR" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.plan",
+      "kind": "primary",
+      "role": "review",
+      "submode": "plan",
+      "purpose": "Critique an implementation plan before any of its code exists.",
+      "whenToUse": [
+        "a plan draft heading into its review council",
+        "checking whether a cold executor could really run the plan"
+      ],
+      "whenNotTo": ["a working-tree change set — that is review.code"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 1 }],
+      "operands": [
+        { "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)" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "outside a git tree the receipt is skipped with a warning", "enforcement": "enforced", "condition": "unless AW_REVIEW_RECEIPTS names a destination", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.diff",
+      "kind": "primary",
+      "role": "review",
+      "submode": "diff",
+      "purpose": "Review a diff file you assembled yourself, rather than the live working tree.",
+      "whenToUse": [
+        "reviewing a diff that is not the current tree — a patch, a range, another branch",
+        "reviewing a change set trimmed to the hunks that matter"
+      ],
+      "whenNotTo": ["the current uncommitted tree — review.code assembles that for you"],
+      "invocationRefs": [{ "contractField": "invocations", "index": 2 }],
+      "operands": [
+        { "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)" }
+      ],
+      "guardrails": [
+        { "value": "read-only posture — the prompt forbids edits, commands and git writes", "enforcement": "advisory", "source": "bin/agy-review.sh" },
+        { "value": "the receipt fingerprints the DIFF FILE, never the tree — it cannot attest the tree", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.continue",
+      "kind": "continuation",
+      "role": "review",
+      "purpose": "Send a round-2 delta into the review already open in this conversation.",
+      "whenToUse": [
+        "asking the same reviewer whether a fold really solves its own finding",
+        "a follow-up round that must not re-read the whole artifact"
+      ],
+      "whenNotTo": ["attesting a folded tree — a continuation records fresh:false and never satisfies the gate"],
+      "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)" }
+      ],
+      "guardrails": [
+        { "value": "--facts is rejected on a continuation — the facts are already in the conversation", "enforcement": "enforced", "source": "bin/agy-review.sh" },
+        { "value": "a continuation receipt is fresh:false — informational only, never a gate pass", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "review.conversation",
+      "kind": "continuation",
+      "role": "review",
+      "purpose": "Resume a NAMED review conversation by its id, rather than the most recent one.",
+      "whenToUse": ["returning to a specific earlier review after other agy runs happened in between"],
+      "invocationRefs": [{ "contractField": "continue", "index": 1 }],
+      "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)" }
+      ],
+      "guardrails": [
+        { "value": "a continuation receipt is fresh:false — informational only, never a gate pass", "enforcement": "enforced", "source": "capability.json roles.review.contract.receipt" }
+      ],
+      "customHooks": ["AGY_PROBE"]
+    },
+    {
+      "key": "run",
+      "kind": "primary",
+      "role": "probe",
+      "purpose": "Send a raw advisory prompt to a selectable model and print the reply.",
+      "whenToUse": [
+        "a one-off question that needs no repo grounding",
+        "reaching a specific model (Gemini, Claude, GPT-OSS) from the terminal",
+        "a throwaway probe of the CLI, a model, or the wrapper plumbing"
+      ],
+      "whenNotTo": ["a code or plan review — agy-review owns the grounded posture and the receipt"],
+      "descriptor": "agy-run <prompt|-|@file> -- <extra agy flags...>",
+      "operands": [
+        { "slot": "<prompt|-|@file>", "required": true, "description": "the prompt text, - to read it from stdin, or @path to read it from a file" },
+        { "slot": "<extra agy flags...>", "required": false, "description": "raw agy flags passed straight through after --" }
+      ],
+      "guardrails": [
+        { "value": "subscription-only — every *_API_KEY env var is unset before the run", "enforcement": "enforced", "source": "bin/agy.sh" },
+        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.1 Pro (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
+        { "value": "hard wall-clock cap AGY_HARD_TIMEOUT (built-in default 5m)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.AGY_HARD_TIMEOUT" },
+        { "value": "the prompt rides a single argv — over AGY_MAX_PROMPT_BYTES (120000) the run refuses", "enforcement": "enforced", "source": "bin/agy.sh" },
+        { "value": "no review posture, no grounding, no receipt — the reply is raw model output", "enforcement": "advisory", "source": "bin/agy.sh" }
+      ],
+      "customHooks": ["run"]
+    },
+    {
+      "key": "AGY_PROBE",
+      "kind": "env-hook",
+      "parents": ["review.code", "review.plan", "review.diff", "review.continue", "review.conversation"],
+      "purpose": "Silence the off-frontier model advisory for a THROWAWAY probe review.",
+      "whenToUse": [
+        "a probe whose answer cannot depend on the model",
+        "deliberately reviewing with a cheaper non-frontier model"
+      ],
+      "whenNotTo": ["any run whose output informs what ships — a probe never attests"],
+      "descriptor": "AGY_PROBE=1 agy-review code --facts @<facts-file>",
+      "operands": [
+        { "slot": "@<facts-file>", "required": true, "description": "the verified facts the review runs AGAINST" }
+      ],
+      "guardrails": [
+        { "value": "a probe review mints a probe-marked receipt the review-state gate rejects", "enforcement": "enforced", "source": "agent-workflow-kit tools/review-state.mjs" }
+      ]
+    }
+  ],
   "settings": [
     {
       "key": "AGY_HARD_TIMEOUT",

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: '2.7.0'
+  version: '2.8.0'
 ---
 
 # codex-cli-bridge
@@ -71,6 +71,13 @@ waste, never lowering quality. Full knob list: [§ Environment knobs](#environme
 
 ## Usage
 
+> **The machine-readable mode catalog lives in [`capability.json`](capability.json) `modeCatalog`** —
+> every documented mode with its purpose, when to use it (and when not), the exact invocation form
+> with its operand slots, and the guardrails that really apply. The catalog tracks **the documented
+> wrapper mode set** (never "the CLI's modes"): an upstream Codex CLI change reaches it through a
+> bridge release, where the source-level drift tests fail loudly until the catalog is updated.
+> Nothing probes a live CLI. The prose below stays the human tour.
+
 Drive codex only through the two wrappers (installed on `PATH`), run from the target project root:
 
 ```bash

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

@@ -112,12 +112,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -169,6 +179,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0

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

@@ -821,6 +821,139 @@ describe('codex-exec.sh — source-level reverse guard (parser arms ⟷ manifest
   });
 });
 
+// ── mode catalog ⟷ wrapper reality (BRIDGE-MODES-CATALOG) ─────────────────────────
+// The kit validator owns the catalog's INTERNAL shape; these arms pin the half only this wrapper's
+// source can settle — the execute role's cataloged modes really exist here, every declared contract
+// invocation is cataloged, and the env-hook the catalog aims at exec really changes the run.
+
+// The source lines that really EXECUTE: a heredoc body (the --help text) and a comment both carry
+// names without carrying logic, so a bare name-grep stays green after the logic is deleted.
+const executableLines = (source) => {
+  const out = [];
+  let heredoc = null;
+  for (const raw of source.split('\n')) {
+    if (heredoc) {
+      if (raw.trim() === heredoc) heredoc = null;
+      continue;
+    }
+    const hd = raw.match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (hd) { heredoc = hd[1]; continue; }
+    if (raw.trimStart().startsWith('#')) continue;
+    out.push(raw);
+  }
+  return out;
+};
+const consultsEnv = (source, name) =>
+  executableLines(source).some((l) => new RegExp(`\\[\\[[^\\]]*\\$\\{?${name}\\b[^\\]]*(==|!=)`).test(l));
+// The optional `@` prefix rides WITH the slot — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
+describe('codex-exec.sh — mode catalog ⟷ wrapper reality (manifest-pinned)', () => {
+  const source = readFileSync(WRAPPER, 'utf8');
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const execEntries = catalog.filter((e) => e.role === 'execute');
+
+  it('the execute role is cataloged: one primary plus a continuation per resume flag', () => {
+    const primaries = execEntries.filter((e) => e.kind === 'primary');
+    const continuations = execEntries.filter((e) => e.kind === 'continuation');
+    assert.equal(primaries.length, 1, 'codex-exec has exactly one primary drive form');
+    assert.equal(continuations.length, EXEC_CONTRACT.continue.length, 'one continuation entry per declared resume descriptor');
+  });
+
+  it('every execute entry composes BY REFERENCE and every reference resolves', () => {
+    for (const entry of execEntries) {
+      assert.ok(
+        Array.isArray(entry.invocationRefs) && entry.invocationRefs.length > 0,
+        `${entry.key}: a contract-backed entry references at least one contract descriptor`,
+      );
+      assert.ok(!Object.hasOwn(entry, 'descriptor'), `${entry.key}: a contract-backed entry never restates a literal descriptor`);
+      for (const ref of entry.invocationRefs) {
+        assert.equal(
+          typeof EXEC_CONTRACT[ref.contractField]?.[ref.index], 'string',
+          `${entry.key}: ref ${ref.contractField}[${ref.index}] does not resolve into the manifest contract`,
+        );
+      }
+    }
+  });
+
+  it('every execute contract invocation is claimed by exactly ONE catalog entry (no uncataloged form)', () => {
+    const claims = execEntries.flatMap((e) => e.invocationRefs.map((r) => `${r.contractField}[${r.index}]`));
+    assert.equal(new Set(claims).size, claims.length, 'a contract invocation is claimed at most once');
+    const declared = [
+      ...EXEC_CONTRACT.invocations.map((_, i) => `invocations[${i}]`),
+      ...EXEC_CONTRACT.continue.map((_, i) => `continue[${i}]`),
+    ];
+    setEq(new Set(claims), declared, 'catalog claims ⟷ declared contract invocations');
+  });
+
+  it('every env-hook the catalog aims at an execute mode is a real EXECUTABLE guard, not a mention', () => {
+    const hooks = catalog.filter((e) => e.kind === 'env-hook' && e.parents.some((p) => execEntries.some((x) => x.key === p)));
+    assert.ok(hooks.length > 0, 'CODEX_PROBE must be cataloged as an env-hook over codex-exec');
+    for (const hook of hooks) {
+      assert.ok(
+        consultsEnv(source, hook.key),
+        `env-hook ${hook.key} is named in the source but never TESTED in an executable condition — a help/comment mention would keep a name-grep green after the logic is deleted`,
+      );
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots its rendered forms really carry (both directions)', () => {
+    for (const entry of execEntries) {
+      const forms = entry.invocationRefs.map((r) => EXEC_CONTRACT[r.contractField][r.index]);
+      // The DEDUPLICATED UNION over every resolved form: `exec` legitimately spreads its slots across
+      // two descriptors, so per-form equality would false-fail a correct catalog.
+      const realSlots = new Set(forms.flatMap((f) => f.match(SLOT_RE) ?? []));
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its forms really carry`);
+    }
+  });
+
+  it('the catalog claims CODEX_PROBE over the resume modes because the guard really precedes resume parsing', () => {
+    // Verified in source: the quality guard runs BEFORE the resume dispatch, so a resume run is
+    // relaxed too — the catalog must say so, and this pins the ORDER the claim rests on.
+    const lines = executableLines(source);
+    const guardAt = lines.findIndex((l) => /\$\{?CODEX_PROBE/.test(l));
+    const resumeAt = lines.findIndex((l) => /^\s*--resume-last\)/.test(l));
+    assert.ok(guardAt !== -1 && resumeAt !== -1, 'both the probe guard and the resume arm must exist');
+    assert.ok(guardAt < resumeAt, 'the probe guard must precede resume parsing — else the resume parents are a false claim');
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    for (const key of ['exec.resume-last', 'exec.resume']) {
+      assert.ok(hook.parents.includes(key), `${key} is relaxed by the hook, so the catalog must declare it a parent`);
+    }
+  });
+
+  it('CODEX_PROBE really relaxes the guard on EVERY execute parent the catalog claims (behavioural)', () => {
+    // Source ORDER alone is not the claim: a branch bug after resume parsing would keep it green.
+    // Drive each claimed parent for real — the guard must stop the dispatch without the hook, and
+    // codex must really be reached with it (r.argv is non-empty only on a real invocation).
+    const hook = catalog.find((e) => e.key === 'CODEX_PROBE');
+    const drive = {
+      exec: (sb) => ({ args: ['-'], input: 'do a thing' }),
+      'exec.resume-last': (sb) => {
+        writeFileSync(join(sb.repo, '.codex-last-session'), 'sess-from-sidecar\n');
+        return { args: ['--resume-last', '-'], input: 'continue' };
+      },
+      'exec.resume': () => ({ args: ['--resume', 'sess-xyz', '-'], input: 'continue' }),
+    };
+    const execParents = hook.parents.filter((p) => execEntries.some((x) => x.key === p));
+    assert.ok(execParents.length > 0, 'CODEX_PROBE must claim at least one execute parent');
+    for (const parent of execParents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+
+      const guarded = makeSandbox();
+      const off = run(guarded, { ...drive[parent](guarded), env: { CODEX_MODEL: 'not-the-pinned-model' } });
+      rmSync(guarded.root, { recursive: true, force: true });
+      assert.equal(off.status, 2, `${parent}: the quality guard must refuse an off-pin model without the hook`);
+      assert.equal(off.argv, '', `${parent}: the guard must refuse BEFORE spending a run`);
+
+      const probed = makeSandbox();
+      const on = run(probed, { ...drive[parent](probed), env: { CODEX_MODEL: 'not-the-pinned-model', CODEX_PROBE: '1' } });
+      rmSync(probed.root, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: CODEX_PROBE=1 must really relax the guard — the catalog claims it does`);
+      assert.notEqual(on.argv, '', `${parent}: CODEX_PROBE=1 must really reach codex, not merely exit 0`);
+    }
+  });
+});
+
 // ── bridge settings file + service tier knob (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
@@ -1080,8 +1213,9 @@ describe('codex-exec.sh — settings surface ⟷ manifest (D6, manifest-pinned)'
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

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

@@ -62,7 +62,10 @@ Receipt:
   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); a write failure warns, never fails the review
+  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); a
+  write failure warns, never fails the review
 
 Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):
   ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf
@@ -104,12 +107,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -161,6 +174,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0
@@ -172,7 +193,7 @@ DEFAULT_CODEX_EFFORT="xhigh"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by codex-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="codex"
-AW_BRIDGE_VERSION="2.7.0"
+AW_BRIDGE_VERSION="2.8.0"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
 CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # Generous hard cap for a slow xhigh review (subscription latency varies).
@@ -199,7 +220,11 @@ fi
 CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
 
 # --- Quality-first guard: refuse a silent model/effort downgrade ---------------
+# A relaxed run is RECORDED, not just warned about: the receipt carries probe:true so the kit's
+# review-state gate rejects it — "do NOT use this as a real review" becomes a mechanism, not a plea.
+REVIEW_PROBE=false
 if [[ "${CODEX_PROBE:-}" == "1" ]]; then
+  REVIEW_PROBE=true
   echo "warning: CODEX_PROBE=1 — THROWAWAY PROBE MODE. Quality guards relaxed; do NOT use this run's" >&2
   echo "         output as a real review (model='$CODEX_MODEL' effort='$CODEX_EFFORT')." >&2
 else
@@ -396,13 +421,18 @@ receipt_json_scalar() {
   if [[ -z "${1:-}" ]]; then printf 'null'; else printf '"%s"' "$1"; fi
 }
 
-# write_review_receipt <artifact|""> <fresh: true|false> <fingerprint|""> <verdict> <grounded: true|false> <factsHash|"">
+# write_review_receipt <artifact|""> <fresh: true|false> <fingerprint|""> <verdict> <grounded: true|false> <factsHash|""> [probe: true|false]
 # Appends ONE receipt line (the AD-038 fixture shape) as a side effect of a SUCCESSFUL review —
 # to $AW_REVIEW_RECEIPTS when set, else <git dir>/agent-workflow-review-receipts.jsonl (inside the
 # git dir by construction, so it is never committable). Fail-safe: every failure here warns loudly
 # and returns 0 — a missing receipt fails the kit's review-state CHECKER, never the review run.
+# The optional 7th argument marks a PROBE run (CODEX_PROBE=1 / AGY_PROBE=1 — the quality guards
+# relaxed), which the kit's review-state gate rejects: a probe review must never attest a tree. The
+# marker is written ALWAYS, true or false: the receipt SELF-DECLARES, so the gate reads the fact
+# itself instead of inferring it from this wrapper's version (which bumps in a different release
+# phase). Silence is not a declaration — an unmarked receipt is untrustworthy and the gate rejects it.
 write_review_receipt() {
-  local artifact="$1" fresh="$2" fingerprint="$3" verdict="$4" grounded="$5" facts_hash="$6"
+  local artifact="$1" fresh="$2" fingerprint="$3" verdict="$4" grounded="$5" facts_hash="$6" probe="${7:-false}"
   local receipts="${AW_REVIEW_RECEIPTS:-}"
   if [[ -z "$receipts" ]]; then
     local receipt_git_dir
@@ -412,11 +442,12 @@ write_review_receipt() {
     fi
     receipts="$receipt_git_dir/agent-workflow-review-receipts.jsonl"
   fi
-  local line
-  line="$(printf '{"schema":1,"artifact":%s,"fresh":%s,"fingerprint":%s,"backend":"%s","verdict":"%s","grounded":%s,"factsHash":%s,"wrapperVersion":"%s","timestamp":"%s"}' \
+  local line probe_field=',"probe":false'
+  if [[ "$probe" == "true" ]]; then probe_field=',"probe":true'; fi
+  line="$(printf '{"schema":1,"artifact":%s,"fresh":%s,"fingerprint":%s,"backend":"%s","verdict":"%s","grounded":%s,"factsHash":%s,"wrapperVersion":"%s","timestamp":"%s"%s}' \
     "$(receipt_json_scalar "$artifact")" "$fresh" "$(receipt_json_scalar "$fingerprint")" \
     "$AW_RECEIPT_BACKEND" "$verdict" "$grounded" "$(receipt_json_scalar "$facts_hash")" \
-    "$AW_BRIDGE_VERSION" "$(date -u +%Y-%m-%dT%H:%M:%SZ)")"
+    "$AW_BRIDGE_VERSION" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$probe_field")"
   if ! printf '%s\n' "$line" >>"$receipts" 2>/dev/null; then
     echo "warning: could not append the review receipt to $receipts — the review itself succeeded;" >&2
     echo "         the review-state gate will read the current tree as un-receipted." >&2
@@ -669,5 +700,5 @@ fi
 [[ -z "$verdict" ]] && verdict="unknown"
 # codex is grounded by construction (AGENTS.md auto-merge + the precomputed change set): grounded
 # true, factsHash null (native grounding — no separate facts payload exists). Every codex run is a
-# full fresh run (one-shot, no resume) → fresh:true.
-write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" true ""
+# full fresh run (one-shot, no resume) → fresh:true. $REVIEW_PROBE marks a guards-relaxed run.
+write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" true "" "$REVIEW_PROBE"