@sabaiway/agent-workflow-kit 14.20.0 → 14.21.0

package/bridges/codex-cli-bridge/references/driving-codex.md

@@ -18,26 +18,29 @@ judgment.
 4. Let codex run; then **review its diff yourself** and re-run the project's gates.
 5. **Commit yourself** — codex never commits (a git-write shim enforces it; see below).
 
-## Quality-first: model & effort are pinned
-
-Delegated codex work ALWAYS runs on the PINNED model at the pinned effort: `gpt-6-astra` / `high` are **pinned**
-and a non-default `CODEX_MODEL`/`CODEX_EFFORT` is **refused** (exit 2). That the pinned id is still the
-strongest selectable model is a hand-checked claim with no automated gate and no recorded date — see
-SKILL.md. Do not try to "tune down" the
-model or effort for a real run — the wrapper will stop you. Quota is metered in **messages** (rolling
-5h + weekly), so economy comes from removing waste (clean capture, the precomputed review diff, resume),
-never from a downgrade. The only opt-out is a throwaway, effort-independent probe: `CODEX_PROBE=1`
-(loud) — never use its output as real work.
+## Model & effort: the host posture
+
+Delegated codex work runs on the host posture: `CODEX_MODEL` / `CODEX_EFFORT` from the bridge settings
+file, else the built-in default `gpt-6.1-sol` / `high`, checked against the installed CLI's catalog
+before any spend. `/agent-workflow-kit bridge-settings` shows the models the installed codex offers and
+sets the host posture. An environment value off the host posture is a one-off and is **refused** (exit 2)
+with the settings-file remedy unless `CODEX_PROBE=1` — do not "tune down" the model or effort per call;
+a weaker model is the user's choice in the setting. Whether the default is the strongest selectable
+model is a hand-checked claim with no automated gate and no recorded date — see SKILL.md. Quota is
+metered in **messages** (rolling 5h + weekly), so economy comes from removing waste (clean capture, the
+precomputed review diff, resume), never from a per-call downgrade. A probe (`CODEX_PROBE=1`, loud) is
+the one route to a one-off — never use its output as real work; its review receipt never attests.
 
 ## Posture banners — quote them verbatim
 
 Every dispatch states its ACTUAL posture on ONE stderr line: `codex-exec` emits
-`exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> timeout=…`
+`exec posture: model=… effort=… tier=… sandbox=workspace-write session=fresh|resume:<id> source=… timeout=…`
 (fresh and resume alike, only after the resume id is resolved and validated), `codex-review` emits
-`review posture: model=… effort=… tier=… timeout=…`. When you label a dispatch for a user or a
+`review posture: model=… effort=… tier=… source=… timeout=…`. When you label a dispatch for a user or a
 record, **quote the posture banner verbatim** — the banner is the machine-stated posture; a prose
-re-type drifts. The `timeout=` field is **banner-only** (exactly the duration handed to
-`timeout(1)`; on exec `uncapped` when no capping binary is on PATH, while `codex-review` fails
+re-type drifts. The `source=` field (`model:<s>,effort:<s>`, each `default`, `setting` or
+`environment`) and the `timeout=` field are **banner-only** (`timeout=` is exactly the duration handed
+to `timeout(1)`; on exec `uncapped` when no capping binary is on PATH, while `codex-review` fails
 CLOSED pre-spend there) — informational, never part of a receipt or the banner↔receipt parity.
 
 ## Exec vs review
@@ -92,7 +95,7 @@ codex-exec --resume <session-id> <file|->  # explicit session id
 
 Resume continues the SAME codex session, so you avoid re-sending the original context. It runs through
 the wrapper, which **re-establishes every invariant** (subscription-only `*_API_KEY` scrub,
-`--ignore-user-config`, the pinned `gpt-6-astra`/`high`) and **restates the full posture via `-c`** —
+`--ignore-user-config`, the host posture's model/effort) and **restates the full posture via `-c`** —
 because `codex exec resume` resets the sandbox/approval/network posture and rejects `-s`/`--add-dir`/`-C`,
 the wrapper passes `-c sandbox_mode=workspace-write -c approval_policy=never -c
 sandbox_workspace_write.network_access=false` explicitly. A resume takes no passthrough flags and an

package/bridges/codex-cli-bridge/references/sandbox-and-flags.md

@@ -47,7 +47,7 @@ carries the session id) into the run trace, with stderr merged into it; `--color
 `--color`, which stays on the fresh lane), so the resume lane is no longer the odd one out: it used
 to print its final message straight to stdout with the event stream nowhere, which left the very
 mode a nested-sandbox incident fired on without a structured evidence surface. Net effect: the wrapper prints just the final answer. **Reasoning still runs at
-the pinned effort** — quality is unchanged; only the *noise* is dropped. On success `codex-exec` extracts the
+the run's effort** — quality is unchanged; only the *noise* is dropped. On success `codex-exec` extracts the
 session id from the trace and records it to `${CODEX_SESSION_FILE:-./.codex-last-session}` (so
 `--resume-last` can find it) and echoes `session: <id>` to stderr. On a missing/empty final-message
 file it falls back to the trace tail (loud, never silent).
@@ -61,13 +61,16 @@ well-formed item is simply not evidence, never a parse error. See the dual polic
 its loose whole-trace rule, and the successful-run arm demands both tokens inside ONE item whose
 failure is proven.
 
-## Quality-first guard (pinned model & effort)
+## Host posture (model & effort)
 
-The wrappers default `CODEX_MODEL=gpt-6-astra` and `CODEX_EFFORT=high` and **refuse** (exit 2, loud) any
-non-default — delegated work always uses the PINNED model at the pinned effort; quality is never traded for
-quota. (Whether the pinned id is still the strongest selectable model is a hand-checked claim with no
-automated gate — see SKILL.md.) `CODEX_PROBE=1` relaxes this for a throwaway, effort-independent probe only (echoed loudly), and
-a probe still runs on the subscription, in the sandbox, with clean capture.
+The wrappers run on the host posture: `CODEX_MODEL` / `CODEX_EFFORT` from the bridge settings file, else
+the built-in default `gpt-6.1-sol` / `high`, checked pre-spend against the installed CLI's catalog
+(`codex debug models`); `/agent-workflow-kit bridge-settings` shows the models offered and sets one. A model or effort the catalog does not offer, and an environment value off the
+host posture (a one-off), are **refused** (exit 2, loud) with the settings-file remedy; a weaker model
+is the user's choice in the setting, never a per-call downgrade. (Whether the default is the strongest
+selectable model is a hand-checked claim with no automated gate — see SKILL.md.) `CODEX_PROBE=1` is the
+one route to a one-off, for a throwaway probe only (echoed loudly; a nonced `codex-exec` probe one-off
+is refused), and a probe still runs on the subscription, in the sandbox, with clean capture.
 
 ## Passthrough guard (two tiers, after a literal `--`)
 
@@ -75,7 +78,7 @@ a probe still runs on the subscription, in the sandbox, with clean capture.
 
 - **Tier 1 — ALWAYS rejected, even under `CODEX_PROBE=1`:** anything that would defeat the policy or the
   capture — `-c`/`--config`, `-s`/`--sandbox`, `--full-auto`, `--dangerously-bypass-*`, `--oss`,
-  `--local-provider`, `-p`/`--profile`, `-m`/`--model` (the model is pinned via `CODEX_MODEL`), and the
+  `--local-provider`, `-p`/`--profile`, `-m`/`--model` (the model is the host posture or `CODEX_MODEL`), and the
   capture flags `-o`/`--output-last-message`/`--json`/`--color`/`--output-schema`/`--ephemeral`.
 - **Tier 2 — context/discovery knobs, rejected for a real run but allowed under `CODEX_PROBE=1`:**
   `--add-dir`, `-C`/`--cd`, `--skip-git-repo-check`, `--ignore-rules`, `--enable`/`--disable`.
@@ -155,7 +158,7 @@ run starts, so the failure is loud and costs no quota; the wrapper's own test pi
 (`RESUME_ACCEPTED_FLAGS`) precisely because the hermetic fake CLI accepts any argv and cannot answer
 this question. The `codex-exec --resume`/`--resume-last` entrypoint handles the reset: it restates
 the entire policy via `-c` (`sandbox_mode=workspace-write`, `approval_policy=never`,
-`sandbox_workspace_write.network_access=false`) plus the pinned `-m`/effort and
+`sandbox_workspace_write.network_access=false`) plus the host posture's `-m`/effort and
 `--ignore-user-config`, reads the session id from the sidecar (or an argument), and applies the same
 EVIDENCE posture as a fresh run — `-o` for the final message, `--json` into the trace. Only a *raw*
 `codex exec resume` outside the wrapper loses the posture.
@@ -164,7 +167,7 @@ EVIDENCE posture as a fresh run — `-o` for the final message, `--json` into th
 
 A backgrounded/hung run survives otherwise, so both wrappers wrap codex in `timeout`/`gtimeout`
 (`--kill-after=15s`): `CODEX_HARD_TIMEOUT` defaults to **3600s (exec)** / **1800s (review)**, sized for a
-slow run at the pinned effort. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
+slow run at the host posture's effort. Exit 124/137 ⇒ "exceeded the hard cap" (raise the cap or narrow the task). If neither
 `timeout` nor `gtimeout` is on `PATH`, `codex-exec` **warns loudly and runs uncapped** — never a silent
 no-op — while `codex-review` **refuses pre-spend** (the fail-closed hard-timeout preflight).
 
@@ -205,8 +208,9 @@ exec` over the precomputed diff instead, keeping every invariant intact.
 | `-o, --output-last-message <f>` | write ONLY the final message (clean capture) |
 | `--json` | structured event stream (`thread.started` ⇒ session id) |
 | `--output-schema <f>` | constrain output to a JSON schema (`CODEX_REVIEW_SCHEMA=1`) |
-| `-m <model>` | model (wrapper default `gpt-6-astra`, pinned via `CODEX_MODEL`) |
-| `-c model_reasoning_effort=<effort>` | reasoning effort (wrapper default `high`, pinned via `CODEX_EFFORT`) |
+| `-m <model>` | model (the host posture: the `CODEX_MODEL` setting, else `gpt-6.1-sol`) |
+| `-c model_reasoning_effort=<effort>` | reasoning effort (the host posture: the `CODEX_EFFORT` setting, else `high`) |
+| `codex debug models` | the model catalog as JSON `models[]` (`slug`, `visibility`, `priority`, `supported_reasoning_levels`, `default_reasoning_level`) — the wrappers' pre-spend check; reads no stdin (probed on 0.160.0) |
 | `--ignore-user-config` | do NOT load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME` |
 | `--color never` | disable ANSI colour in output |
 

package/bridges/codex-cli-bridge/setup/README.md

@@ -70,9 +70,9 @@ if it reports a missing git work tree or root `AGENTS.md`, run it from a project
 
 - The wrappers are **subscription-only** by design and will not use api-key billing.
 - `codex-exec` runs a **workspace-write** sandbox with **network OFF**; `codex-review` runs
-  **read-only**. They also pin the model/effort (refusing ANY non-pinned model or effort, a stronger
-  one included; whether the pinned id is still the strongest selectable model is a hand-checked claim
-  with no gate — see `../SKILL.md`), enforce a hard
+  **read-only**. They also run on the host posture — `CODEX_MODEL` / `CODEX_EFFORT` from the
+  bridge settings file, else `gpt-6.1-sol` / `high` — checked against the installed CLI's catalog,
+  and refuse a one-off model or effort unless `CODEX_PROBE=1` (see `../SKILL.md`), enforce a hard
   timeout, capture only codex's final message, and block codex from writing git via a shim — see
   [`../references/sandbox-and-flags.md`](../references/sandbox-and-flags.md) and the knob table in
   [`../SKILL.md`](../SKILL.md#environment-knobs). No setup is needed to enable these — they are on by

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.20.0",
+  "version": "14.21.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.20.0",
+  "version": "14.21.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/bridge-settings.md

@@ -4,11 +4,14 @@
 
 The reader + consent-gated **writer** for the **host-level** bridge settings file — the answer to *"turn on the codex Fast tier (or another bridge knob) once, predictably, so it survives kit upgrades."* The four bridge wrappers read `${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf` (`KEY=VALUE` lines, **parsed never sourced**); this is the ONLY writer for it. The file lives **outside every kit-managed tree**, so a kit refresh never writes or clobbers it — upgrade-survival is structural (D2). It **previews by default**; `--apply` writes. Hand-editing the file stays fully supported — this is an offered convenience, never a lock.
 
-**The knobs are the bundled bridges' own `settings` blocks** (manifest-as-source, D6) — the tool never invents a key or a value rule, and what it writes always passes the wrappers' own validation. Model/effort are **NOT** settable here (the wrappers' quality-first guard is untouched, D4). Run **`node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs`** to see the live list; today:
+**The knobs are the bundled bridges' own `settings` blocks** (manifest-as-source, D6) — the tool never invents a key or a value rule, and what it writes always passes the wrappers' own validation. **The model keys set each bridge's host posture** — the model every run of that bridge uses (codex: and its effort); a set one is checked against the models the installed CLI offers **before anything is written**. Run **`/agent-workflow-kit bridge-settings`** (`node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs`) to see the live list and the models on offer; today:
 
 | key | bridge | values | note |
 |---|---|---|---|
-| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: "2x speed, **increased usage**" in the codex catalog's own words for gpt-6-astra (cache fetched 2026-09-05); it states no credit-rate figure; quality-neutral (same model). Default unset ⇒ standard tier. |
+| `CODEX_MODEL` | codex | a model the installed codex offers | the host posture's model; default `gpt-6.1-sol`. |
+| `CODEX_EFFORT` | codex | an effort that model offers | the host posture's reasoning effort; default `high`. |
+| `AGY_MODEL` | agy | a display string the installed agy offers | the host posture's model; default `Gemini 3.8 Flash (High)`. |
+| `CODEX_SERVICE_TIER` | codex | `priority` | **SPEND KNOB** — the "Fast" tier: "2x speed, **increased usage**" in the codex catalog's own words for gpt-6.1-sol (cache fetched 2026-10-03); it states no credit-rate figure; quality-neutral (same model). Default unset ⇒ standard tier. |
 | `CODEX_HARD_TIMEOUT` | codex | integer `1..86400` | hard wall-clock cap (seconds) via `timeout(1)`. |
 | `CODEX_REVIEW_MAX_TOTAL_BYTES` | codex | integer `1..100000000` | codex-review payload size above which the diff rides a temp file (never truncated). |
 | `AGY_HARD_TIMEOUT` | agy | duration `5m`/`30m`/`90s` (unit required, nonzero) | hard wall-clock cap via `timeout(1)`. |
@@ -17,16 +20,16 @@ The reader + consent-gated **writer** for the **host-level** bridge settings fil
 
 **Invocations:**
 
-1. **Read** — `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs [--json]` prints every knob's **effective value + source** (`env` / `file` / `default`) and flags any unknown/duplicate/malformed lines. Read-only.
+1. **Read** — `node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs [--json]` prints every knob's **effective value + source** (`env` / `file` / `default`; a model key's `environment` / `setting` / `default`, as the wrappers' banner names it), each bridge's host posture with the models its installed CLI offers (read with `codex debug models` / `agy models`, never a model run; an unreadable or missing CLI is one stated line, exit 0), and flags any unknown/duplicate/malformed lines. Read-only.
 2. **Preview a change** — `--set KEY=VALUE` (or `--unset KEY`) prints `before → after` and writes **nothing**. Re-run with **`--apply`** to write. Multiple `--set`/`--unset` ops apply in one atomic write.
 3. **`--apply`** writes via the hardened out-of-tree atomic writer (creates the dir + file on first use; symlink/parent/TOCTOU-safe; last-writer-wins). It touches **only** the `KEY=` line it owns — every comment / blank / other line is preserved verbatim.
 
-**Precedence at run time:** explicit env (even empty — `KEY=` disables the knob for one run) **>** this file **>** the wrapper's built-in default. So an operator can always override one run without editing the file; the reader shows which source wins.
+**Precedence at run time:** explicit env (even empty — `KEY=` disables the knob for one run) **>** this file **>** the wrapper's built-in default. So an operator can always override one run without editing the file; the reader shows which source wins. A model key is the exception: an environment value off the host posture is a one-off, which `codex-exec`, `codex-review` and `agy-review` refuse unless it is a probe (the bridge-model contract).
 
-**Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** → exit `2` (nothing read of the file, nothing written). A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
+**Refusals (the guarded contract):** an **unknown key** or an **invalid / out-of-range value** (a model key: empty, padded with whitespace, or carrying a control byte) → exit `2` (nothing read of the file, nothing written). A **model the catalog does not offer**, or a codex **effort that model does not offer**, → exit `2` with the offered list, nothing written; an unreadable catalog leaves the value unchecked and says so. A file that already carries **duplicate keys** → exit `1`, named and left **byte-untouched** (fix the duplicates by hand first — the writer never edits blindly around them). A **symlinked / non-regular / unreadable** settings file → exit `1` (refuses to write through it). `--apply` with `--dry-run`, a duplicate op for one key, or a malformed `--set` → usage exit `2`.
 
-**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs **increased usage** (the catalog states no credit-rate figure) — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset).
+**Spend consent (D4):** enabling `CODEX_SERVICE_TIER=priority` costs **increased usage** (the catalog states no credit-rate figure) — a per-host, consented act, never a default. The preview shows the caveat (from the manifest `effect`); confirm with the user before `--apply`. The tool also warns when an env var currently shadows the key you are writing (the env value wins for that session until unset; for a model key, an environment value off the host posture is a one-off, which `codex-exec`, `codex-review` and `agy-review` refuse unless it is a probe).
 
 Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
 
-**Invariants:** writer (writes only the host settings file — outside any project/kit tree) · never commits · never runs a subscription CLI · previews by default · allowlist + value rules from the bundled manifests · model/effort never settable · the host file survives every kit refresh.
+**Invariants:** writer (writes only the host settings file — outside any project/kit tree) · never commits · never runs a model (only the two read-only catalog commands) · previews by default · allowlist + value rules from the bundled manifests · a model key is judged against its bridge's catalog before any write · the host file survives every kit refresh.

package/references/modes/recipes.md

@@ -12,7 +12,7 @@ The five recipes (defined over each bridge's `provides` roles — `codex`: execu
 - **Delegated** — you hand a **bounded** execution sub-task to a backend (`codex exec`), then review the returned diff and commit.
 - **Subagent** — a **full-tool frontier subagent**, dispatched from the placed executor vehicle (`.claude/agents/executor.md`), carries a **bounded, file-disjoint** slice — of execution, of plan/contract authoring, of an authoring fold, of routine work, of an epic brief (`epic.author`), of a task brief from one ledger row (`task.author`), or of one stamped task brief run inside its Files (`task.execute`); you verify the returned slice by running its suites yourself and you make the commit. It is **never a review backend**, **never a bridge substitute**, and is **never told to commit**; it **degrades to Solo** when the vehicle is `missing` or `unusable`, with the reason. Readiness here is the **vehicle FILE, never the host** — a **Claude Code lane**, like the `agents` writer itself: on a host that cannot dispatch the vehicle, the rendered dispatch form is an instruction you follow by hand and report as such, never as a subagent dispatch.
 
-1. Run **`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs`** (the read-only planner; `--json` for the structured form). It runs the backend detector, lists the five recipes, and prints — for the current environment — a **per-recipe dispatch plan that degrades with a stated reason** when a carrier isn't `ready` (Council → Reviewed → Solo; Delegated → Solo; Subagent → Solo when the executor vehicle is `missing`/`unusable`), plus advisory **quota/health notes** (prefer the cheapest model; Council spends two backends' quota; `agy` may stall on substantive prompts — Issue-001, prefer `codex`).
+1. Run **`node ${CLAUDE_SKILL_DIR}/tools/recipes.mjs`** (the read-only planner; `--json` for the structured form). It runs the backend detector, lists the five recipes, and prints — for the current environment — a **per-recipe dispatch plan that degrades with a stated reason** when a carrier isn't `ready` (Council → Reviewed → Solo; Delegated → Solo; Subagent → Solo when the executor vehicle is `missing`/`unusable`), plus advisory **quota/health notes** (each bridge runs the host posture the user set — a weaker model is the user's bridge setting, never a per-call choice; Council spends two backends' quota; `agy` may stall on substantive prompts — Issue-001, prefer `codex`).
 2. **Offer the choice** via **`AskUserQuestion` where your agent supports it** (`AskUserQuestion` in Claude Code) — one option per recipe, the `recommendRecipe` choice listed **first** — otherwise in prose. Then print `planRecipe(chosen, detection)` (the per-stage dispatch + degradation reasons + quota/health notes) so the user sees exactly what running it entails.
 3. **Availability = `readiness === ready`, full stop.** Every other readiness supplies the human reason (needs-skill → "not installed — `/agent-workflow-kit setup`"; needs-cli → "install the CLI"; needs-credentials → "log in"; degraded → "wrapper not on PATH — `/agent-workflow-kit setup`"). This is set-up state only — **never** a claim that a backend's service is responsive (the detector cannot observe a runtime stall; `agy`'s Issue-001 is a *standing advisory*, not a readiness signal).
 

package/references/modes/review-state.md

@@ -7,7 +7,7 @@ Read-only **review-receipt checker** (AD-038) — it makes *"reviewed ≠ shippe
 Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, the `held session: <id> — <n> fold(s) rode it` / `none` / substitution line when configured delegated execution arms it (with a task `code` thread of backend `codex` in the commit epoch and no unresolved substitution, `held sessions: <k> chain(s) — <label>: <id> (<n>) · …` is printed instead, one entry per chain, labelled by its brief or `untasked`, with `none` for a chain with no held session), and per-backend receipt state (current / stale / ungrounded / probe / rejected / missing) with verdict + grounding + timestamp.
-2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute` or `task.execute` of `delegated` (each read on its own) with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`/`TASK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review runs with the frontier-model/max-effort guard OFF, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
+2. **`--check`** → the gate exit code. Before the review-recipe early return, a configured `plan-execution.execute` or `task.execute` of `delegated` (each read on its own) with a plan in flight and a dirty, fingerprintable tree audits the delegation ledger and refuses a substituted held session; an absent ledger is inert, while an unreadable, malformed, foreign, audit-refused ledger or failed HEAD read fails closed with its own reason. For a head-base thread, the accepted-replacement escape is a `codex-exec` degrade at the substituted return's tree, standing after every later fold, never the review receipt id `codex`. A checkpoint-based thread's substitution closes only by its own ledger `degrade` (which also withdraws the expectation, so the next fold establishes HELD) — no core-evidence degrade lifts it, and the report's recovery hint says so. The remaining **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a CONFIGURED solo recipe (after the held-session arm above) (a computed readiness-degrade NEVER silently becomes solo — it needs the explicit degrade record below), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`/`TASK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a cwd where git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree location that passes — `error`, `redirected`, `no-work-tree` and `env-only` refuse by their state name once a receipt could be required), or every recipe-named backend SATISFIED for the current tree. **A clean-tree PASS under a NON-SOLO review obligation is never silent about a latent arm:** when a `reviewed` or `council` recipe is configured, it NAMES every plan in flight and states that this gate arms as soon as the tree is dirty — the condition is discoverable BEFORE it blocks, instead of surfacing at the worst moment (a pending commit, or the landing of a feature worktree when main first turns dirty). Nothing is announced under a configured `solo` recipe or a not-a-repository cwd, where the gate can never arm. **Satisfaction is ship-class-only on the LATEST NORMAL receipt (D3(b)):** per backend, the latest probe-free current-fingerprint receipt is selected FIRST and THEN verdict-checked — only the recognized ship-class vocabulary (`ship` / `ship with nits`) satisfies; a recognized NEGATIVE (`revise` / `rethink` / `rework`) is an authoritative VETO (an earlier ship never survives a later revise); an UNRECOGNIZED verdict (e.g. `unknown` from a dead run) fails CLOSED unconditionally — a later `unknown` never lets an earlier SHIP stand, and a fresh normal re-run supersedes it. **The ONLY review-backend escape is an explicit degrade RECORD** (`core-evidence.mjs degrade --backend <name> --reason "…"`, fingerprint-bound to the current tree) — and never all backends: ≥1 non-degraded ship-class receipt is required whenever ≥1 backend is configured; a malformed evidence store denies the escape fail-closed but never fails an independently-satisfied tree. Exit 1 otherwise — missing, **stale** (every edit the payload can see moves the fingerprint, and no more), ungrounded, vetoed, or unrecognized. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green. **Probe receipts never attest either:** a `CODEX_PROBE=1` / `AGY_PROBE=1` review is the one route to a one-off model or effort, so the wrapper stamps `probe:true` and this checker excludes it — per receipt, so a real review at the same fingerprint still satisfies. **Silence is not a declaration:** a malformed *or* absent probe marker is rejected fail-closed and stated in the check line. Honest bound: receipts are **not authenticated** (a forger could write `probe:false` as easily as any other field) — like the rest of the receipt this is a self-discipline mechanism, not a security boundary.
 3. **Wire it as a gate by hand OR via the explicit-consent init preview — never without consent (AD-021/D9).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated gates-init preview — `node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>` (dry-run: it prints the derived entries and writes NOTHING; `--apply --only review-state` writes exactly this one on your explicit yes) — offers exactly this entry, path resolved and quoted, ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces). The full consent-fill contract is in `${CLAUDE_SKILL_DIR}/references/modes/gates.md`. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate — and `run-gates --final` requires this check among its canonical core gates.
 4. **`--await [--timeout <s>]`** (BUGFREE-3 / AD-049) → BLOCK until every recipe-named backend is SATISFIED for the current tree (i.e. until `--check` would PASS), or the bounded timeout elapses (a loud exit 1; default 900s). Run it after dispatching the review bridges to WAIT for their receipts to land instead of hand-polling a pid: the durable completion signal is the **receipt**, never a process event (a harness "completed" notification fires early; a bridge's output late-flushes). It inherits the `--check` decision whole — a backend with a current-tree degrade RECORD stops being waited on (the shared decideCheck), so you never hand-`--await` around a known degrade. A held-session refusal and an **AUTHORITATIVE veto terminate the wait loudly BEFORE the deadline**: neither can be moved by waiting; only the held-session retry/degrade lane or a fresh review can move its corresponding refusal. Still read-only (it re-reads the receipts + the evidence store); solo / no-plan / clean-tree resolve instantly. For waiting on **one dispatch's arrival** (never obligation satisfaction) use the receipt-arrival deadline runner, `${CLAUDE_SKILL_DIR}/references/modes/receipt-deadline.md`.
 

package/tools/bridge-catalog.mjs

@@ -0,0 +1,114 @@
+// bridge-catalog.mjs — reads the models each installed bridge CLI offers, exactly as the bridge
+// wrappers read them before a run (spec bridge-model: Catalog check; spec bridge-settings): codex
+// `codex debug models -c model_provider=openai`, the `visibility: list` slugs each with its efforts;
+// agy `agy models`, the display string after the TAB of each line carrying one. Each read runs on the
+// caller's PATH with every *_API_KEY (and, for codex, OPENAI_BASE_URL) removed, so the list is the
+// subscription catalog the runs use. A read is bounded by the wrapper's own constant, then killed with
+// its whole process group after the wrapper's kill grace. Read-only: it runs no model, writes nothing.
+//
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { spawn } from 'node:child_process';
+import { accessSync, statSync, constants } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+
+// The wrappers' constants: codex-exec.sh CODEX_CATALOG_TIMEOUT_S=15, agy.sh AGY_CATALOG_TIMEOUT=30s,
+// both under `timeout --kill-after=5s`.
+export const CATALOG_BOUNDS_MS = Object.freeze({ 'codex-cli-bridge': 15000, 'antigravity-cli-bridge': 30000 });
+export const CATALOG_KILL_GRACE_MS = 5000;
+
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+const unreadable = (cause) => ({ state: 'unreadable', cause, entries: [] });
+
+export const parseCodexCatalog = (text) => {
+  let doc;
+  try { doc = JSON.parse(text); } catch { return unreadable('its output is not JSON'); }
+  if (doc === null || typeof doc !== 'object' || !Array.isArray(doc.models)) return unreadable('it carries no models[]');
+  const offered = doc.models.filter((m) => m !== null && typeof m === 'object' && m.visibility === 'list');
+  if (offered.some((m) => typeof m.slug !== 'string' || m.slug === '' || CONTROL.test(m.slug))) return unreadable('an offered entry carries no usable slug');
+  if (offered.length === 0) return unreadable('it offers no model');
+  const effortsOf = (m) => (Array.isArray(m.supported_reasoning_levels)
+    && m.supported_reasoning_levels.every((l) => l !== null && typeof l === 'object' && typeof l.effort === 'string' && l.effort !== '' && !CONTROL.test(l.effort))
+    ? m.supported_reasoning_levels.map((l) => l.effort) : null);
+  return { state: 'offered', cause: null, entries: offered.map((m) => ({ model: m.slug, efforts: effortsOf(m) })) };
+};
+
+export const parseAgyCatalog = (text) => {
+  const entries = text.split('\n')
+    .map((line) => line.replace(/\r$/u, ''))
+    .filter((line) => line.includes('\t'))
+    .map((line) => line.slice(line.indexOf('\t') + 1))
+    .filter((model) => model !== '' && !CONTROL.test(model))
+    .map((model) => ({ model }));
+  return entries.length ? { state: 'offered', cause: null, entries } : unreadable('it offers no model');
+};
+
+const CLIS = {
+  'codex-cli-bridge': { cli: 'codex', args: ['debug', 'models', '-c', 'model_provider=openai'], parse: parseCodexCatalog, clears: ['OPENAI_BASE_URL'] },
+  'antigravity-cli-bridge': { cli: 'agy', args: ['models'], parse: parseAgyCatalog, clears: [] },
+};
+
+// The environment a catalog read runs in: the caller's, minus every *_API_KEY and the bridge's own
+// base-URL variable — the variables the wrapper's subscription guard clears before its own read.
+export const catalogEnv = (name, getenv) => Object.fromEntries(Object.entries(getenv)
+  .filter(([key]) => !/_API_KEY$/u.test(key) && !(CLIS[name]?.clears ?? []).includes(key)));
+
+const resolveOnPath = (cli, env) => {
+  for (const dir of String(env.PATH ?? '').split(delimiter)) {
+    if (!dir || !isAbsolute(dir)) continue;
+    const candidate = join(dir, cli);
+    try {
+      if (!statSync(candidate).isFile()) continue;
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch { /* not this directory */ }
+  }
+  return null;
+};
+
+const killGroup = (child, signal) => {
+  try { process.kill(-child.pid, signal); } catch { try { child.kill(signal); } catch { /* already gone */ } }
+};
+
+const readOne = (name, ctx) => new Promise((done) => {
+  const spec = CLIS[name];
+  if (!spec) return done(unreadable(`no catalog reader for ${name}`));
+  const env = catalogEnv(name, ctx.getenv ?? process.env);
+  const bin = resolveOnPath(spec.cli, env);
+  if (bin === null) return done({ state: 'not-installed', cause: `${spec.cli} is not on PATH`, entries: [] });
+  const boundMs = ctx.catalogBoundsMs?.[name] ?? CATALOG_BOUNDS_MS[name];
+  const graceMs = ctx.catalogKillGraceMs ?? CATALOG_KILL_GRACE_MS;
+  const label = `${spec.cli} ${spec.args.slice(0, name === 'codex-cli-bridge' ? 2 : 1).join(' ')}`;
+  const chunks = [];
+  let timedOut = false;
+  let settled = false;
+  let bound;
+  let kill;
+  const finish = (result) => { if (!settled) { settled = true; clearTimeout(bound); clearTimeout(kill); done(result); } };
+  // spawn THROWS for an execve errno it does not emit (ETXTBSY: the binary is being replaced).
+  let child;
+  try {
+    child = spawn(bin, spec.args, { env, stdio: ['ignore', 'pipe', 'ignore'], detached: process.platform !== 'win32' });
+  } catch (err) {
+    return finish(unreadable(`${label} could not start (${err.code ?? err.message})`));
+  }
+  bound = setTimeout(() => {
+    timedOut = true;
+    killGroup(child, 'SIGTERM');
+    kill = setTimeout(() => killGroup(child, 'SIGKILL'), graceMs);
+  }, boundMs);
+  child.stdout?.on('data', (chunk) => chunks.push(chunk));
+  child.on('error', (err) => finish(unreadable(`${label} could not start (${err.code ?? err.message})`)));
+  child.on('close', (code, signal) => {
+    if (timedOut) return finish(unreadable(`it exceeded ${boundMs / 1000}s`));
+    if (code !== 0) return finish(unreadable(`${label} exited ${code ?? signal}`));
+    return finish(spec.parse(Buffer.concat(chunks).toString('utf8')));
+  });
+});
+
+// names: bridge names (the family-members `name`). Resolves to { [name]: { state, cause, entries } },
+// state `offered` | `unreadable` | `not-installed`; the reads run concurrently and never reject.
+export const readCatalogs = async (names, ctx = {}) => {
+  const results = await Promise.all(names.map((name) => readOne(name, ctx)));
+  return Object.fromEntries(names.map((name, i) => [name, results[i]]));
+};

package/tools/bridge-posture.mjs

@@ -12,9 +12,18 @@ const validPosture = (posture) => posture !== null && typeof posture === 'object
   && (!Object.hasOwn(posture, 'tier') || posture.tier === null || (typeof posture.tier === 'string' && posture.tier.length > 0))
   && Object.keys(posture).every((key) => ['model', 'effort', 'tier'].includes(key));
 
+// A posture key the settings file or the environment sets replaces the manifest default and names its
+// source; an explicitly empty AGY_MODEL (value null) renders as no model.
+const overlaid = (slot, fallback, backend, settings) => {
+  const row = (settings?.posture ?? []).find((r) => r.bridge === backend.name && r.source !== 'default'
+    && (r.key.endsWith('_EFFORT') ? 'effort' : 'model') === slot);
+  if (!row) return oneLine(fallback);
+  return `${row.value == null ? 'none' : oneLine(row.value)} (${row.source})`;
+};
+
 const postureString = (posture, backend, settings) => {
-  const parts = [`model=${oneLine(posture.model)}`];
-  if (Object.hasOwn(posture, 'effort')) parts.push(`effort=${oneLine(posture.effort)}`);
+  const parts = [`model=${overlaid('model', posture.model, backend, settings)}`];
+  if (Object.hasOwn(posture, 'effort')) parts.push(`effort=${overlaid('effort', posture.effort, backend, settings)}`);
   if (Object.hasOwn(posture, 'tier')) {
     const knob = (settings?.active ?? []).find((row) => row.key === 'CODEX_SERVICE_TIER' && row.bridge === backend.name);
     parts.push(knob ? `tier=${oneLine(knob.value)} (bridge-settings)` : `tier=${posture.tier ?? 'standard'}`);

package/tools/bridge-settings-read.mjs

@@ -75,6 +75,7 @@ export const allowedLabel = (entry) => {
     case 'integer': return `integer ${entry.min}..${entry.max}`;
     case 'duration': return 'duration (e.g. 5m, 30m, 90s — a unit is required, nonzero)';
     case 'boolean': return '"0" | "1"';
+    case 'posture': return 'a value the installed CLI offers (checked when set)';
     default: return entry.kind;
   }
 };
@@ -172,8 +173,34 @@ const REFUSED = (key, v) => ({ value: null, source: 'default', configuredIn: 'en
 // built-in default (`source: 'default'`) while still being an explicit line the operator wrote — and
 // for a RETIRED knob that is exactly the line the retirement asks them to clear, so it must not
 // vanish from the surfaces (council fold: `AGY_REVIEW_ALLOW_ADDDIR=2` and `=` both disappeared).
+// A posture key (the model and effort, spec bridge-model) follows the wrappers' aw_read_posture, not
+// the applied-settings lane: an env key set at all wins, its empty value meaning the key's default
+// (AGY_MODEL: no model, agy's own settings decide); else a non-empty, control-free file value; else the
+// default. Its sources are the wrappers' banner words: default, setting, environment.
+const EMPTY_ENV_DROPS_MODEL = new Set(['AGY_MODEL']);
+const postureOf = (entry, parsed, getenv) => {
+  const key = entry.key;
+  if (Object.prototype.hasOwnProperty.call(getenv, key)) {
+    const v = getenv[key];
+    if (v === '' && EMPTY_ENV_DROPS_MODEL.has(key)) return { value: null, source: 'environment', configuredIn: 'env', note: `the env ${key}= drops the model — agy's own settings decide` };
+    if (v === '') return { value: entry.default, source: 'environment', configuredIn: 'env', note: `the env ${key}= selects the built-in default` };
+    if (hasControlByte(v)) return { value: null, source: 'environment', configuredIn: 'env', note: `env value "${safeShow(v)}" carries control bytes for ${key} — ${entry.bridge === 'antigravity-cli-bridge'
+      ? 'agy-review refuses the run pre-spend; agy-run has no control-byte screen and refuses it only through its catalog check (it runs it when the catalog is unreadable)'
+      : 'the codex wrappers refuse the run pre-spend'}` };
+    return { value: v, source: 'environment', configuredIn: 'env' };
+  }
+  const fileEntries = parsed.byKey.get(key);
+  if (fileEntries && fileEntries.length) {
+    const v = fileEntries[fileEntries.length - 1].value;
+    if (v !== '' && !hasControlByte(v)) return { value: v, source: 'setting', configuredIn: 'file' };
+    return { value: entry.default, source: 'default', configuredIn: 'file', note: `file value "${safeShow(v)}" is empty or carries a control byte — falls back to the built-in default` };
+  }
+  return { value: entry.default, source: 'default', configuredIn: null };
+};
+
 export const effectiveOf = (entry, parsed, getenv) => {
   const key = entry.key;
+  if (entry.kind === 'posture') return postureOf(entry, parsed, getenv);
   if (Object.prototype.hasOwnProperty.call(getenv, key)) {
     const v = getenv[key];
     // An EXPLICITLY-EMPTY env (`KEY=`) suppresses the FILE override for this run (the wrapper skips a
@@ -222,21 +249,29 @@ export const displayValue = (v) => (v == null ? '(unset — wrapper built-in app
 // ── the fact-only snapshot the read-only status/advisor surfaces consume ────────────────
 
 // Best-effort, never throws: the ACTIVE knobs (a non-default value is in play — source env/file,
-// non-null) plus file presence + any unknown/duplicate keys. Model/effort are structurally excluded
-// from the registry, so `active` can NEVER carry a model claim (the fact-only guarantee). A corrupt
-// bundle or fs error degrades to `{ error }` — the caller renders that localized-on-error, never crashes.
+// non-null), every posture key's effective value and source (`posture`), plus file presence + any
+// unknown/duplicate keys. A posture key's sources are default/setting/environment, so it never enters
+// `active`. A corrupt bundle or fs error degrades to `{ error }` — the caller renders that
+// localized-on-error, never crashes.
+const postureRows = (registry, parsed, getenv) => [...registry.values()]
+  .filter((entry) => entry.kind === 'posture')
+  .map((entry) => {
+    const eff = effectiveOf(entry, parsed, getenv);
+    return { key: entry.key, bridge: entry.bridge, value: eff.value, source: eff.source, retired: entry.retired ?? null };
+  });
+
 export const settingsSnapshot = (ctx = {}) => {
   try {
     const registry = loadRegistry(ctx);
     const path = settingsPath(ctx);
     const fileState = readFileState(path, ctx);
+    const getenv = ctx.getenv ?? process.env;
     // A symlink / non-regular / unreadable file is IGNORED by the wrappers (built-in defaults apply) —
     // surface that honestly instead of silently omitting it (the wrappers warn; the status must too).
     if (fileState.state === 'unusable') {
-      return { path, fileState: 'unusable', active: [], unknown: [], duplicates: [], error: 'the settings file is a symlink / not a regular file — ignored, built-in defaults apply' };
+      return { path, fileState: 'unusable', active: [], posture: postureRows(registry, parseSettings(''), getenv), unknown: [], duplicates: [], error: 'the settings file is a symlink / not a regular file — ignored, built-in defaults apply' };
     }
     const parsed = parseSettings(fileState.text ?? '');
-    const getenv = ctx.getenv ?? process.env;
     const active = [];
     for (const entry of registry.values()) {
       const eff = effectiveOf(entry, parsed, getenv);
@@ -262,6 +297,7 @@ export const settingsSnapshot = (ctx = {}) => {
       path,
       fileState: fileState.state,
       active,
+      posture: postureRows(registry, parsed, getenv),
       unknown: [...parsed.byKey.keys()].filter((k) => !registry.has(k)),
       duplicates: duplicateKeys(parsed),
     };