@sabaiway/agent-workflow-kit 1.33.0 → 1.35.0

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

@@ -50,6 +50,10 @@ Usage:
   agy-run @path/to/prompt.md
   agy-run <prompt|-|@file> -- <extra agy flags...>
 
+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 = AGY_TIMEOUT, 5m)
+
 Environment: AGY_MODEL (exact display string from `agy models`; empty ⇒ agy's settings.json), AGY_TIMEOUT / AGY_HARD_TIMEOUT (duration strings), AGY_MAX_PROMPT_BYTES (single-argv byte ceiling; the override only lowers it).
 Requires at run time: the agy CLI on PATH + a Google AI subscription login (--help needs neither).
 HELP
@@ -68,6 +72,96 @@ while IFS= read -r _api_key_var; do
   unset "$_api_key_var" 2>/dev/null || true
 done < <(compgen -v 2>/dev/null | grep '_API_KEY$' || true)
 
+# This wrapper's applied settings-file subset (see the shared reader block below).
+AW_SETTINGS_APPLIED="AGY_HARD_TIMEOUT"
+
+# --- 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
+
 if ! command -v agy >/dev/null 2>&1; then
   echo "error: 'agy' (Antigravity CLI) not found on PATH. Install it and run 'agy' once to sign in." >&2
   exit 127

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

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, existsSync, readdirSync, symlinkSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -208,3 +208,247 @@ describe('agy.sh — --help (pre-preflight, candidate C)', () => {
     assert.equal(invoked, true, 'the run must proceed to agy with the payload');
   });
 });
+
+// ── 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-run APPLIES only AGY_HARD_TIMEOUT and RECOGNIZES
+// the whole registry. HOME is the sandbox home, so the default path is hermetic per test.
+
+const writeSettings = (home, text) => {
+  const dir = join(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.sh — bridge settings file (bridges 2.3.0)', () => {
+  it('a file-set AGY_HARD_TIMEOUT is effective (killed at the file cap)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
+    writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, 'the file cap must apply when the env is unset');
+    assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
+  });
+
+  it('env overrides file: env=2s file=10m → killed at the env cap', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
+    writeSettings(home, 'AGY_HARD_TIMEOUT=10m\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0, 'the env cap (2s) must win over the file cap (10m)');
+    assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
+  });
+
+  it('an EXPLICITLY EMPTY env (AGY_HARD_TIMEOUT=) disables the file knob for one run', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 3\necho "OK reply"\n');
+    writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
+    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '', AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `built-in default must apply (not the 2s file cap): ${r.stderr}`);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('duplicate key → the LAST occurrence wins (10m then 2s → killed at 2s)', () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
+    writeSettings(home, 'AGY_HARD_TIMEOUT=10m\nAGY_HARD_TIMEOUT=2s\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
+  });
+
+  it('an invalid duration warns and falls back to the built-in default', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    writeSettings(home, 'AGY_HARD_TIMEOUT=abc\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /invalid value 'abc'/);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('a bare-integer duration (no unit suffix) is invalid → warn + built-in default', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    writeSettings(home, 'AGY_HARD_TIMEOUT=90\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /invalid value '90'/, 'duration values require a unit suffix (5m/30m/90s)');
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('a ZERO duration is invalid — timeout 0 would silently DISABLE the hard cap', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    writeSettings(home, 'AGY_HARD_TIMEOUT=0s\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /invalid value '0s'/, 'a persistent settings line must never remove the stall guard');
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('a DIRECTORY at the settings path warns loudly and falls back to built-ins (no crash)', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    mkdirSync(join(home, '.config', 'agent-workflow', 'bridge-settings.conf'), { recursive: true });
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(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.match(r.stdout, /OK reply/);
+  });
+
+  it("another bridge's valid key is skipped silently (and never applied)", () => {
+    const home = makeSandbox('#!/usr/bin/env bash\nsleep 3\necho "OK reply"\n');
+    writeSettings(home, 'CODEX_SERVICE_TIER=priority\nCODEX_HARD_TIMEOUT=2\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, `a codex key must not cap an agy run: ${r.stderr}`);
+    assert.doesNotMatch(r.stderr, /bridge settings/, 'a recognized non-applied key earns NO warning');
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('a truly unknown key warns ONCE naming the file; the run is unaffected', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    writeSettings(home, 'TOTALLY_UNKNOWN=1\nTOTALLY_UNKNOWN=2\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(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.match(r.stdout, /OK reply/);
+  });
+
+  it('malformed lines warn and are ignored; comments and blank lines are silent', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    writeSettings(home, '# a comment\n\nNOT A KEY VALUE LINE\n');
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(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.match(r.stdout, /OK reply/);
+  });
+
+  it('an existing-but-unreadable file warns loudly and falls back to built-ins', { skip: isRoot }, () => {
+    const home = makeSandbox(RECORDING_STUB);
+    const file = writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
+    chmodSync(file, 0o000);
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stderr, /unreadable/);
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('a settings line can NEVER execute code (command-substitution payload inert)', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    const pwned = join(home, 'pwned');
+    writeSettings(home, `AGY_HARD_TIMEOUT=$(touch ${pwned})\nEVIL_KEY=\`touch ${pwned}2\`\n`);
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    const executed = existsSync(pwned) || existsSync(`${pwned}2`);
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(executed, false, 'file content must be parsed, never evaluated');
+    assert.match(r.stdout, /OK reply/);
+  });
+
+  it('no file → byte-identical behaviour to today (no settings chatter)', () => {
+    const home = makeSandbox(RECORDING_STUB);
+    const r = runWrapper(home, { AGY_MODEL: '' });
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stderr, /bridge settings/);
+    assert.match(r.stdout, /OK reply/);
+  });
+});
+
+// ── settings surface ⟷ manifest (drift guard, D6) ────────────────────────────────
+// agy-run's --help stays candidate-C (not contract-pinned), but its SETTINGS surface
+// is manifest-pinned like the other three wrappers: the Settings help section and the
+// shell constants (registry / applied subset / typed validation arms) stay set-equal
+// to the bridges' capability.json `settings` blocks. The sibling manifest path
+// resolves identically in the repo layout and in the kit's bridges/ mirror layout.
+const SETTINGS_HEADER = 'Settings file (KEY=VALUE, parsed never sourced; env wins over file, file wins over built-in default):';
+const MANIFEST = JSON.parse(readFileSync(join(HERE, '..', 'capability.json'), 'utf8'));
+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-run';
+const setEq = (got, want, msg) => assert.deepEqual([...got].sort(), [...want].sort(), msg);
+const helpSection = (text, header) => {
+  const lines = text.split('\n');
+  const i = lines.findIndex((l) => l.trim() === header);
+  assert.notEqual(i, -1, `--help must carry a "${header}" section`);
+  const out = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (lines[j].trim() === '') break;
+    out.push(lines[j].trim());
+  }
+  return out;
+};
+
+describe('agy.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () => {
+  const runHelpText = () => {
+    const home = mkdtempSync(join(tmpdir(), 'agy-settings-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('--help Settings section keys set-EQUAL the manifest appliesTo subset', () => {
+    const section = helpSection(runHelpText(), 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)`);
+      }
+    }
+  });
+});

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

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "provides": ["review", "probe"],
   "roles": {
     "review": {
@@ -33,6 +33,22 @@
     },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
   },
+  "settings": [
+    {
+      "key": "AGY_HARD_TIMEOUT",
+      "kind": "duration",
+      "default": null,
+      "appliesTo": ["agy-run", "agy-review"],
+      "effect": "hard wall-clock cap via timeout(1), duration string (e.g. 5m, 30m, 90s); built-in default: agy-run = AGY_TIMEOUT (5m), agy-review 30m."
+    },
+    {
+      "key": "AGY_REVIEW_ALLOW_ADDDIR",
+      "kind": "boolean",
+      "default": "0",
+      "appliesTo": ["agy-review"],
+      "effect": "1 ⇒ an oversized code review offloads the change set to a private --add-dir staging dir (re-enables the Issue-001 stall risk; the hard timeout bounds it). Default 0: an oversized prompt refuses instead."
+    }
+  ],
   "detect": {
     "installed": {
       "env": "ANTIGRAVITY_CLI_BRIDGE_DIR",

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

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.2.0'
+  version: '2.3.0'
 ---
 
 # codex-cli-bridge
@@ -109,6 +109,7 @@ defeat a policy is guarded — see [§ Models](#models-quality-first-pinned).
 | `CODEX_MODEL` | `gpt-5.5` (pinned) | model; non-default REFUSED unless `CODEX_PROBE=1` |
 | `CODEX_EFFORT` | `xhigh` (pinned) | reasoning effort; non-default REFUSED unless `CODEX_PROBE=1` |
 | `CODEX_HARD_TIMEOUT` | `3600` (exec) / `1800` (review) | hard wall-clock cap (seconds) via `timeout`/`gtimeout`; exit 124/137 ⇒ "exceeded hard cap". No `timeout` binary ⇒ loud warning + uncapped (never silent). |
+| `CODEX_SERVICE_TIER` | unset (standard tier) | **SPEND knob**: `priority` (catalog name "Fast") = ~1.5× token speed at a **2.5× credit rate** on gpt-5.5 — quality-neutral (same model). codex accepts any `-c service_tier` string silently (probe-pinned 2026-07-05), so the wrapper validates: an unsupported value warns and runs standard. Env or settings file. |
 | `CODEX_SESSION_FILE` | `./.codex-last-session` | where `codex-exec` records the session id and where `--resume-last` reads it |
 | `CODEX_REVIEW_MAX_TOTAL_BYTES` | `1500000` | `codex-review code`: above this the assembled diff goes via a git-dir temp file instead of inline — never truncated |
 | `CODEX_REVIEW_SCHEMA` | unset | `codex-review`: `=1` returns findings as a validated JSON object (`--output-schema`), with a raw-text fallback. Default off. |
@@ -117,6 +118,19 @@ defeat a policy is guarded — see [§ Models](#models-quality-first-pinned).
 The git-write shim, `--ignore-user-config`, and the `*_API_KEY` scrub are NOT env-tunable — they are
 fixed invariants.
 
+### 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: `CODEX_SERVICE_TIER` (the Fast tier — **2.5× credit rate**; enabling it is a consented
+per-host spend decision, never a default), `CODEX_HARD_TIMEOUT`, `CODEX_REVIEW_MAX_TOTAL_BYTES` —
+exactly the manifest `settings` block (the single source; the wrapper constants and `--help` are
+drift-guarded against it). Model/effort keys are **not** file-settable — the quality guard above
+is untouched. 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).
+
 ## Project context (how `codex` sees the repo)
 
 `codex` auto-**merges** `AGENTS.md` (root→cwd, plus a global `~/.codex/AGENTS.md`) straight into its

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

@@ -67,6 +67,11 @@ Guarded passthrough after '--':
   blocked always: -c* --config* -s* --sandbox* --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust --full-auto --oss --local-provider* -p* --profile* -m* --model* -o* --output-last-message* --json* --color* --output-schema* --ephemeral*
   relaxed only under CODEX_PROBE=1: --add-dir* -C* --cd* --skip-git-repo-check --ignore-rules --enable* --disable*
 
+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
+  CODEX_SERVICE_TIER — service tier: 'priority' (Fast — ~1.5x speed at a 2.5x credit rate on gpt-5.5); a consented SPEND knob, default off (standard tier)
+  CODEX_HARD_TIMEOUT — hard wall-clock cap, integer seconds 1..86400 (built-in default 3600)
+
 Environment: CODEX_HARD_TIMEOUT (seconds, default 3600), CODEX_PROBE=1 (throwaway probe only).
 Requires at run time: the codex CLI on PATH, a ChatGPT-subscription login, a git work tree with a root AGENTS.md (--help needs none of these).
 HELP
@@ -74,6 +79,96 @@ HELP
     ;;
 esac
 
+# This wrapper's applied settings-file subset (see the shared reader block below).
+AW_SETTINGS_APPLIED="CODEX_SERVICE_TIER CODEX_HARD_TIMEOUT"
+
+# --- 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_CODEX_MODEL="gpt-5.5"   # frontier coding model (verified locally) — pinned
 DEFAULT_CODEX_EFFORT="xhigh"    # maximum reasoning effort — pinned
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
@@ -82,6 +177,22 @@ CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # varies — a trivial reply was observed taking minutes). Raise for a known-healthy
 # long run; lowering it only risks killing real work.
 CODEX_HARD_TIMEOUT="${CODEX_HARD_TIMEOUT:-3600}"
+# Codex service tier (quality-neutral speed knob; live-probed 2026-07-05): default EMPTY ⇒ no
+# service_tier flag (standard tier) — enabling Fast is a consented per-host SPEND act, never a
+# silent default. The only server-catalog tier id on this subscription is 'priority' (catalog
+# display name "Fast": ~1.5x token speed at a 2.5x credit rate on gpt-5.5; quality-neutral —
+# same model). codex itself accepts ANY -c service_tier string silently (probe-verified), so
+# the wrapper validates the effective value: an unsupported one warns and runs on the standard
+# tier — a typo can never silently masquerade as Fast.
+CODEX_SERVICE_TIER="${CODEX_SERVICE_TIER:-}"
+if [[ -n "$CODEX_SERVICE_TIER" ]] && ! aw_settings_valid CODEX_SERVICE_TIER "$CODEX_SERVICE_TIER"; then
+  echo "warning: CODEX_SERVICE_TIER='$CODEX_SERVICE_TIER' is not a supported service tier ('priority') — running on the standard tier." >&2
+  CODEX_SERVICE_TIER=""
+fi
+tier_flags=()
+if [[ -n "$CODEX_SERVICE_TIER" ]]; then
+  tier_flags=(-c "service_tier=$CODEX_SERVICE_TIER")
+fi
 CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
 
 # --- Quality-first guard: refuse a silent model/effort downgrade ---------------
@@ -371,6 +482,7 @@ if [[ -n "$resume_mode" ]]; then
     -c sandbox_workspace_write.network_access=false
     -c hide_agent_reasoning=true
     -c model_reasoning_summary=none
+    "${tier_flags[@]+"${tier_flags[@]}"}"
     -)
   full_prompt="$RESUME_REMINDER"$'\n\n'"$task"
 else
@@ -386,6 +498,7 @@ else
     -c model_reasoning_effort="$CODEX_EFFORT"
     -c hide_agent_reasoning=true
     -c model_reasoning_summary=none
+    "${tier_flags[@]+"${tier_flags[@]}"}"
     --color never
     -o "$out"
     --json