@sabaiway/agent-workflow-kit 1.33.0 → 1.35.0

package/CHANGELOG.md

@@ -4,6 +4,105 @@ 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.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
+stays `1.3.0` — no migration). First contact now interrupts once instead of three times, the
+opt-in accelerators are discoverable from every happy path, and a project's own verification
+commands can be seeded into `docs/ai/gates.json` behind an explicit per-entry yes:
+
+- **F11 — ONE batched setup prompt.** Bootstrap asks the three setup questions (visibility /
+  conversational language / attribution) as one structured multi-question prompt where supported
+  (`AskUserQuestion`, up to 4 questions per call), records each answer individually, and writes
+  nothing until all are answered (`references/modes/bootstrap.md` preamble + steps 2–4;
+  `references/contracts.md` · `references/shared/deploy-tail.md` · `launchers/windsurf-workflow.md`
+  reworded to match). Upgrade batches its two migration asks the same way ONLY when BOTH
+  `AGENTS.md` blocks are missing (a pre-1.1.0 deployment), collects them in step 6 BEFORE the
+  migrations apply, and never re-asks a collected answer (`references/modes/upgrade.md`); the four
+  migration files are untouched — their own ask stays the standalone fallback. New
+  `test/ask-contract.test.mjs` pins the wording across all 7 files and holds the kit↔memory
+  `references/contracts.md` ask paragraph byte-identical (a hand-lockstep pair, deliberately not a
+  sync-mirrors family).
+- **F12 — the installer says what a returning user needs.** `bin/install.mjs` prints a restart
+  hint on every run over a PRE-existing install ("restart the session so the agent reloads the
+  refreshed kit files") — on the verb path, at most once per run, surviving even the fatal
+  engine-install abort — and replaces the false "Claude Code / Codex / Devin Desktop all use the
+  same /agent-workflow-kit" claim with the real per-agent matrix (Codex invokes via its `/skills`
+  menu and may auto-trigger) in `--help` AND the final next-steps block. Pinned in
+  `bin/install.test.mjs`.
+- **F10a — the opt-in funnel is visible.** The welcome-mat ladder
+  (`references/shared/report-footer.md`) gains caveat-aware rungs: velocity when the allowlist is
+  unseeded, `agents` when no cheap-lane vehicle is placed, `hook` when gates are DECLARED
+  (non-empty — file presence alone would misfire on the empty seed) but the hook is unwired; the
+  two new signals ride the existing status envelope (`tools/family-registry.mjs`
+  `surveyCheapAgents` + `surveyGateHook.declaredGates` → `tools/view-model.mjs` →
+  `tools/renderers.mjs` — no new helper call). Bootstrap step 11 ends on a compact
+  optional-accelerators block (velocity · agents · gates seeding + hook · set-recipe;
+  preview-first, nothing runs without a yes), and `help` output gains a matching "Tune" tail
+  (`tools/commands.mjs` — no new mode, no new kind; the router SKILL.md is untouched). New
+  `test/report-footer-rotation.test.mjs` pins one shorthand ladder literal across
+  upgrade + bootstrap; the `gate-approve-hook` fixture is refreshed to the live 10-gate shape.
+- **F10b — the consent-gated `gates.json` seeder (the seeding↔hook trust chain).** New
+  `tools/seed-gates.mjs`: dry-run by default (prints the derived `{ id, title, cmd }` entries,
+  writes NOTHING; declining leaves the file byte-identical); `--apply [--only <id>]…` appends
+  exactly the consented entries — append-only (never modifies or removes an existing entry),
+  id-collision refusal, validator-checked (it imports the runner's `validateDeclaration`; the
+  runner never imports it), stamp-gated apply, and OUTSIDE every velocity tier (a consent-per-run
+  writer is never pre-approved). Offered candidates are terminating verification classes only
+  (test / lint / type-check / build) — release/publish/deploy scripts, watch/serve modes, and
+  MUTATING variants (`lint:fix`, `test:update`, bodies carrying `--fix`/`--write`/`-w`/`-u`)
+  never enter the offer; commands are package-manager-aware (npm/pnpm/yarn). The review-state
+  candidate is included ONLY when `docs/ai/orchestration.json` declares reviewed/council on
+  `plan-execution.review` (the slot the checker enforces), with the resolved QUOTED path. Every
+  preview prints the trust-chain disclosure: the hook auto-approves byte-exact declared commands —
+  seeding and hook wiring are two separate consents. The hardened atomic write core is extracted
+  into `tools/atomic-write.mjs` (exclusive-create tmp+rename, TOCTOU re-check, symlink STOPs) and
+  shared with `tools/orchestration-write.mjs` (public API unchanged). The consent-seed protocol
+  lives in `references/modes/gates.md`; `references/modes/review-state.md` step 3 now names the
+  seeder path ("by hand OR the explicit-consent seeder — never without consent").
+- **AD-039 amendment (documented, AD-042):** `test/router-contract.test.mjs` `routerPlusMode`
+  28672 → 29696 — the F11 upgrade batching caveat is +422 B of new contract text against 154 B of
+  headroom; the router itself is byte-identical. Tarball 116 → 118 files
+  (`test/package-content.test.mjs` count + payload pins for the seeder pair).
+
 ## 1.33.0 — The agent-rules lens region: render + reconcile from the engine canon (AD-041)
 
 A **feature** release (new shipped tool + wiring; deployment-lineage head stays `1.3.0` — the

package/README.md

@@ -234,12 +234,13 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
-| `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand** (never auto-seeded). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
+| `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
 | `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/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,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.33.0'
+  version: '1.35.0'
 ---
 
 # agent-workflow-kit
@@ -75,7 +75,7 @@ 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:**
@@ -141,6 +141,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.

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, '..');
@@ -303,7 +304,8 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
 After install, invoke the skill in your agent, inside a project:
   first time in the project  ->  /agent-workflow-kit
   project already has it     ->  /agent-workflow-kit upgrade
-  (Claude Code / Codex / Devin Desktop all use the same /agent-workflow-kit.)
+  Per agent: Claude Code -> /agent-workflow-kit; Devin Local -> /agent-workflow-kit;
+  Codex -> its /skills menu -> agent-workflow-kit (Codex may also auto-trigger it).
 
 Re-running this npx command updates the kit's own files; /agent-workflow-kit
 upgrade then migrates a project's deployment to that version.`);
@@ -388,6 +390,23 @@ const main = async () => {
     : 'installed';
   console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
 
+  // F12 restart hint — any run over a PRE-EXISTING install (every cmp outcome, incl. the legacy
+  // unstamped one) leaves an already-open agent session still holding the PREVIOUS kit files in
+  // memory (mirrors the SKILL.md "restart the session" note the memory-miss paths already carry).
+  // Printed AT MOST ONCE per run: here on the verb path — so it survives the fatal engine abort
+  // below — with the final next-steps block as the carrier only if this line did not print.
+  const restartHintState = { pending: wasPresent };
+  const printRestartHint = () => {
+    if (!restartHintState.pending) return;
+    restartHintState.pending = false;
+    console.log(
+      `[agent-workflow-kit] the kit was already installed here — an agent session that was ` +
+        `already open is still running the previous kit files; restart the session so the agent ` +
+        `reloads the refreshed kit files.`,
+    );
+  };
+  printRestartHint();
+
   // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
   // it restores locally modified/deleted files), and whether npx served a cached build is NOT
   // observable here (no network), so the note never claims it; the @latest hint is conditional.
@@ -449,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)
@@ -506,10 +539,13 @@ const main = async () => {
   // This command (de)installed the *kit* globally. Deploying it into a project is a
   // separate, in-agent step — and which sub-command depends on whether that project
   // already has the kit. Spell both out so it's unambiguous (see README "Use").
+  printRestartHint(); // carrier fallback — a no-op when the verb path already printed it
   console.log(`
 Next — open your agent inside a project and run the skill:
   • first time in this project  ->  /agent-workflow-kit
   • project already has the kit  ->  /agent-workflow-kit upgrade
+  • per agent: Claude Code -> /agent-workflow-kit · Devin Local -> /agent-workflow-kit ·
+    Codex -> its /skills menu -> agent-workflow-kit (Codex may also auto-trigger it)
 
 This command only installs/updates the kit itself (in ${tildify(target)}).
 To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`);

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)`);
+      }
+    }
+  });
+});