@sabaiway/agent-workflow-kit 1.34.0 → 1.36.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ 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.
 
+## 1.36.0 — Review-round ledger: the prose crossover-stop becomes a computed signal (AD-045)
+
+A **feature** release (deployment-lineage head stays `1.3.0` — no migration). The review-loop
+crossover-stop that `planning.md` §9 and `procedures.md` describe in prose — "cap ≤2 rounds", the
+crossover, "fold-at-altitude vs residual", "{round N · finding-origin tally · per-backend verdict} …
+a computed signal, not a remembered rule" — was **prose with no checker** and broke under load. This
+ships it as a **mechanism** (DEBT-REVIEW-CAP): a review-round **LEDGER** that protects every consumer
+project's `plan-execution` review loop.
+
+- **`tools/review-ledger.mjs`** (read-only) — the record schema (two kinds, `round` / `triage`,
+  internally-consistency-validated), a tolerant reader (malformed lines counted + surfaced, never
+  dropped), the pure **`decideStop`** truth table returning exactly one state under a fixed precedence
+  (**converged > resolved-residual > triage-required > continue**) from machine fields only, the
+  integrity receipt cross-check, and the **`--check`** gate — **fail-CLOSED** on every unknown state
+  (detector failure · unreadable / malformed ledger · a corrupt round sequence · more than one plan
+  in flight).
+- **`tools/review-ledger-write.mjs`** (the sole writer, over the hardened `atomic-write` core) —
+  `record` / `classify` with **the teeth**: it refuses a round while triage is required, beyond the
+  hard-max ceiling of 3, or without a grounded review receipt, and enforces round-sequence integrity +
+  round-bound classifications. The read/write split is pinned by an import-split test; the ledger lives
+  in the git dir (uncommittable by construction, mirroring the receipts precedent).
+- **Command surface** — a `review-ledger` catalog entry + `### Mode: review-ledger` + its mode
+  reference; the conditional `seed-gates` candidate (offered only when `plan-execution.review` is
+  reviewed / council).
+- **Honest residual** (stated in the tool header, like `review-state`'s): the ledger attests a review
+  occurred and its ship-class is consistent; it does not prove the recorded counts are truthful nor
+  that a self-reported `degraded` is real — a self-discipline mechanism, not a security boundary.
+
+Self-arming dogfood: this release's own review loop was recorded through the ledger it builds
+(`--check` exits 0 via the `converged` branch). The optional per-fold `testId` slot exists but stays
+**unenforced** — enforcement + a fold-completeness signal + the canon-pointer mechanization are the
+next plan (DEBT-TEST-COMPLETENESS).
+
+## 1.35.0 — Host-level bridge settings surface + Codex Fast tier as configuration (AD-043)
+
+A **feature** release (deployment-lineage head stays `1.3.0` — no migration). Bridge knobs like the
+Codex Fast tier are now enabled **through a host-level settings file that survives kit upgrades**,
+never re-researched and re-patched per host; the kit surfaces, reconciles, and honestly refreshes
+that surface. Ships **bridges 2.3.0** inside the tarball (the four wrappers' shared settings-reader
+block + the `CODEX_SERVICE_TIER` knob + the typed `settings` manifest schema, Phase 1). The kit
+machinery (Phase 2):
+
+- **`bridge-settings` mode — the host-config reader + consent-gated writer.** New
+  `tools/bridge-settings.mjs` (+ its read-only core `tools/bridge-settings-read.mjs`) reads/writes
+  `${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` — a `KEY=VALUE` file **outside
+  every kit tree** (D2, upgrade-survival is structural). Previews by default, `--apply` writes via a
+  hardened out-of-tree atomic core (`writeContainedFileAtomic` / `writeHostConfigFileAtomic`,
+  factored from `atomic-write.mjs` — symlink/parent/TOCTOU-safe, dir created on first use). The
+  allowlist + typed validation come from the **bundled bridge manifests** (`settings` blocks,
+  manifest-as-source / D6 — `settingValueValid` is now the single shared predicate). It refuses an
+  unknown key, an out-of-range/invalid value, and — loudly, naming the key — a duplicate-carrying
+  file; model/effort stay unsettable (the quality guard is untouched, D4). Routed in `SKILL.md`
+  (`guarded` kind) with `references/modes/bridge-settings.md`.
+- **Refresh overwrite honesty (D5).** `tools/setup-backends.mjs` now byte-compares a placed bridge
+  against the bundle on an equal-version re-sync and **states** the local edits it overwrote (file
+  list + the settings-file pointer), instead of the old silent wipe; a version upgrade never cries
+  wolf about the version delta, an unreadable placed file degrades honestly, a placed-only extra is
+  preserved and never claimed as loss.
+- **Init/upgrade reconcile.** `init` (`bin/install.mjs`) and `Mode: upgrade` run
+  `bridge-settings --reconcile` after the bridge refresh: every settings-file key is validated
+  against the new bundled manifests; an unknown/retired key is a loud flag, **preserved verbatim**
+  (never edited — the lens-region posture).
+- **Status + advisor surfaces (fact-only).** `status`' execution-backends block, the `procedures`
+  driving-contract render, and `recipes --status-line` now surface the active knobs (env>file>default)
+  and each wrapper's settable knobs — fact-only, no model claim, localized-on-error; the status line
+  stays byte-identical unless a knob is active.
+- Parity + budgets: new `test/settings-reader-parity.test.mjs` pins the reader block byte-identical
+  across the four wrappers; the always-loaded router stays `≤ 10240 B` (the equal-head reconcile
+  enumeration was trimmed to its step-3 pointer to make room for the new mode); the `routerPlusMode`
+  budget is re-pinned `29696 → 30720` (documented) for the reconcile paragraph added to `upgrade.md`.
+
 ## 1.34.0 — Onboarding UX: one batched setup prompt, honest installer messaging, the visible accelerator funnel, and the consent-gated gates seeder (AD-042)
 
 A **feature** release (first-contact flow + a new consent-gated writer; deployment-lineage head

package/README.md

@@ -240,6 +240,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
 | `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. Preview by default; never writes `settings.local.json`; never commits. |
+| `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the review byte cap, the oversized-review add-dir toggle. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

package/SKILL.md

@@ -3,12 +3,12 @@ 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.34.0'
+  version: '1.36.0'
 ---
 
 # agent-workflow-kit
 
-Deploys a **portable AI-agent memory-and-workflow system** into a project, and upgrades it as the kernel evolves — so any future agent can reconstruct project context in ~60 seconds and avoid repeating past mistakes.
+Deploys a **portable AI-agent memory-and-workflow system** into a project, and upgrades it as the kernel evolves — so any future agent can reconstruct project context fast and avoid repeating past mistakes.
 
 **Posture:** never leak kit internals — translate tool outcomes to plain language; Gotchas: `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`.
 
@@ -23,14 +23,13 @@ when it is present and healthy, and otherwise uses its **own bundled copy** (`re
 `migrations/`) — so the existing one-command install keeps working with **no new dependency on the
 memory substrate**. (The methodology slot is a separate axis: its fragment is read **live from the
 installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs — a
-runtime dependency placed by `init` and read live; see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
+runtime dependency read live; see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
-success: a warning with the exact recovery command + exit 0, never silent, never the engine's hard
-STOP; `--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
+success: warn + the exact recovery command + exit 0, never silent, never the engine's hard STOP;
+`--no-memory` skips it), so a returning `init` leaves **no stale core member**. The
 execution-backend bridges are still never **placed** by `init` (placed on demand by `setup`, opt-in);
-**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, local
-files, never a downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed
-bridge either.
+**once placed**, `init` **refreshes** them from the kit's own bundled copies (refresh-only, never a
+downgrade; `--no-bridges` skips it) — so a returning `init` leaves no stale placed bridge either.
 
 **Detection (kit-owned, decided BEFORE any project write).** Run the kit's **own shipped**
 validator — `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs <memory-skill-dir>` — never a
@@ -38,9 +37,8 @@ validator shipped by the candidate (which could itself be broken). Delegate only
 hold:
 - result is **valid** and `kind` is `memory-substrate`;
 - **every required asset is present** in the candidate, at its real path:
-  `references/templates/`, **`references/templates/orchestration.json`** (the orchestration-config
-  template — a memory too old to ship it, pre-`1.2.0`, can't seed `docs/ai/orchestration.json`, so it
-  falls back to the kit's own bundled substrate, which does), `references/contracts.md`,
+  `references/templates/`, **`references/templates/orchestration.json`** (a pre-`1.2.0` memory can't
+  ship it, so it falls back to the kit's bundled substrate), `references/contracts.md`,
   `references/scripts/`, `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial
   install (manifest + `SKILL.md` only) is treated as **invalid**.
 
@@ -75,13 +73,13 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `1.3.0`** (the deployment-lineage head) → `upgrade`.
-- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3 (pointer slots · hidden-mode footprint · both `.json` config ensures · the enforcement-script ensure · the placed-bridge refresh · the agent-rules lens refresh); run step 3 rather than enumerating from memory.
+- **stamp == `1.3.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3; run step 3 (never enumerate the reconciles from memory).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2).
 
 **Two independent version axes — never conflate them:**
 
 1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`1.3.0`). This is the **only** axis this skill compares.
-2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version (e.g. `1.x`) is **not** the lineage head.
+2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version is **not** the lineage head.
 
 **Refreshed the kit but nothing changed?** The skill you are running is whatever was on disk when the session started. After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files (the slash command + this `SKILL.md`).
 
@@ -125,6 +123,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/procedures.md` before a
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md` before acting.
 
+### Mode: set-autonomy
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-autonomy.md` before acting.
+
 ### Mode: uninstall
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/uninstall.md` before acting.
@@ -141,6 +143,10 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/agents.md` before acting.
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/hook.md` before acting.
 
+### Mode: bridge-settings
+
+guarded — read `${CLAUDE_SKILL_DIR}/references/modes/bridge-settings.md` before acting.
+
 ### Mode: review-state
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` before acting.
@@ -149,6 +155,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` before
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/grounding.md` before acting.
 
+### Mode: review-ledger
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/review-ledger.md` before acting.
+
 ---
 
 ## References

package/bin/install.mjs

@@ -53,6 +53,7 @@ import { FAMILY_MEMBERS } from '../tools/family-members.mjs';
 // skip (never a first placement, AD-009/AD-011) and a placed bridge newer than this kit's bundled
 // mirror is a stated skip too (never a downgrade). Every line it returns is tool-composed.
 import { refreshPlacedBridges } from '../tools/setup-backends.mjs';
+import { reconcileSettings } from '../tools/bridge-settings.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -467,6 +468,20 @@ const main = async () => {
     }
   }
 
+  // Bridge settings reconcile — LOCAL files only, AFTER the bridge refresh, BEFORE the network
+  // cascade. Reads the deployed host settings file and validates its keys against the bundled
+  // manifests that just landed; it NEVER edits the file (D2 — the file lives outside every kit tree,
+  // so upgrade-survival is structural), only STATES unknown/retired keys (preserved verbatim). Rides
+  // with the bridge gate: --no-bridges / win32 skip it. Best-effort — any error is a warning + exit 0.
+  if (!args.noBridges && process.platform !== 'win32') {
+    try {
+      const { lines } = reconcileSettings();
+      for (const l of lines) console.log(l);
+    } catch (err) {
+      console.warn(`[agent-workflow-kit] could not reconcile the bridge settings file (${err.message}) — continuing; the kit itself IS installed and works.`);
+    }
+  }
+
   // Memory substrate refresh — AFTER the kit + launchers, BEFORE the (fatal) engine and the success
   // block, so a returning `init` leaves no stale memory. Unlike the engine, a memory miss is a
   // DEGRADED success: warn with the exact recovery command + the on-disk version (read crash-proof)

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.2.0'
+  version: '2.3.0'
 ---
 
 # antigravity-cli-bridge
@@ -88,6 +88,18 @@ yourself. Wrapper inputs: first argument is the prompt (`text`, `-` for stdin, o
 `AGY_HARD_TIMEOUT` → hard `timeout(1)` wall-clock cap (default = `AGY_TIMEOUT`); extra `agy` flags
 after `--`. Full detail: [`references/models-and-flags.md`](references/models-and-flags.md).
 
+## Settings file (host-level, survives kit upgrades)
+
+`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` holds `KEY=VALUE` lines,
+**parsed, never sourced** — a file line can never execute code. Precedence: explicit env (even
+empty — `KEY=` disables a knob for one run) > file > built-in default. File-settable keys for this
+bridge: `AGY_HARD_TIMEOUT` (duration string, e.g. `5m`/`30m`) and `AGY_REVIEW_ALLOW_ADDDIR`
+(`0`/`1`; arming the oversized `--add-dir` escape re-enables the Issue-001 stall risk — the hard
+timeout bounds it) — exactly the manifest `settings` block (the single source; the wrapper
+constants and `--help` are drift-guarded against it). Model keys are **not** file-settable. The
+file lives **outside every kit-managed tree**, so a kit refresh/upgrade can never wipe it; edit it
+by hand or via `/agent-workflow-kit bridge-settings` (preview-first, consent-gated).
+
 ## Review mode (`agy-review`)
 
 For a **code / plan / diff review**, drive the dedicated **`agy-review`** wrapper

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

@@ -86,6 +86,11 @@ Receipt:
   payload; a continuation receipt is fresh:false (informational-only — it cannot attest the
   folded tree); 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
+  AGY_HARD_TIMEOUT — hard wall-clock cap, duration string like 5m/30m/90s (built-in default 30m)
+  AGY_REVIEW_ALLOW_ADDDIR — boolean 0/1: 1 arms the oversized --add-dir escape (re-enables the Issue-001 stall risk; default 0)
+
 Closed grammar: unknown flags are rejected; no '--' passthrough (the only escapes are AGY_PROBE=1 and AGY_REVIEW_ALLOW_ADDDIR=1).
 Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
 HELP
@@ -93,11 +98,101 @@ HELP
     ;;
 esac
 
+# This wrapper's applied settings-file subset (see the shared reader block below).
+AW_SETTINGS_APPLIED="AGY_HARD_TIMEOUT AGY_REVIEW_ALLOW_ADDDIR"
+
+# --- Bridge settings file (host-level, kit-independent) — byte-identical across the four wrappers ---
+# ${XDG_CONFIG_HOME:-$HOME/.config}/agent-workflow/bridge-settings.conf holds KEY=VALUE lines,
+# PARSED (grep/case), NEVER sourced — a file line can never execute code. Precedence: explicit
+# env (even empty: KEY= disables the knob for one run) > file > built-in default. Each wrapper
+# APPLIES only its own subset ($AW_SETTINGS_APPLIED, set above this block) but RECOGNIZES the
+# whole registry: a key belonging to another wrapper or another bridge is skipped silently; only
+# a key unknown to the entire registry warns (once per key), naming this file as the source.
+# A malformed line warns and is ignored; a value failing the key's typed validation warns and
+# falls back to the built-in default (never passed to the binary); duplicate key → the LAST
+# occurrence wins; a missing file is silent; an existing-but-unreadable or non-regular file
+# warns loudly and falls back to built-in defaults (a directory or FIFO is never opened).
+# Diagnostics are emitted once per user-visible run: a delegating wrapper (agy-review →
+# agy-run) exports AW_SETTINGS_NOTIFIED so the child never repeats the same file's warnings.
+# The registry, per-wrapper subsets, and typed constants mirror
+# the bridges' capability.json `settings` blocks (manifest-as-source, drift-guarded by tests).
+aw_settings_file() {
+  printf '%s/agent-workflow/bridge-settings.conf' "${XDG_CONFIG_HOME:-$HOME/.config}"
+}
+aw_settings_known() {
+  case " CODEX_SERVICE_TIER CODEX_HARD_TIMEOUT CODEX_REVIEW_MAX_TOTAL_BYTES AGY_HARD_TIMEOUT AGY_REVIEW_ALLOW_ADDDIR " in
+    *" $1 "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+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 )) ;;
+    AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
+    AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
+    *) return 1 ;;
+  esac
+}
+aw_apply_settings() {
+  local file line key value warned notify
+  file="$(aw_settings_file)"
+  [[ -e "$file" ]] || return 0
+  notify=1
+  [[ -n "${AW_SETTINGS_NOTIFIED:-}" ]] && notify=0
+  export AW_SETTINGS_NOTIFIED=1
+  if [[ ! -f "$file" || ! -r "$file" ]]; then
+    if (( notify )); then
+      echo "warning: bridge settings file '$file' exists but is unreadable or not a regular file — using built-in defaults." >&2
+    fi
+    return 0
+  fi
+  if (( notify )); then
+    warned=" "
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "${line//[[:space:]]/}" ]] && continue
+      case "${line#"${line%%[![:space:]]*}"}" in "#"*) continue ;; esac
+      if [[ ! "$line" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+        echo "warning: malformed line in bridge settings file '$file' (ignored): $line" >&2
+        continue
+      fi
+      key="${line%%=*}"
+      if ! aw_settings_known "$key"; then
+        case "$warned" in
+          *" $key "*) : ;;
+          *)
+            warned="$warned$key "
+            echo "warning: unknown key '$key' in bridge settings file '$file' (ignored)." >&2
+            ;;
+        esac
+      fi
+    done <"$file"
+  fi
+  for key in $AW_SETTINGS_APPLIED; do
+    if [[ -n "${!key+x}" ]]; then continue; fi
+    value="$(grep "^${key}=" "$file" 2>/dev/null || true)"
+    [[ -n "$value" ]] || continue
+    value="${value##*$'\n'}"
+    value="${value#*=}"
+    if ! aw_settings_valid "$key" "$value"; then
+      if (( notify )); then
+        echo "warning: invalid value '$value' for $key in bridge settings file '$file' — using the built-in default." >&2
+      fi
+      continue
+    fi
+    export "$key=$value"
+  done
+  return 0
+}
+aw_apply_settings
+
 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.2.0"
+AW_BRIDGE_VERSION="2.3.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.

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

@@ -637,7 +637,7 @@ describe('agy-review.sh — declared contract is really accepted (forward guard)
 // The normative fixture (docs: the AD-038 plan Decisions — copied verbatim; 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.2.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"}',
 );
 const RECEIPTS_REL = join('.git', 'agent-workflow-review-receipts.jsonl');
 const readReceipts = (repo) => {
@@ -793,3 +793,206 @@ describe('agy-review.sh — review receipts (AD-038)', () => {
     assert.equal(receipts.length, 0, 'no review ran — no receipt');
   });
 });
+
+// ── 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
+// knob) > file > built-in default. agy-review APPLIES AGY_HARD_TIMEOUT +
+// AGY_REVIEW_ALLOW_ADDDIR and RECOGNIZES the whole registry. HOME is the sandbox home,
+// so the default path is hermetic per test.
+
+const writeSettings = (sb, text) => {
+  const dir = join(sb.home, '.config', 'agent-workflow');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, 'bridge-settings.conf');
+  writeFileSync(file, text);
+  return file;
+};
+const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+
+describe('agy-review.sh — bridge settings file (bridges 2.3.0)', () => {
+  it('a file-set AGY_REVIEW_ALLOW_ADDDIR=1 arms the oversized --add-dir escape', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'unique.txt'), `OVERSIZE_UNIQUE_MARKER\n${'x'.repeat(8000)}\n`);
+    writeSettings(sb, 'AGY_REVIEW_ALLOW_ADDDIR=1\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_MAX_PROMPT_BYTES: '2000' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.invoked, true, 'the file-armed escape lets the run proceed');
+    assert.match(r.argv, /--add-dir/);
+    assert.match(r.stderr, /RE-ENABLES the Issue-001 stall risk/);
+  });
+
+  it('env overrides file: AGY_REVIEW_ALLOW_ADDDIR env=0 file=1 → the refusal stands', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'unique.txt'), `MARKER\n${'x'.repeat(8000)}\n`);
+    writeSettings(sb, 'AGY_REVIEW_ALLOW_ADDDIR=1\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_MAX_PROMPT_BYTES: '2000', AGY_REVIEW_ALLOW_ADDDIR: '0' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, r.stderr);
+    assert.match(r.stderr, /over AGY_MAX_PROMPT_BYTES=2000/);
+    assert.equal(r.invoked, false);
+  });
+
+  it('an EXPLICITLY EMPTY env (AGY_REVIEW_ALLOW_ADDDIR=) disables the file knob', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'unique.txt'), `MARKER\n${'x'.repeat(8000)}\n`);
+    writeSettings(sb, 'AGY_REVIEW_ALLOW_ADDDIR=1\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_MAX_PROMPT_BYTES: '2000', AGY_REVIEW_ALLOW_ADDDIR: '' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, 'env wins over file — empty means knob off (built-in default 0)');
+    assert.equal(r.invoked, false);
+  });
+
+  it('an invalid boolean warns and falls back to the built-in default (refusal stands)', () => {
+    const sb = makeSandbox();
+    writeFileSync(join(sb.repo, 'unique.txt'), `MARKER\n${'x'.repeat(8000)}\n`);
+    writeSettings(sb, 'AGY_REVIEW_ALLOW_ADDDIR=yes\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_MAX_PROMPT_BYTES: '2000' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 2, r.stderr);
+    assert.match(r.stderr, /invalid value 'yes'/);
+    assert.equal(r.invoked, false);
+  });
+
+  it('a file-set AGY_HARD_TIMEOUT flows through the agy-run delegation (killed at the file cap)', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'AGY_HARD_TIMEOUT=2s\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '5' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, 'the file cap must apply end-to-end (reader → agy-run → timeout)');
+    assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
+  });
+
+  it("another bridge's valid key is skipped silently", () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'CODEX_SERVICE_TIER=priority\nCODEX_HARD_TIMEOUT=2\nCODEX_REVIEW_MAX_TOTAL_BYTES=100\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stderr, /bridge settings/, 'a recognized non-applied key earns NO warning');
+    assert.equal(r.invoked, true);
+  });
+
+  it('a truly unknown key warns ONCE naming the file; the review is unaffected', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, 'TOTALLY_UNKNOWN=1\nTOTALLY_UNKNOWN=2\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const warns = r.stderr.match(/unknown key 'TOTALLY_UNKNOWN'/g) ?? [];
+    assert.equal(warns.length, 1, `exactly one warning per unknown key, got ${warns.length}`);
+    assert.match(r.stderr, /bridge-settings\.conf/, 'the warning must name the settings file');
+    assert.equal(r.invoked, true);
+  });
+
+  it('malformed lines warn and are ignored; comments and blank lines are silent', () => {
+    const sb = makeSandbox();
+    writeSettings(sb, '# a comment\n\nNOT A KEY VALUE LINE\n');
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    const malformed = r.stderr.match(/malformed line/g) ?? [];
+    assert.equal(malformed.length, 1, 'comments/blank lines must NOT count as malformed');
+    assert.equal(r.invoked, true);
+  });
+
+  it('an existing-but-unreadable file warns loudly and falls back to built-ins', { skip: isRoot }, () => {
+    const sb = makeSandbox();
+    const file = writeSettings(sb, 'AGY_REVIEW_ALLOW_ADDDIR=1\n');
+    chmodSync(file, 0o000);
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /unreadable/);
+    assert.equal(r.invoked, true);
+  });
+
+  it('a settings line can NEVER execute code (command-substitution payload inert)', () => {
+    const sb = makeSandbox();
+    const pwned = join(sb.home, 'pwned');
+    writeSettings(sb, `AGY_HARD_TIMEOUT=$(touch ${pwned})\nEVIL_KEY=\`touch ${pwned}2\`\n`);
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    const executed = existsSync(pwned) || existsSync(`${pwned}2`);
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(executed, false, 'file content must be parsed, never evaluated');
+    assert.equal(r.invoked, true);
+  });
+
+  it('no file → byte-identical behaviour to today (no settings chatter)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stderr, /bridge settings/);
+    assert.equal(r.invoked, true);
+  });
+
+  it('a DIRECTORY at the settings path warns loudly and falls back to built-ins (no crash)', () => {
+    const sb = makeSandbox();
+    mkdirSync(join(sb.home, '.config', 'agent-workflow', 'bridge-settings.conf'), { recursive: true });
+    const r = run(sb, { args: ['code', '--facts', 'f'] });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `a directory must degrade honestly, not kill the run: ${r.stderr}`);
+    assert.match(r.stderr, /unreadable or not a regular file/);
+    assert.doesNotMatch(r.stderr, /Is a directory/, 'no raw bash error may leak');
+    assert.equal(r.invoked, true);
+  });
+});
+
+// ── settings surface ⟷ manifest (drift guard, D6) — same contract as the codex bridge ──
+const SETTINGS_HEADER = 'Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):';
+const SIBLING_MANIFEST = JSON.parse(readFileSync(join(HERE, '..', '..', 'codex-cli-bridge', 'capability.json'), 'utf8'));
+const ALL_SETTINGS = [...(MANIFEST.settings ?? []), ...(SIBLING_MANIFEST.settings ?? [])];
+const SETTINGS_CMD = 'agy-review';
+
+describe('agy-review.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () => {
+  it('--help Settings section keys set-EQUAL the manifest appliesTo subset', () => {
+    const help = runHelp('--help').stdout;
+    const section = helpSection(help, SETTINGS_HEADER);
+    const got = section.filter((l) => /^[A-Z][A-Z0-9_]+ —/.test(l)).map((l) => l.split(' ')[0]);
+    const want = (MANIFEST.settings ?? []).filter((s) => s.appliesTo.includes(SETTINGS_CMD)).map((s) => s.key);
+    assert.ok(want.length > 0, 'the manifest must declare settings for this wrapper');
+    setEq(got, want, 'help Settings keys ⟷ manifest settings.appliesTo');
+    assert.ok(section.some((l) => l.includes('agent-workflow/bridge-settings.conf')), 'the section names the settings file');
+  });
+
+  const source = readFileSync(WRAPPER, 'utf8');
+
+  it('aw_settings_known carries exactly the UNION of both bridges settings keys', () => {
+    const m = source.match(/aw_settings_known\(\) \{\n  case " ([^"]+) " in/);
+    assert.ok(m, 'aw_settings_known registry case not found');
+    assert.ok(ALL_SETTINGS.length >= 5, 'both manifests must contribute settings');
+    setEq(m[1].trim().split(/\s+/), ALL_SETTINGS.map((s) => s.key), 'shell registry ⟷ manifest union');
+  });
+
+  it('AW_SETTINGS_APPLIED equals the manifest appliesTo subset for this wrapper', () => {
+    const m = source.match(/^AW_SETTINGS_APPLIED="([^"]*)"$/m);
+    assert.ok(m, 'AW_SETTINGS_APPLIED not found');
+    const want = ALL_SETTINGS.filter((s) => s.appliesTo.includes(SETTINGS_CMD)).map((s) => s.key);
+    assert.ok(want.length > 0);
+    setEq(m[1].trim().split(/\s+/), want, 'applied subset ⟷ manifest appliesTo');
+  });
+
+  it('aw_settings_valid arms carry the manifest typed constants per key', () => {
+    const body = source.match(/aw_settings_valid\(\) \{[\s\S]*?\n\}/);
+    assert.ok(body, 'aw_settings_valid not found');
+    const armKeys = [...body[0].matchAll(/^    ([A-Z][A-Z0-9_]*)\)/gm)].map((x) => x[1]);
+    setEq(armKeys, ALL_SETTINGS.map((s) => s.key), 'validation arms ⟷ manifest keys');
+    for (const s of ALL_SETTINGS) {
+      const arm = body[0].match(new RegExp(`^    ${s.key}\\) (.*) ;;$`, 'm'));
+      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`);
+      }
+      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') {
+        assert.ok(arm[1].includes('$dur_re'), `${s.key}: duration grammar not pinned`);
+        assert.ok(arm[1].includes('$zero_re'), `${s.key}: zero-duration rejection not pinned (timeout 0 disables the cap)`);
+      }
+    }
+  });
+});