@sabaiway/agent-workflow-kit 1.48.0 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,104 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 2.0.0 — Bridge mode catalog (manifest-as-source) + a review receipt that SELF-DECLARES (AD-057)
+
+> ### ⚠ BREAKING — a review receipt written before this release no longer attests a tree
+>
+> The kit now **rejects an unmarked receipt**: a receipt must self-declare whether it came from a
+> probe run, and silence is not a declaration. Every receipt on disk from kit ≤ 1.49.0 / bridges
+> ≤ 2.7.1 / ≤ 2.6.1 predates the marker, so `review-state --check` and `review-ledger --check` will
+> RED on it where they previously passed.
+>
+> **How to upgrade:** `npx @sabaiway/agent-workflow-kit@latest init`, which also ATTEMPTS to refresh
+> the placed bridges — then read its per-bridge outcome. **`skipped-readonly` or `could not refresh`
+> means a compatible writer is not guaranteed:** the new reader may still be paired with an old bridge
+> writer, whose reviews write unmarked receipts this gate now rejects. Re-run the refresh from a
+> writable environment (using the recovery command if one was printed), then **re-run the review** on
+> the tree you are working on. That is the whole migration; no project file changes, and the
+> deployment-lineage stamp is untouched.
+>
+> **Why it is not opt-in.** The pre-marker wrappers already honoured `CODEX_PROBE` / `AGY_PROBE` and
+> wrote no marker, so an unmarked receipt is **indistinguishable from a probe receipt** — a review
+> that ran with the frontier-model/max-effort guard switched off. Any transitional window that keeps
+> accepting unmarked receipts keeps the hole fully open for exactly the receipts it targets: it would
+> not defer the break, it would cancel the fix.
+
+A **breaking + feature** release (kit MAJOR carrying codex-cli-bridge **2.8.0** + antigravity-cli-bridge
+**2.7.0** MINOR in-tarball — the bridges only ADD a field to the receipt they write, which is additive;
+the incompatibility is created by the kit READER that now refuses the old form. engine 1.17.0 / memory
+2.3.0 unchanged; the deployment-lineage head is a separate axis and stays `2.0.0`). Two independent
+contracts, one theme: **what a bridge offers, and what a receipt claims, must both be readable off the
+artifact itself — never inferred from source or from silence.**
+
+- **`modeCatalog` — a machine-readable answer to "what modes does this bridge offer, and why?"** A new
+  **top-level, additive-optional** manifest block (schema stays 1), typed-validated exactly like
+  `settings`: absent → valid (a bridge predating it keeps validating), present-but-malformed → invalid.
+  Both bridges now declare their real mode set — codex `{exec, exec.resume-last, exec.resume,
+  review.plan, review.code, CODEX_PROBE}`, agy `{review.code/plan/diff, review.continue,
+  review.conversation, run, AGY_PROBE}` — each entry carrying a closed taxonomy (`primary` /
+  `continuation` / `env-hook`, where an env-hook names `parents[]` rather than faking a role), a
+  required one-line `purpose` + `whenToUse`, and — declared only where they apply — `whenNotTo`, typed
+  `operands[]`, structured `guardrails` `{value, enforcement, condition?, source}` and `customHooks[]`
+  (`exec.resume` carries no `guardrails`; a mode with no operands omits `operands`). Invocation forms compose **by
+  reference** (`invocationRefs[]`) into the existing AD-033 driving contract — the catalog is the
+  user-facing DISCOVERY layer and never shadows it.
+- **Descriptor honesty is enforced, not promised.** Declared operand slots must set-EQUAL the
+  placeholders the referenced forms really carry, in **both** directions over the deduplicated union of
+  an entry's forms: an undeclared placeholder is as dishonest as an invented slot, since either way the
+  render shows a form as ready-to-run that the reader cannot actually fill. `enforced` is claimable only
+  for an OS- or code-enforced fact; a runtime bound rides in `condition`; anything a prompt merely asks
+  for renders `advisory`. Catalog `submode` values are drift-guarded against the wrappers' real parser
+  arms, and every declared env-hook must be a real EXECUTABLE condition (heredocs and comments excluded,
+  so a name-grep cannot stay green after the logic is deleted).
+- **A probe review can no longer attest a tree — and the receipt says so itself.** Both wrappers wrote
+  receipts unconditionally, so a `CODEX_PROBE=1` / `AGY_PROBE=1` review — which runs with the
+  frontier-model/max-effort guard **off** — minted a `fresh:true`/`grounded:true` receipt the
+  review-state gate accepted. Both wrappers now write `probe` on **every** successful review, `true` or
+  `false`, through the shared byte-identical `write_review_receipt` block: a receipt self-declares and
+  nothing has to infer it. The kit rejects a probe-marked receipt (a probe never attests) and **equally
+  rejects an unmarked one — silence is not a declaration**.
+- **One attesting predicate, three consumers.** `classifyReviewReceiptForTree` /
+  `summarizeReviewReceiptsForTree` / `describeMissingReviewAttestation` live in the neutral
+  `review-ledger-core.mjs` and are read by `review-state.mjs`, `receiptCrossCheck` and the round writer
+  — two gates disagreeing about what attests is precisely the class AD-050 closed, and a second copy
+  would re-open it. The shared summary also fixes a latent hole: the ledger took `own[own.length - 1]`,
+  so a probe landing **after** a real review became the authoritative verdict — a probe SHIP could bury
+  a real REWORK and let both gates report convergence. The summary now returns the latest **attesting**
+  receipt, never the last line.
+- **Scope of the claim.** What a marker carries is UNTRUSTWORTHINESS, never provenance — receipts are
+  not authenticated, and a forger could write `probe:false` as easily as any other field. This is
+  self-discipline made legible, not a security boundary. See the BREAKING callout above for the upgrade
+  path; full record, including the mid-execution amendment of the original design and the stated
+  residuals, in AD-057.
+
+## 1.49.0 — Honesty/robustness bundle: refresh EROFS stated skip · settings integer-overflow parity (AD-056)
+
+A small **honesty/robustness** release (kit MINOR carrying the two bridge PATCH bumps in-tarball —
+codex-cli-bridge 2.7.1 + antigravity-cli-bridge 2.6.1; engine 1.17.0 / memory 2.3.0 unchanged; lineage
+head stays `2.0.0`). Two kit/bridge fixes ship here (a third, repo-only dispatcher fix, rides the same
+commit); all three share one theme: **a blocked environment must produce a STATED degrade, never a
+false red — and a real failure stays loud.**
+
+- **Refresh under a read-only skills dir is a stated skip, not a false failure.** Under the harness
+  session sandbox `~/.claude/skills` is read-only, yet `--refresh-placed` re-syncs even at the current
+  version (repair-on-rerun). That write EROFSed into the generic catch → *"could not refresh — … recover
+  with setup"*, though both versions were already current AND `setup` hits the same read-only dir. It now
+  reports a new **`skipped-readonly`** outcome (exit 0): it names the current version, states the re-sync
+  was skipped/incomplete, and names the read-only cause — never claiming a re-sync ran or file integrity
+  (a partial copy may precede the block). Only a read-only-class write failure at the copy-write boundary,
+  at an equal version, degrades; a read-side / source-side / `linkWrappers` / real-I/O failure, or a
+  version-**behind** refresh, stays a loud *could not refresh* (its recovery pointing at a writable
+  rerun). The opt-in `setup` placement lane keeps its loud failure. Any drift persists until a writable
+  rerun (converge-on-re-run).
+- **Settings integer validation is now shell↔JS exact (Issue-012, Resolved).** The four bridge wrappers'
+  shared `aw_settings_valid` integer arms did `(( 10#$v … ))`, which wraps modulo 2^64 on a 19+ digit
+  string — the shell **accepted** `18446744073709551916` (2^64+300) while the kit's `settingValueValid`
+  (safe-integer) **rejected** it. A shared overflow-safe `aw_int_in_range` helper (byte-identical across
+  all four wrappers) strips leading zeros then rejects on a digit count exceeding the max's — never
+  running arithmetic on a huge string. A leading-zero **in-range** value (e.g. `000…086400`) still
+  passes on both sides; the value is pinned by a new behavioral shell↔JS parity test.
+
 ## 1.48.0 — Family-owned neutral ack store + read-prompt-economy hook lane (AD-055, the CLAUDE-CODE-HARNESS-FRICTION cluster)
 
 A **feature** release (kit-only — engine 1.17.0, memory 2.3.0, bridges 2.7.0/2.6.0 unchanged) that

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.48.0'
+  version: '2.0.0'
 ---
 
 # agent-workflow-kit

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

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.6.0'
+  version: '2.7.0'
 ---
 
 # antigravity-cli-bridge
@@ -69,6 +69,14 @@ list wins.
 
 ## Usage
 
+> **The machine-readable mode catalog lives in [`capability.json`](capability.json) `modeCatalog`** —
+> every documented mode (`agy-run` raw prompts, the three `agy-review` modes, their continuations,
+> the `AGY_PROBE` escape) 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 Antigravity 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 `agy` only through the wrapper [`bin/agy.sh`](bin/agy.sh) (installed on `PATH` as `agy-run`):
 
 ```bash

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

@@ -91,7 +91,10 @@ Receipt:
   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
+  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
 
 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
@@ -132,12 +135,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 ;;
@@ -189,6 +202,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
@@ -199,7 +220,7 @@ DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="2.6.0"
+AW_BRIDGE_VERSION="2.7.0"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable warning.
@@ -210,6 +231,10 @@ FRONTIER_SET=("Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonne
 AGY_HARD_TIMEOUT="${AGY_HARD_TIMEOUT:-30m}"
 AGY_TIMEOUT="${AGY_TIMEOUT:-$AGY_HARD_TIMEOUT}"
 AGY_PROBE="${AGY_PROBE:-0}"
+# A probe run is RECORDED, not just silently allowed: the receipt carries probe:true so the kit's
+# review-state gate rejects it — a guards-relaxed review must never attest a tree.
+REVIEW_PROBE=false
+if [[ "$AGY_PROBE" == "1" ]]; then REVIEW_PROBE=true; fi
 AGY_REVIEW_ALLOW_ADDDIR="${AGY_REVIEW_ALLOW_ADDDIR:-0}"
 AGY_MAX_PROMPT_BYTES="${AGY_MAX_PROMPT_BYTES:-120000}"
 if [[ ! "$AGY_MAX_PROMPT_BYTES" =~ ^[0-9]+$ ]]; then
@@ -414,13 +439,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
@@ -430,11 +460,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
@@ -777,7 +808,7 @@ if [[ $rc -eq 0 ]]; then
     # A continuation never re-embeds the current artifact (agy holds the ORIGINAL round server-side;
     # --facts is rejected above), so it cannot attest the folded tree: fresh:false, artifact /
     # fingerprint / factsHash null, grounded false — informational-only, ignored by the state gate.
-    write_review_receipt "" false "" "$verdict" false ""
+    write_review_receipt "" false "" "$verdict" false "" "$REVIEW_PROBE"
     echo "notice: a continuation receipt is fresh:false (informational-only) — only a fresh grounded run" >&2
     echo "        (agy-review code --facts @f) mints a receipt that satisfies the review-state gate." >&2
   else
@@ -787,7 +818,7 @@ if [[ $rc -eq 0 ]]; then
       grounded=true
       facts_hash="$(printf '%s' "$FACTS_CONTENT" | sha256_stdin || true)"
     fi
-    write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" "$grounded" "$facts_hash"
+    write_review_receipt "$REVIEW_ARTIFACT" true "$REVIEW_FINGERPRINT" "$verdict" "$grounded" "$facts_hash" "$REVIEW_PROBE"
   fi
 fi
 exit $rc

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

@@ -521,6 +521,32 @@ const extractArgCaseArms = (source) => {
 };
 const splitArms = (labels) => (labels ?? []).flatMap((l) => l.split('|'));
 
+// 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 over the whole source stays green after the
+// logic is deleted. Reuses the same heredoc discipline as extractArgCaseArms.
+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;
+};
+// An env var is really CONSULTED when an executable test compares it: [[ "$NAME" == … ]].
+const consultsEnv = (source, name) =>
+  executableLines(source).some((l) => new RegExp(`\\[\\[[^\\]]*\\$\\{?${name}\\b[^\\]]*(==|!=)`).test(l));
+// The operand slots a rendered invocation form really carries: <angle> and [bracket] placeholders.
+// The optional `@` prefix rides WITH the slot (`@<facts-file>` is one operand, not a bare
+// `<facts-file>` behind a stray character) — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
 describe('agy-review.sh — --help contract (manifest-pinned)', () => {
   it('--help and -h exit 0 pre-preflight (no agy, no git)', () => {
     for (const arg of ['--help', '-h']) {
@@ -597,6 +623,116 @@ describe('agy-review.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 cataloged review modes ARE the real parser arms, every declared contract
+// invocation is cataloged, and the env-hook the catalog aims at review is a real env var.
+describe('agy-review.sh — mode catalog ⟷ wrapper reality (manifest-pinned)', () => {
+  const source = readFileSync(WRAPPER, 'utf8');
+  const arms = extractArgCaseArms(source);
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const reviewEntries = catalog.filter((e) => e.role === 'review');
+  const reviewPrimaries = reviewEntries.filter((e) => e.kind === 'primary');
+
+  it('the catalog submodes ARE the wrapper\'s real parser mode arms (both directions)', () => {
+    const modes = splitArms(arms.get('"$mode"')).filter((a) => a !== '*');
+    assert.ok(reviewPrimaries.length > 0, 'the manifest must catalog its review modes');
+    setEq(new Set(reviewPrimaries.map((e) => e.submode)), new Set(modes), 'catalog submodes ⟷ real parser mode arms');
+  });
+
+  it('every review entry composes BY REFERENCE and every reference resolves', () => {
+    for (const entry of reviewEntries) {
+      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 REVIEW_CONTRACT[ref.contractField]?.[ref.index], 'string',
+          `${entry.key}: ref ${ref.contractField}[${ref.index}] does not resolve into the manifest contract`,
+        );
+      }
+    }
+  });
+
+  it('every review contract invocation is claimed by exactly ONE catalog entry (no uncataloged mode)', () => {
+    const claims = reviewEntries.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 = [
+      ...REVIEW_CONTRACT.invocations.map((_, i) => `invocations[${i}]`),
+      ...REVIEW_CONTRACT.continue.map((_, i) => `continue[${i}]`),
+    ];
+    setEq(new Set(claims), declared, 'catalog claims ⟷ declared contract invocations');
+  });
+
+  it('every env-hook the catalog aims at a review mode is a real EXECUTABLE guard, not a mention', () => {
+    const hooks = catalog.filter((e) => e.kind === 'env-hook' && e.parents.some((p) => reviewPrimaries.some((r) => r.key === p)));
+    assert.ok(hooks.length > 0, 'AGY_PROBE must be cataloged as an env-hook over the review modes');
+    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 reviewEntries) {
+      const forms = entry.invocationRefs.map((r) => REVIEW_CONTRACT[r.contractField][r.index]);
+      // The DEDUPLICATED UNION over every resolved form: a plural-ref entry legitimately spreads its
+      // slots across forms, 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('an entry rendering a LITERAL descriptor is slot-checked too (env-hooks have no role to filter on)', () => {
+    // The contract-backed arm above filters by role — and an env-hook HAS no role, so its descriptor
+    // was never slot-checked at all. That is exactly how a hardcoded dead path can reach the
+    // discovery surface looking ready-to-run. Every literal-descriptor kind is covered here:
+    // env-hooks and contract-free primaries.
+    const literalEntries = catalog.filter((e) => typeof e.descriptor === 'string');
+    assert.ok(literalEntries.length > 0, 'AGY_PROBE must be cataloged with a literal descriptor');
+    for (const entry of literalEntries) {
+      const realSlots = new Set(entry.descriptor.match(SLOT_RE) ?? []);
+      setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, `${entry.key}: catalog operands ⟷ the slots its descriptor really carries`);
+    }
+  });
+
+  it('AGY_PROBE really silences the advisory on EVERY review parent the catalog claims (behavioural)', () => {
+    // The catalog CLAIMS these modes are modified by the hook; prove it per parent rather than
+    // trusting a source scan: the off-frontier advisory fires without it, is silent with it.
+    const hook = catalog.find((e) => e.key === 'AGY_PROBE');
+    const drive = {
+      'review.code': () => ['code', '--facts', 'f'],
+      'review.plan': (sb) => { writeFileSync(join(sb.repo, 'p.md'), '# p\n'); return ['plan', 'p.md', '--facts', 'f']; },
+      'review.diff': (sb) => { writeFileSync(join(sb.repo, 'c.diff'), 'diff body\n'); return ['diff', 'c.diff', '--facts', 'f']; },
+      'review.continue': () => ['--continue'],
+      'review.conversation': () => ['--conversation', 'conv-1'],
+    };
+    assert.ok(hook.parents.length > 0, 'AGY_PROBE must claim at least one parent');
+    for (const parent of hook.parents) {
+      assert.ok(drive[parent], `no behavioural drive for claimed parent "${parent}" — add one`);
+      // Both runs must really REACH agy: asserting the diagnostic text alone would let an early
+      // failure that never dispatched pass the probe-on branch (its stderr simply lacks the string).
+      const noisy = makeSandbox();
+      const off = run(noisy, { args: drive[parent](noisy), env: { AGY_MODEL: 'Some Weak Model' } });
+      rmSync(noisy.home, { recursive: true, force: true });
+      assert.equal(off.status, 0, `${parent}: ${off.stderr}`);
+      assert.equal(off.invoked, true, `${parent}: the control run must reach agy`);
+      assert.match(off.stderr, /non-frontier model/, `${parent}: the advisory must fire without the hook`);
+
+      const quiet = makeSandbox();
+      const on = run(quiet, { args: drive[parent](quiet), env: { AGY_MODEL: 'Some Weak Model', AGY_PROBE: '1' } });
+      rmSync(quiet.home, { recursive: true, force: true });
+      assert.equal(on.status, 0, `${parent}: ${on.stderr}`);
+      assert.equal(on.invoked, true, `${parent}: AGY_PROBE=1 must still reach agy — silence must come from the hook, not from an early exit`);
+      assert.doesNotMatch(on.stderr, /non-frontier model/, `${parent}: AGY_PROBE=1 must really silence it — the catalog claims it does`);
+    }
+  });
+});
+
 describe('agy-review.sh — declared contract is really accepted (forward guard)', () => {
   it('every manifest mode runs green', () => {
     const drive = {
@@ -643,10 +779,10 @@ describe('agy-review.sh — declared contract is really accepted (forward guard)
 });
 
 // ── review receipts (AD-038) ─────────────────────────────────────────────────────
-// The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; backend/verdict here
+// The normative fixture: the AD-038 shape + the D3 self-declaring probe marker (backend/verdict here
 // carry this bridge's vocabulary; dynamic values are asserted by shape):
 const RECEIPT_FIXTURE = JSON.parse(
-  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z"}',
+  '{"schema":1,"artifact":"code","fresh":true,"fingerprint":"<sha256hex>","backend":"codex","verdict":"revise","grounded":true,"factsHash":null,"wrapperVersion":"2.3.0","timestamp":"2026-07-03T12:00:00Z","probe":false}',
 );
 const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
 const readReceipts = (repo) => {
@@ -682,6 +818,41 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
     assert.match(receipt.timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
   });
 
+  // The probe marker (BRIDGE-MODES-CATALOG, D3) — the twin of the sibling bridge's arm: an
+  // AGY_PROBE=1 review runs with the frontier-model advisory silenced, so its receipt is marked and
+  // the kit's review-state gate rejects it. EVERY receipt carries the marker (true or false): it
+  // self-declares, so the gate reads the fact rather than inferring it from a version string that
+  // bumps in a different release phase. Silence is not a declaration.
+  it('AGY_PROBE=1 stamps probe:true — a throwaway probe can never attest a tree (D3)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_PROBE: '1', AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].probe, true, 'a probe-relaxed run marks its own receipt');
+    assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
+  });
+
+  // Every receipt SELF-DECLARES: the kit's gate reads the marker, never the wrapper version — so
+  // the marker must not depend on a version bump landing in the same release phase.
+  it('a normal review self-declares probe:false — the receipt states the fact, not a version', () => {
+    const sb = makeSandbox();
+    run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(receipts[0].probe, false, 'silence is not a declaration — the gate rejects an unmarked receipt');
+  });
+
+  it('a probe CONTINUATION is marked too (it is doubly unable to attest — fresh:false AND probe)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['--continue'], env: { AGY_PROBE: '1', AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
+    const receipts = readReceipts(sb.repo);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(receipts[0].fresh, false);
+    assert.equal(receipts[0].probe, true, 'both write paths carry the marker — no unmarked probe lane');
+  });
+
   it('an ungrounded fresh run records grounded:false + factsHash null (the vacuous-grounding hole stays visible)', () => {
     const sb = makeSandbox();
     const r = run(sb, { args: ['code'], env: { AGY_FAKE_OUTPUT: VERDICT_OUTPUT } });
@@ -994,8 +1165,9 @@ describe('agy-review.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/antigravity-cli-bridge/bin/agy.sh

@@ -99,12 +99,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 ;;
@@ -156,6 +166,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/antigravity-cli-bridge/bin/agy.test.mjs

@@ -443,8 +443,9 @@ describe('agy.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') {
@@ -454,3 +455,79 @@ describe('agy.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () =>
     }
   });
 });
+
+// ── mode catalog: the contract-free raw mode ⟷ this wrapper (BRIDGE-MODES-CATALOG) ─────
+// agy-run is the probe role: it is dispatched by no activity slot and so carries NO manifest
+// driving contract (`wrapperContractFor(_, 'probe')` stays null). Its catalog entry therefore
+// carries a LITERAL descriptor — the stated exception to no-duplication, because for a
+// contract-free mode the catalog IS canonical. That makes the catalog the only thing that can
+// drift from this wrapper, so these arms pin it in BOTH directions and then really drive it.
+const USAGE_HEADER = 'Usage:';
+const PROBE_CMD = 'agy-run';
+// The operand slots a rendered invocation form really carries: <angle> and [bracket] placeholders.
+// The optional `@` prefix rides WITH the slot — the catalog declares the whole token a user types.
+const SLOT_RE = /@?<[^<>]+>|\[[^[\]]*\]/g;
+
+describe('agy.sh — mode catalog ⟷ wrapper reality (the contract-free raw mode)', () => {
+  const catalog = MANIFEST.modeCatalog ?? [];
+  const probeEntries = catalog.filter((e) => e.role === 'probe');
+
+  const helpText = () => {
+    const home = mkdtempSync(join(tmpdir(), 'agy-catalog-help-'));
+    const r = spawnSync('bash', [WRAPPER, '--help'], {
+      env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+      encoding: 'utf8',
+      timeout: 15000,
+    });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    return r.stdout;
+  };
+
+  it('the probe role is cataloged as exactly ONE contract-free primary carrying a literal descriptor', () => {
+    assert.equal(probeEntries.length, 1, 'agy-run is one mode — a raw prompt');
+    const [entry] = probeEntries;
+    assert.equal(entry.kind, 'primary');
+    assert.equal(MANIFEST.roles.probe.contract, undefined, 'the probe role carries no driving contract — the catalog must not invent one');
+    assert.ok(!Object.hasOwn(entry, 'invocationRefs'), 'a contract-free entry has nothing to reference');
+    assert.equal(typeof entry.descriptor, 'string', 'a contract-free entry is canonical for its own form');
+  });
+
+  it('the catalog descriptor IS a real --help Usage line (catalog → wrapper: no invented form)', () => {
+    const usage = helpSection(helpText(), USAGE_HEADER);
+    assert.ok(usage.includes(probeEntries[0].descriptor), `the cataloged form is in no Usage line: ${probeEntries[0].descriptor}`);
+  });
+
+  it('every --help Usage line belongs to the cataloged mode (wrapper → catalog: no uncataloged form)', () => {
+    const usage = helpSection(helpText(), USAGE_HEADER);
+    assert.ok(usage.length > 0, 'the wrapper must document its usage');
+    for (const line of usage) {
+      assert.ok(line.includes(PROBE_CMD), `Usage line "${line}" invokes something other than the one cataloged mode`);
+    }
+  });
+
+  it('the catalog operand slots set-EQUAL the slots the cataloged form really carries (both directions)', () => {
+    const [entry] = probeEntries;
+    const realSlots = new Set(entry.descriptor.match(SLOT_RE) ?? []);
+    setEq(new Set((entry.operands ?? []).map((o) => o.slot)), realSlots, 'catalog operands ⟷ the slots the descriptor really carries');
+  });
+
+  it('the required operand really accepts every form the catalog says it takes (forward drive)', () => {
+    // <prompt|-|@file> is ONE slot with three real spellings — drive all three against the stub.
+    const home = makeSandbox('#!/usr/bin/env bash\nprintf "%s" "$*" >"$HOME/argv"\necho FAKE_REPLY\n');
+    const promptFile = join(home, 'p.md');
+    writeFileSync(promptFile, 'from a file\n');
+    const env = { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, TMPDIR: process.env.TMPDIR ?? '/tmp' };
+    const drives = [
+      { label: 'literal prompt', args: ['inline prompt'], stdin: undefined },
+      { label: 'stdin (-)', args: ['-'], stdin: 'from stdin\n' },
+      { label: '@file', args: [`@${promptFile}`], stdin: undefined },
+    ];
+    for (const drive of drives) {
+      const r = spawnSync('bash', [WRAPPER, ...drive.args], { env, encoding: 'utf8', timeout: 20000, input: drive.stdin });
+      assert.equal(r.status, 0, `${drive.label}: ${r.stderr}`);
+      assert.match(r.stdout, /FAKE_REPLY/, `${drive.label} never reached agy`);
+    }
+    rmSync(home, { recursive: true, force: true });
+  });
+});