@sabaiway/agent-workflow-kit 1.15.2 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,78 @@ 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.17.0 — Hardened Codex bridge: quality-first delegation, clean capture, enforced git-write boundary (kit)
+
+A **feature** release. The bundled `codex-cli-bridge` (`bridges/codex-cli-bridge/`) is overhauled to
+make delegating to the OpenAI Codex CLI faster, quieter, and safer **without lowering output quality** —
+economy comes only from quality-neutral waste removal, never a model/effort downgrade. The bridge's own
+contract bumps to **`2.0.0`** (MAJOR — the hardened wrappers now *refuse* inputs the `1.0.0` wrappers
+silently accepted). The kit's own modes/CLI are unchanged, so the kit is a MINOR bump; the
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration). The kit
+**package** version is a separate axis.
+
+- **Quality-first — no silent downgrade.** Both wrappers pin frontier `gpt-5.5` @ `xhigh` and **refuse
+  with a loud error** if `CODEX_MODEL`/`CODEX_EFFORT` resolves to a non-default, unless the explicit
+  throwaway `CODEX_PROBE=1` mode is set (echoed loudly). Outside that probe mode the passthrough guard
+  now blocks **every** model/context/policy-affecting flag (`-m/--model`, `--add-dir`, `-C/--cd`,
+  `-p/--profile`, `--oss`, …), not just the previous subset.
+- **Clean output capture.** `-o` (final message only) + a `--json` event trace +
+  `hide_agent_reasoning=true` + `--color never` replace the streamed reasoning transcript; the session id
+  is persisted to a sidecar (`CODEX_SESSION_FILE`) for resume; on failure the trace tail is surfaced to
+  stderr (no silent failure). Reasoning still runs at `xhigh` — quality unchanged.
+- **Hard timeout.** New `CODEX_HARD_TIMEOUT` (`timeout`/`gtimeout`, generous `xhigh`-sized defaults —
+  exec `3600` s / review `1800` s, `--kill-after=15s`); a hard kill (124/137) reports `codex exceeded
+  hard timeout`. A host with no `timeout` warns and runs uncapped (no silent skip).
+- **Precomputed-diff review.** `review code` now assembles the diff itself (`git status` + cached/unstaged
+  `git diff` + untracked file **contents**, binary-skipped; a payload above the
+  `CODEX_REVIEW_MAX_TOTAL_BYTES` threshold goes via a repo-local temp file, never truncated) and feeds it
+  to `codex exec` — killing the agentic
+  discovery roaming that read unrelated files (incl. `~/.claude`). Reads stay `read-only` for
+  surrounding-file context; a no-change preflight exits before spending a run. Optional structured
+  findings via `CODEX_REVIEW_SCHEMA=1` (default off, raw-text fallback).
+- **Invariant-preserving resume + enforced git-write boundary.** A dedicated `--resume-last` /
+  `--resume <id>` entrypoint re-establishes every wrapper invariant (`--ignore-user-config`, the pin,
+  posture restated via `-c`). A **physical `git` shim** (a real executable on a temp `PATH`, since
+  `execve` bypasses bash functions) enforces a strict read allowlist and blocks every write verb by
+  default — defence beyond the prompt contract.
+- **First hermetic bridge tests + tarball `70 → 72` files.** `bridges/codex-cli-bridge/bin/{codex-exec,codex-review}.test.mjs`
+  ship as byte-identical mirror payload (matching `agy.test.mjs`); `npm pack --dry-run --json`
+  re-verified. The byte-identical bridge mirror + `capability.json` stay valid.
+
+## 1.16.0 — Onboarding & discoverability: `help`, honest versioning, an enriched `status` (kit)
+
+A **feature** release (additive, backward-compatible). Makes the kit self-explanatory: a discoverable
+command surface, honest installed-on-this-machine version legibility, and one `status` that answers
+"versions + deployment + settings + bridges". The deployment-lineage head stays **`1.3.0`** — nothing
+in the deployed `docs/ai` *structure* changed, so there is **no migration**. The kit **package**
+version is a separate axis from that head.
+
+- **`/agent-workflow-kit help` + safe unknown-invocation routing.** New `tools/commands.mjs`: a frozen
+  command catalog (grouped Inspect / Configure / Orchestrate / Lifecycle, each tagged read-only /
+  writer / guarded) + a pure `routeInvocation` router. A discoverable index, and the read-only landing
+  spot for any unrecognized invocation — **no unrecognized/garbage token ever reaches a writer/guarded
+  mode** (only an explicit known token, or the acknowledged bare-bootstrap exception). Drift-guarded
+  against the `### Mode:` headers.
+- **Honest version legibility.** `tools/family-registry.mjs` gains a no-leak `--json` envelope (user-safe
+  field names only — never the internal manifest/stamp terms) feeding a shared **version block**:
+  deployment-structure head · installed package versions per member · the two-axes disambiguation when
+  the numbers coincide. An **offline caveat** flags a memory install too old to ship the current
+  orchestration template ("installed on this machine", no network). Bootstrap/upgrade now print a
+  **welcome mat** (success → version block → backend line → one caveat-aware next step) and bootstrap
+  opens with a one-line first-contact orientation.
+- **Settings & bridges in `status`.** `status` is now the single answer to "versions + deployment +
+  settings + bridges": orchestration recipes (effective per slot), attribution
+  (`includeCoAuthoredBy`), velocity (`defaultMode`), the bridges (readiness + wrapper PATH presence,
+  no model claim), and **visibility** (visible / hidden / unclear, via `inferVisibility`) — each in
+  plain language, **localized-on-error** (a malformed file surfaces its own error, the rest still
+  renders). `loadConfig` is shared with the procedures advisor (one strict-JSON reader).
+- **Surgical delegation gate.** `references/templates/orchestration.json` joins the memory
+  required-asset set: a memory too old to seed `docs/ai/orchestration.json` now **falls back** to the
+  kit's bundled substrate (which seeds it) instead of being delegate-classified — closing the
+  stale-memory trap the read-only note only informs about.
+- **Tarball guard `69 → 70`** (the new shipped `tools/commands.mjs`); `npm pack --dry-run --json`
+  re-verified. No `docs/ai` structural change → lineage head unchanged.
+
 ## 1.15.2 — Strip the package's own tests + fixtures from the npm tarball (kit)
 
 Packaging only — no API/behaviour change; removed the package's own colocated tests + fixtures from

package/README.md

@@ -218,9 +218,10 @@ command is printed).
 |---------|------|--------------|
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); never installs a bridge — set one up with `/agent-workflow-kit setup` |
+| `/agent-workflow-kit help` | any time | **read-only command index** — every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The discoverable entry point, and where any unrecognized invocation lands (always read-only — a garbage invocation never writes). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit status` | any time | **read-only** view of the whole family: which members (kit / memory / engine / the two bridges) are installed and at what version, and — with a project — what's deployed (`docs/ai`, the version stamps, and whether the AI files are git-ignored for hidden mode). Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/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 hand-edited `docs/ai/orchestration.json` + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, 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. |

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.15.2'
+  version: '1.17.0'
 ---
 
 # agent-workflow-kit
@@ -35,9 +35,11 @@ validator shipped by the candidate (which could itself be broken). Delegate only
 hold:
 - result is **valid** and `kind` is `memory-substrate`;
 - **every required asset is present** in the candidate, at its real path:
-  `references/templates/`, `references/contracts.md`, `references/scripts/`,
-  `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial install (manifest +
-  `SKILL.md` only) is treated as **invalid**.
+  `references/templates/`, **`references/templates/orchestration.json`** (the orchestration-config
+  template — a memory too old to ship it, pre-`1.2.0`, can't seed `docs/ai/orchestration.json`, so it
+  falls back to the kit's own bundled substrate, which does), `references/contracts.md`,
+  `references/scripts/`, `scripts/stamp-takeover.mjs`, `migrations/`, `capability.json`. A partial
+  install (manifest + `SKILL.md` only) is treated as **invalid**.
 
 On **unsupported** (unknown schema), **invalid**, **unavailable**, **wrong-family**, or
 **wrong-name**, **use the bundled copy** — never block. The fallback decision is final once
@@ -96,10 +98,11 @@ ever deleted.
 
 ## Modes
 
-Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call.
+Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call. The invocation→mode mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested): a **known** subcommand routes to its mode; the **bare/empty** invocation routes to `bootstrap`; **any unrecognized/ambiguous** token routes to `help`, which is **read-only** — so a garbage invocation never triggers a write (see the safe-routing rule under *Version status & the two axes*).
 
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
+- **`/agent-workflow-kit help`** — read-only **command index**: enumerate every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The single discoverable entry point, and the landing spot for any unrecognized invocation. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 - **`/agent-workflow-kit status`** — read-only view of the **whole family**: which members (kit / memory / engine / the two bridges) are installed, at what version, and — in a project — what is deployed (`docs/ai`, the version stamps, the hidden-mode fence). Never writes, never commits, never runs a subscription CLI.
@@ -110,6 +113,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 
 ### Version status & the two axes — surface this on every invocation
 
+**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can). The mapping is unit-tested, so it is not left to interpretation.
+
 Before acting, read `docs/ai/.workflow-version` (the project's stamp), state a one-line status, then route:
 
 - **absent** → bootstrap (a fresh deployment).
@@ -151,6 +156,67 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
   I'm skipping the backend-status line."* — never a silent skip (Hard Constraint — no silent
   failures).
 
+### The version block + welcome mat (shared by bootstrap + upgrade)
+
+Bootstrap (step 11) and **every** successful `upgrade` exit (steps 4 + 8) close with the same
+**report footer**, in this **canonical order**: success state → **version block** → the **one-line
+backend-status line** → **welcome mat**. Only the version block comes from
+`node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json` (add `--dir <project>` for the deploy
+axis) — **never hardcoded semver**; the backend-status line is its own shared contract (above), and
+the welcome mat **composes signals already gathered** (the version block's notes + the backend-status
+line), not a fresh helper call. Present everything in the user's conversational language; never paste
+the JSON or any internal field name.
+
+**Version block — three plain lines, fed from `--json`:**
+- **`Deployment structure: <deploymentHead> (current)`** — the deployed `docs/ai` structure version
+  (the envelope's `deploymentHead`); **the only axis `upgrade` compares**.
+- **`Installed on this machine — package versions:`** `kit <v> · memory <v> · engine <v> ·
+  codex-bridge <v> · antigravity-bridge <v>` — one per `installed[]` entry, labelled by its `display`
+  and showing its `version`, or, when there is no version, the plain phrase for its `state` (map
+  below). Append any `installed[].notes` **in plain words** (e.g. the memory-behind refresh+restart
+  line).
+- **The two axes are different — say so even when the numbers coincide:** an installed *package*
+  version (e.g. engine `1.3.0`) is a package number, **not** the deployment-structure version on line
+  one (which is also `1.3.0` today). The head advances only when the deployed `docs/ai` structure
+  changes, so a higher package number on npm/GitHub is **not** a newer deployment.
+
+**`state` → plain language** (map the envelope's `installed[].state` token; never show the raw token):
+`installed` → its version · `absent` → "not installed" · `other-tool` → "a different tool occupies
+that skill slot" · `placeholder` → "a placeholder, not a working install" · `invalid` → "installed
+but its manifest didn't validate" · `unsupported` → "installed but its manifest schema is too new for
+this kit" · `uncheckable` → "couldn't be checked (a permission error)".
+
+**Helper-failure contract (mirror the backend-status line).** The version block needs the
+family-registry helper, which the **agent host** runs. If the host can't run it (`node` not on the
+agent's PATH, or the helper errors), **skip the version block and say so with the concrete reason** —
+e.g. *"Couldn't run the family-registry helper here (node is not on the agent host PATH), so I'm
+skipping the installed-versions block."* — never a silent skip (Hard Constraint). It is non-essential:
+the rest of the report — and the commit gate — proceeds.
+
+**Welcome mat — the last line(s) of the footer.** After the version block and the backend-status
+line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
+step, chosen **caveat-aware** from signals already in hand (the version block's notes + the
+backend-status line — no new helper call) in this priority order:
+1. a member is **behind** (an `installed[].notes` caveat fired — memory/engine) → *refresh the behind
+   member first* (its `npx …@latest init` + restart the session);
+2. else **no backend is ready** (the backend-status line shows none ready) → *set one up with
+   `/agent-workflow-kit setup`*;
+3. else **a backend is ready but the orchestration config is still all-Solo** (no `reviewed` /
+   `council` / `delegated` slot anywhere — inspect `docs/ai/orchestration.json`, or read the
+   procedures advisor's resolved recipes) → *put it to work with `/agent-workflow-kit recipes`*;
+4. else (a backend is ready **and** a backend-backed recipe is already selected) → the optional
+   *`/agent-workflow-kit velocity`* opt-in (never run it without a yes).
+
+Keep it compact — a few short lines, plain language, no kit-internal terms.
+
+### Mode: help
+
+Read-only. The single discoverable **command index** — it answers *"what can `/agent-workflow-kit` do, and which commands change things?"* It **never writes, never commits, and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/commands.mjs` (add `--json` for the machine-readable catalog) and present its grouped index — **Inspect / Configure / Orchestrate / Lifecycle**, each command tagged **read-only / writer / guarded** — in the user's conversational language. That catalog is the **single source of truth** for the command surface (the same one the bootstrap / upgrade report footers point at); `routeInvocation(token)` in the same file is the executable contract for which invocation maps to which mode.
+
+`help` is also the landing spot for any **unrecognized or ambiguous** invocation — and that path is **always read-only** (the safe-routing rule under *Version status & the two axes*). When you arrive here that way, render the index and, in plain language, note that the invocation wasn't recognized so nothing was changed.
+
 ### Mode: bootstrap
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.
@@ -164,6 +230,7 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
+   - **First-contact orientation — say this before the first question (read-only).** In 1–2 plain lines, tell the user what this is — a portable memory & workflow system for this repo, so future sessions boot from a small structured memory instead of re-reading everything — and that they can run **`/agent-workflow-kit help`** any time to see every command. This is the "start here"; keep it to a sentence or two, then ask the visibility question.
 2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` — one managed block covering the full AI/agent footprint, never the machine-global excludes). See [Visibility contract](references/contracts.md#visibility-contract).
 3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
 4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](references/contracts.md#attribution-contract).
@@ -186,7 +253,7 @@ readiness, then **append an actionable recipe recommendation** from the recipe p
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing** — never auto-commit. Finally, offer the optional, opt-in **velocity profile** in one line — `/agent-workflow-kit velocity` seeds a read-only allowlist so routine read-only commands stop prompting (*Mode: velocity*); never run it without a yes.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -220,12 +287,12 @@ Fill strategy:
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the methodology-slot **and** hidden-mode footprint reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
    - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* or was *already present* (a user edit is preserved); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (Gotcha: never leak kit internals).
    - **Name the version axis so the package number isn't mistaken for a newer release.** When you state the deployment is up to date, say it is current at the **deployment-lineage head** (`1.3.0`) and add one plain line: this head versions the deployed `docs/ai` structure and is a **separate axis** from the kit **package** version published on npm/GitHub (the larger number users see on the repo/npm page). A packaging-only release can bump that package version **without** moving the head — the head advances only when the deployed `docs/ai` structure changes — so an equal-head report is **not** a stale deployment even though GitHub shows a higher package number. (This is the only place the two axes meet the user in `upgrade`; surfacing it here prevents the recurring "but GitHub shows a higher version" confusion.)
-   - **Print the one-line backend-status line** — the shared contract above (run `node ${CLAUDE_SKILL_DIR}/tools/detect-backends.mjs`; same format, invariants, and detector-unavailable skip-with-reason).
-   - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, say **"already up to date"** and still print the read-only backend line.
+   - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity`).
+   - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, say **"already up to date"** and still print the read-only version block + backend line.
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes — and when you report the stamp, **name the axis**: the head versions the deployed `docs/ai` structure and is a separate axis from the kit **package** version on npm/GitHub (the larger number users see there), so the user doesn't read the bigger package number as a newer deployment (same framing as the step 4 equal-head exit). Then **print the one-line backend-status line** (the shared contract above — same detector, format, invariants, and detector-unavailable skip-with-reason). Then **ask before committing**.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes — and when you report the stamp, **name the axis**: the head versions the deployed `docs/ai` structure and is a separate axis from the kit **package** version on npm/GitHub (the larger number users see there), so the user doesn't read the bigger package number as a newer deployment (same framing as the step 4 equal-head exit). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.
 
 ### Mode: backends
 
@@ -259,14 +326,22 @@ For each backend it:
 
 ### Mode: status
 
-Read-only. Answers *"which family members are installed (and at what version), and what is deployed in this project?"* across the **whole family** — the unified registry behind it (`tools/family-registry.mjs`) aggregates every member's `capability.json`. It **never writes, never commits, and never runs a subscription CLI**.
+Read-only. The **single answer to "versions + deployment + settings + bridges"** across the whole family — `tools/family-registry.mjs` aggregates every member's `capability.json` and surveys the project. It **never writes, never commits, and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json [--dir <project>]` and render it **compact**, in the user's conversational language — **never paste the JSON or any internal field name** (no-leak rule). Map the **`installed[].state`** token via the value→plain-language map under *The version block + welcome mat* (the `visibility` and wrapper states have their own phrasings, below). Present, each area on its own line(s), routing detail to its domain mode:
 
-Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs [--dir <project>]` and present its two-axis table:
+1. **Versions — the version block** (from `installed[]` + `deploymentHead`): the deployment-structure head, the installed package versions by `display`, the two-axes disambiguation, plus any member `notes` (e.g. a behind member's refresh+restart line). This is the shared version block above.
+2. **Deployment (`--dir`)** (from `project`): whether `docs/ai/` is deployed + the deploy stamps by `display`; and **visibility** — render `project.visibility.state` in **user-safe words only**: *visible (tracked)* / *hidden (git-ignored, local-only)* / *unclear (uncommitted or partially set up)* — **never** the words "hidden fence" or any marker term. A `visibility.error` → surface it plainly.
+3. **Settings (`--dir`, one line each)** (from `project.settings`):
+   - **recipes** — the effective recipe per slot (detail → `/agent-workflow-kit procedures` / `recipes`); a `recipes.detectError` → say the backends couldn't be checked, so recipes floored at solo.
+   - **attribution** — `includeCoAuthoredBy` effective; call out a **local override** only when `local` is non-null **and** differs from `project` (a `null` `local` means the key is absent there, so the project value stands — that is not an override).
+   - **velocity** — the effective `permissions.defaultMode` + whether an allowlist is seeded (detail → `/agent-workflow-kit velocity`).
+   - Any area's **`error`** field → surface it **loudly** in plain language; the rest of `status` still renders (never a crash).
+4. **Bridges (host, one line)** (from `bridges[]`): per bridge — readiness + wrapper PATH-presence; render each wrapper's `state` as *on PATH* (`present`) / *not on PATH* (`missing`) / *couldn't check* (`unknown`) (detail → `/agent-workflow-kit backends` / `setup`). **No default-model claim.** "credentials present" means a marker file exists, not a live login.
 
-1. **Skill axis (always):** per member — `installed` + the manifest health (`ok` / `not-installed` / `foreign` / `stub` / `invalid-manifest` / `unsupported-schema`, the same precedence the backend detector uses) + the installed version (read from the member's own `SKILL.md`, the authoritative source).
-2. **Deploy axis (`--dir <project>`):** the deployment stamps (`docs/ai/.workflow-version`, `.memory-version`), whether `docs/ai/` exists, and whether the hidden-mode managed fence is present.
+Restate the **two-axes honesty** — an installed *package* version is not a project's deployment-lineage stamp (see *Version status & the two axes*); the installed version is whatever is on disk under `~/.claude/skills/…`, so a stale install shows its real (older) version, honestly. A host that can't run the helper → **skip with the concrete reason** (the helper-failure contract), never silently.
 
-State plainly that the two version axes stay decoupled (an installed *skill* version is not a project's deployment-lineage stamp — see *Version status & the two axes*). The installed version reflects whatever is on disk under `~/.claude/skills/…`; a stale install shows its real (older) version, honestly.
+**Invariants:** read-only · never writes · never commits · never runs a subscription CLI · plain language only, no leaked internal terms.
 
 ### Mode: recipes
 
@@ -354,6 +429,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 - **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
 - **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
 - **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
+- **Unrecognized invocations are read-only.** Only a **known** subcommand reaches its mode; the **bare** invocation bootstraps (and an existing `docs/ai/` makes it ask upgrade-vs-bootstrap first, never overwrite); **any other / ambiguous** token routes to `help` (read-only). A garbage invocation never writes. The mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested) — don't hand-route around it.
 - **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
 - **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay in their source language. See [Communication contract](references/contracts.md#communication-contract).
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
@@ -415,6 +491,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the hand-edited `docs/ai/orchestration.json`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never runs a subscription CLI), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `commands.mjs` (the canonical **command catalog** + the pure `routeInvocation` router behind `/agent-workflow-kit help` and the safe unknown-invocation routing rule — one source of truth for the command surface, drift-guarded against the `### Mode:` headers), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `engine-source.mjs` (the bounded **two-slot** reconciliation — ensure-slot / inject-if-empty / cap for the `workflow:methodology` **and** `workflow:orchestration` pointers; both fragments read **live** from the installed `agent-workflow-engine` via `engine-source.mjs` (`deps.rel` selects which) — the family's one source of truth, no bundled mirror; fail-loud when the engine is needed but absent, orchestration soft-skipped when it would bust the cap), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`; exports the readiness consts the planner reuses), `recipes.mjs` (the read-only **recipe planner** behind `/agent-workflow-kit recipes` — `RECIPES` / `planRecipe` / `recommendRecipe` over the bridges' role vocabulary, drift-guarded against `provides`/`cost`/`quota` + an engine↔kit recipe-name parity guard; pure, never runs a subscription CLI; also exports the pure `ACTIVITIES` / `resolveActivityRecipe` activity-procedures resolver), `procedures.mjs` (the read-only **activity-procedures advisor** behind `/agent-workflow-kit procedures` — reads `references/procedures.md` live from the engine via `engine-source.mjs`, reads + validates the hand-edited `docs/ai/orchestration.json`, and prints the steps + the resolved effective recipe per slot; drift-guarded activity/slot table vs the canon; read-only, never runs a subscription CLI), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link/**remove/unlink** primitives that `setup-backends`, the npx installer, and the uninstaller use), `known-footprint.mjs` + `hide-footprint.mjs` (the **hidden-mode** registry + the single hide-writer behind step 9 / the upgrade reconcile — one managed block in the **project-local** `.git/info/exclude` covering the full AI/agent footprint; pinned by `known-footprint.test.mjs` drift-guard + `hide-footprint.test.mjs` / `.integration.test.mjs`), `family-registry.mjs` (the **unified family registry** behind `/agent-workflow-kit status` — aggregates every member's `capability.json`; pinned by a `family-registry.test.mjs` drift-guard), `uninstall.mjs` (the **guarded teardown** behind `/agent-workflow-kit uninstall` — classify each surface, preflight-then-mutate, never delete user-authored content), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

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: '1.0.0'
+  version: '2.0.0'
 ---
 
 # codex-cli-bridge
@@ -46,21 +46,28 @@ this skill. Both wrappers enforce the subscription path before invoking codex:
   regardless of that flag);
 - they **preflight `codex login status`** and refuse to run unless it reports `Logged in using ChatGPT`.
 
-## Models
+## Models quality-first pinned
 
-The wrappers default to `gpt-5.5` at reasoning effort `xhigh` (the strongest setting verified in this
-environment), both overridable per call. `codex --version` reports the CLI version, **not** the model
-list — check your Codex CLI / ChatGPT account for the model slugs available to you, or let a wrong
-`-m` surface the error.
+Delegated codex work ALWAYS runs on the **frontier model at maximum reasoning effort**: the wrappers
+**pin** `gpt-5.5` / `xhigh` and **refuse** (exit 2, loud) a non-default `CODEX_MODEL` / `CODEX_EFFORT`
+— knowingly-worse output is never traded for quota. The pin is deliberate (an explicit `-m gpt-5.5`
+guarantees the *strongest* model, not merely the CLI's current default); a release-time gate against
+<https://developers.openai.com/codex/models> re-checks that `gpt-5.5` is still the strongest selectable
+Codex model. Economy comes only from **quality-neutral waste removal** (clean capture, a hard timeout,
+a precomputed review diff, `resume` instead of re-sending context), never from a downgrade.
+
+The ONLY escape is a **throwaway probe** whose result is effort-independent (a reachability / smoke
+check): set `CODEX_PROBE=1` (echoed loudly) to relax the model/effort guard. Never use a probe run's
+output as real delegated work.
 
 | Variable | Default | Effect |
 |---|---|---|
-| `CODEX_MODEL` | `gpt-5.5` | model passed to `-m` |
-| `CODEX_EFFORT` | `xhigh` | reasoning effort passed to `-c model_reasoning_effort=…` |
+| `CODEX_MODEL` | `gpt-5.5` (pinned) | model passed to `-m`; a non-default is REFUSED unless `CODEX_PROBE=1` |
+| `CODEX_EFFORT` | `xhigh` (pinned) | reasoning effort (`-c model_reasoning_effort=…`); non-default REFUSED unless `CODEX_PROBE=1` |
 
-```bash
-CODEX_MODEL=<slug> CODEX_EFFORT=<low|medium|high|xhigh> codex-exec <file>
-```
+`codex --version` reports the CLI version, **not** the model list. Quota is metered in **messages**
+(a rolling 5h window + a weekly cap), not raw tokens — which is why the levers above are about removing
+waste, never lowering quality. Full knob list: [§ Environment knobs](#environment-knobs).
 
 ## Usage
 
@@ -70,27 +77,55 @@ Drive codex only through the two wrappers (installed on `PATH`), run from the ta
 # EXECUTION (workspace-write sandbox, network OFF, never prompts):
 codex-exec docs/plans/<slug>.md                 # drive a plan file
 echo "apply review fix: ..." | codex-exec -      # ad-hoc instruction from stdin
-CODEX_MODEL=<slug> codex-exec <file>             # override the model
-codex-exec <file|-> -- <extra codex flags...>    # passthrough codex flags after `--`
+codex-exec <file|-> -- <unguarded codex flags...> # passthrough codex flags after `--` (guarded ones rejected)
+
+# RESUME (iterate on the SAME session without re-sending context):
+codex-exec --resume-last docs/plans/<slug>.md    # continue the last session (id from the sidecar)
+echo "now do step 2 ..." | codex-exec --resume <session-id> -
 
 # REVIEW (read-only sandbox — codex cannot edit anything, only emits findings):
 codex-review plan docs/plans/<slug>.md           # critique a plan
-codex-review code                                # review the current working-tree diff
+codex-review code                                # review the current working-tree diff (precomputed)
 codex-review code "focus on the new reducer"     # review with extra focus
 ```
 
 `codex exec` is headless: there is **no TTY**, so `approval_policy=never` — anything needing
-escalation is refused and reported, never interactively approved. Extra `codex` flags go after a
-literal `--`; args without the separator are rejected (never silently dropped). Full flag/policy
-detail: [`references/sandbox-and-flags.md`](references/sandbox-and-flags.md).
+escalation is refused and reported, never interactively approved. The wrappers capture only codex's
+**final message** (`-o`; the JSON event stream + reasoning go to a discarded trace), so output is
+clean; a successful **non-resume** `codex-exec` also records the session id to a sidecar
+(`${CODEX_SESSION_FILE:-./.codex-last-session}`) so `--resume-last` can find it. Extra `codex` flags
+go after a literal `--`; the wrapper rejects any that would defeat the policy or the pinned model (see
+[§ Environment knobs](#environment-knobs) and the flag tiers in
+[`references/sandbox-and-flags.md`](references/sandbox-and-flags.md)); args without the separator are
+rejected, never silently dropped.
+
+## Environment knobs
+
+All optional; the defaults are the supported path. Anything that would lower quality (model/effort) or
+defeat a policy is guarded — see [§ Models](#models-quality-first-pinned).
+
+| Variable | Default | Effect |
+|---|---|---|
+| `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_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. |
+| `CODEX_PROBE` | unset | `=1` ⇒ throwaway-probe mode: relaxes the model/effort guard AND the tier-2 passthrough guard (echoed loudly). Never for real work. |
+
+The git-write shim, `--ignore-user-config`, and the `*_API_KEY` scrub are NOT env-tunable — they are
+fixed invariants.
 
 ## Project context (how `codex` sees the repo)
 
-From its **current working directory** `codex` auto-reads the root **`AGENTS.md`** — so when you run a
-wrapper from a project root, the project's Hard Constraints are available to codex with no wiring (a
+`codex` auto-**merges** `AGENTS.md` (root→cwd, plus a global `~/.codex/AGENTS.md`) straight into its
+developer context, truncated at `project_doc_max_bytes` (default 32 KiB) — so when you run a wrapper
+from a project root, the project's Hard Constraints are already in front of the model with no wiring (a
 probe confirmed codex returned a repo's declared dialogue language from `AGENTS.md`). The wrappers
-therefore **hardcode no project rules**: the orchestrator contract tells codex to read the target
-`AGENTS.md` and obey it.
+therefore **hardcode no project rules**, and the orchestrator contract is **lean**: it tells codex to
+*obey* the already-merged `AGENTS.md` Hard Constraints + declared gates — it does NOT waste a step
+telling codex to go *read* a file that is already in context.
 
 **Fallback is strict.** Both wrappers preflight that they run inside a git work tree and that a root
 `AGENTS.md` exists — if either is missing they **STOP and report** (a wasted subscription run is
@@ -105,17 +140,28 @@ See [`references/driving-codex.md`](references/driving-codex.md) for the full pl
 - **`codex-exec` for doing, `codex-review` for judging.** Use exec to implement a plan/fix under the
   sandbox; use review to get advisory findings on a plan or diff without any edits.
 - **The orchestrator commits — codex never does.** The execution contract forbids every git write
-  (branch/add/commit/stash/reset/checkout/tag/rewrite); you review codex's diff, then commit yourself.
+  (branch/add/commit/stash/reset/checkout/tag/rewrite), and `codex-exec` additionally enforces it with
+  a physical **git-write shim** on the codex subprocess's `PATH`: read-only git verbs pass through,
+  every write/unknown verb is blocked (codex spawns `git` via `execve`, which bypasses shell
+  functions — so the boundary must be a real file). You review codex's diff, then commit yourself.
 - **Treat output as advisory** and verify before acting — re-run the project's gates yourself, reject
   advice that conflicts with user instructions or repo rules.
 - **Hand codex a self-contained task.** It cannot see your conversation — for an ad-hoc instruction,
   embed the goal, the relevant paths, and the expected result; codex reads `AGENTS.md` for the rules.
-- **Re-dispatch with `codex exec resume`** (run codex directly — the wrapper's flag/stdin shape can't
-  host the `resume` subcommand) instead of re-sending context. **Caveat:** resume runs outside the
-  wrapper and may not re-accept `--sandbox` / policy flags — restate the policy, or start a fresh
-  `codex-exec` run when a guaranteed sandbox/network posture matters.
+- **Iterate with `codex-exec --resume-last` / `--resume <id>`** instead of re-sending context. The
+  resume entrypoint re-establishes EVERY wrapper invariant (subscription-only, `--ignore-user-config`,
+  the pinned model/effort) and **restates the full posture via `-c`** — `codex exec resume` resets the
+  sandbox/approval/network posture and rejects the `-s`/`--add-dir`/`-C` posture flags, so the wrapper
+  sets `sandbox_mode=workspace-write` + `approval_policy=never` +
+  `sandbox_workspace_write.network_access=false` explicitly. It reads the session id from the sidecar
+  (`--resume-last`) or takes it as an argument.
 - **Network is OFF in exec.** New dependencies and any network step are installed by hand, then codex
   is re-dispatched.
+- **`codex-review code` precomputes the diff.** The wrapper assembles the change set (repo map, status,
+  staged + unstaged diff, untracked file contents) and feeds it in, so codex does not roam the
+  filesystem rediscovering it; a clean tree exits 0 before a run is spent. Native `codex review` is
+  deliberately NOT used — it rejects `--ignore-user-config` and would load a personal config.toml,
+  breaking the subscription/config-isolation invariant.
 
 ## Complementary skills (optional, standalone-first)
 
@@ -140,8 +186,15 @@ The wrappers work in any git repo where `codex` is installed and authenticated.
   install dependencies or reach the network — do that by hand, then re-dispatch.
 - **No live approvals** — `codex exec` has no TTY, so `approval_policy=never`; an action that would
   need escalation is reported, not approved interactively.
-- **`resume` may drop sandbox/policy flags** — restate the policy or start a fresh run when the
-  posture matters (see the driving reference).
+- **`resume` resets the posture** — `codex exec resume` rejects `-s`/`--add-dir`/`-C` and forgets the
+  original sandbox/approval/network policy. The `codex-exec --resume`/`--resume-last` entrypoint
+  restates it via `-c`; only a *raw* `codex exec resume` (bypassing the wrapper) loses the posture.
+- **Hard timeout** — a hung run is killed at `CODEX_HARD_TIMEOUT` (exec 3600s / review 1800s) and
+  reported (exit 124/137); raise it for a known-healthy slow run. If neither `timeout` nor `gtimeout`
+  is on `PATH` the wrapper warns loudly and runs uncapped (never silently).
+- **Native `codex review` is out of scope** — it rejects `--ignore-user-config` (would load a personal
+  `config.toml` and break the subscription/config-isolation invariant) and can't be cleanly captured;
+  `codex-review` runs `codex exec` over a precomputed diff instead.
 - **bubblewrap** — on Linux, if `bubblewrap` is not on `PATH` codex prints a warning and uses a
   bundled copy; install it via your package manager to silence the warning.
 - codex output is advisory and may be incomplete or out of date — the main agent verifies before