@ikon85/agent-workflow-kit 0.28.0 → 0.29.0

package/.agents/skills/board-to-waves/SKILL.md

@@ -97,11 +97,21 @@ Body from `docs/agents/wave-anchor-template.md` **stage 1** (header + cluster or
 
 **Idempotency — stub marker + search-before-create (mandatory, BEFORE `create`).** Re-runs of board-to-waves must **not** produce duplicate stubs (a duplicate stub would confuse Mode-B identity in `to-prd`). Mirrors the `to-prd` pattern:
 - **Stable stub marker** `<!-- wave-stub-source: <topic-slug> -->` as the **first body line** of every stub. `<topic-slug>` = kebab-case slug of the gate outcome; set on the **first** run, **never** changed after (identity ≠ content — the slug stays findable even if members/size change later).
-- **search-before-create** per candidate **before** the `create`. **No** reliance on GitHub search (doesn't index HTML comments) — bounded, local:
+- **search-before-create** per candidate **before** the `create`, through the
+  shared all-state exact-marker lookup (it uses `gh api --paginate`, discards REST
+  pull-request items, and never relies on GitHub Search or a capped issue list):
   ```bash
-  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
-  # locally filter on `wave-stub-source: <topic-slug>` → 1 match ⇒ skip + report (stub exists); >1 ⇒ STOP + report; 0 ⇒ create
+  python3 scripts/find-by-marker.py --kind wave-stub-source --slug "<topic-slug>"
   ```
+  Branch on its JSON contract (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → skip the
+  create and report/update that stub; exactly one `closed` / `user-decision` → ask
+  the user whether to reopen, use a new identity, or stop; `>1` / `STOP` → stop
+  and report every number/state. Never auto-delete or silently replace a
+  closed/duplicate identity. Immediately after create, run the same lookup with
+  `--created <new-issue-number>`; continue only when it returns exactly the
+  newly-created open issue. Duplicate reconciliation stops loudly and reports
+  both/all numbers for user-decided resolution.
 
 **Create the candidate stub (cluster/wave-less)** — issue **without** `type:cluster` and **without** `--wave` (exactly one `type:*` + one `priority:*`; title **without** a `Welle <N>` prefix, since the wave number is only assigned at promotion), **with `--wave-stub`** (a searchable "awaiting planning" filter — the HTML marker above is only locally greppable, GitHub doesn't index it), attach to the board, triaged-role status (clustered, not yet planned). `to-prd` then matures the stub (Mode B) into a Draft PRD, `to-issues` promotes it to an anchor (sets `type:cluster` + Wave then, **strips `wave-stub`** — the stub leaves the planning list):
 ```bash

package/.agents/skills/to-issues/SKILL.md

@@ -143,33 +143,108 @@ else
   WAVE="$CURRENT"                                    # Stufe-1p Program-stub — reuse
 fi
 
-# 2. render the LEAN Tier-2 anchor body from docs/agents/wave-anchor-template.md into /tmp/anchor.md:
-#    body header `**Welle $WAVE — <Thema>**`, **plan_revision:** r<N> at top (before the first
-#    heading), the FILLED Slices table (you know the cut), the To-Do checklist collapsed to its
-#    one-line summary. The full grilled PRD does NOT go into the body (: every slice
-#    session's `--json body` read loads the whole body — a <details> block collapses only in
-#    the browser). Save it to /tmp/prd-archive.md instead — **with ALL embedded PRD markers
-#    stripped** (`plan_revision`, `prd-source-id`, `prd-content-fp`,
-#    `<!-- prd: awaiting-decomposition -->`; a stray second `plan_revision` on the issue is
-#    exactly the Retro confusion) — posted as ISSUE COMMENT #1 in step 2b.
-#    The anchor carries its own markers at the head. The issue TITLE is rewritten to
-#    `Welle N — <Thema>` by the promote step below (step 3) — do NOT set it here; promote
-#    prepends the wave prefix (and strips any `fix:`/`feat:` prefix) idempotently.
-#    Rewrite the PRD body via skill-prose gh (body-fill is issue CONTENT, NOT a board write — the
-#    helper owns board state only; cf. test_plan_body_fill_is_not_a_board_sync_op; gh-lint allows a
-#    non-workflow-label `gh issue edit`). Content-edit FIRST so a failure stops before board mutation:
-gh issue edit <prd#> --body-file /tmp/anchor.md
-
-# 2b. archive the full PRD as comment #1 on the anchor: one click away for a human,
-#     loaded only on demand by an agent (`--json body` never fetches comments). First line:
-#     `📄 Full PRD (archive, r<N>) — the body carries navigation/decisions only`.
-#     Idempotent re-run: a comment already starting with `📄 Full PRD (archive` → skip, never duplicate:
-gh issue comment <prd#> --body-file /tmp/prd-archive.md
-
-# 3. set the board state (type:cluster + Wave). If THIS fails AFTER the body edit, the title/body are
-#    already rewritten → STOP, report "board state incomplete (body/title already changed)", and
-#    re-run the idempotent promote (do not leave a silent partial state):
-python3 scripts/board-sync.py promote --issue <prd#> --wave "$WAVE"   # sets type:cluster + Wave + title `Welle N — …`
+# 2. Fill /tmp/anchor-template.md from docs/agents/wave-anchor-template.md (Tier 2):
+#    body header `**Welle $WAVE — <Topic>**`, anchor-owned markers at the head,
+#    filled Slices table, and the To-Do checklist collapsed to one line. Save the
+#    unchanged source PRD body as /tmp/source-prd.md. The renderer reads only those
+#    two files and writes only stdout: no GitHub/network call and no mutation.
+python3 scripts/render-anchor.py --template /tmp/anchor-template.md \
+  --prd /tmp/source-prd.md --document anchor > /tmp/anchor.md
+python3 scripts/render-anchor.py --template /tmp/anchor-template.md \
+  --prd /tmp/source-prd.md --document archive > /tmp/prd-archive.md
+```
+
+The anchor output is the filled template byte-for-byte. The archive starts with
+the stable `📄 Full PRD` marker and strips every canonical marker line
+(`plan_revision`, `prd-source-id`, `prd-content-fp`, `<!-- prd: … -->`) only
+from the source body's head block. Marker-looking text in a quote, fence, or
+later section is content and remains untouched.
+
+Promotion uses the remote issue itself as its journal. Classify four
+observations before every resume. Before transition 1, `S=yes|no` compares a
+freshly fetched remote body byte-for-byte with `/tmp/source-prd.md`, the source
+snapshot that produced both rendered outputs. Once `B=yes`, that source
+snapshot is no longer active and `S=n/a`. `B=yes|no` says whether the fetched
+issue body is byte-identical to `/tmp/anchor.md`.
+`C=0|exact-1|wrong-1|duplicates(<ids>)` classifies stable-marker comments:
+none; exactly one whose whole body is byte-identical to
+`/tmp/prd-archive.md`; exactly one with different bytes; or multiple matches
+with every comment ID retained. `P=absent|complete|partial` classifies only
+promotion-owned board state. `P=absent` accepts either an
+ordinary pre-state (no `type:cluster`, Wave unset, no `Welle` title prefix) or a
+valid Stufe-1p pre-state (`wave-stub` present, no `type:cluster`, and the
+pre-stamped Wave/title match `$WAVE`). `P=complete` requires `type:cluster`, the
+expected Wave/title, and no remaining `wave-stub`. Every other combination —
+including a different Wave — is `P=partial`. Fetch comments with the paginated
+API, never the first page alone:
+
+```bash
+gh api --paginate --slurp \
+  "repos/<owner>/<repo>/issues/<prd#>/comments?per_page=100"
+```
+
+Flatten every returned page, retain the comment `id`, and exact-match the
+start-of-body marker. The four valid states and their sole resume action are:
+
+<!-- promotion-board-observation-table:start -->
+| Scenario | Observable board facts | P classification |
+|---|---|---|
+| `ordinary-prestate` | no cluster; Wave unset; no Wave title | `absent` |
+| `stufe-1p-prestate` | wave-stub; no cluster; expected Wave/title | `absent` |
+| `promoted` | cluster; expected Wave/title; no wave-stub | `complete` |
+| `cluster-only` | cluster; Wave/title missing | `partial` |
+| `wrong-wave` | any different Wave value | `partial` |
+<!-- promotion-board-observation-table:end -->
+
+<!-- promotion-state-table:start -->
+| State | Observable predicates | Resume action |
+|---|---|---|
+| `initial` | `S=yes`, `B=no`, `C=0`, `P=absent` | render + write body |
+| `body-written` | `S=n/a`, `B=yes`, `C=0`, `P=absent` | reconcile + write archive comment |
+| `comment-written` | `S=n/a`, `B=yes`, `C=exact-1`, `P=absent` | promote board state |
+| `promoted` | `S=n/a`, `B=yes`, `C=exact-1`, `P=complete` | no-op; continue publish audit |
+<!-- promotion-state-table:end -->
+
+Each transition is idempotent and has an explicit contract:
+
+1. **Write body (`initial → body-written`).** Pre: `S=yes`, `B=no`, `C=0`,
+   `P=absent`. Fetch the remote body again immediately before the command and
+   recompute `S`; a prior fetch is not sufficient.
+   Run `gh issue edit <prd#> --body-file /tmp/anchor.md`, refetch the body, and
+   require a byte match. Post: `S=n/a`, `B=yes`, `C=0`, `P=absent`.
+2. **Write archive (`body-written → comment-written`).** Pre: `S=n/a`, `B=yes`,
+   `C=0`, `P=absent`. Re-run the pagination-aware lookup immediately before
+   create; if it now yields `C=exact-1`, classify as `comment-written` and do
+   not create. `C=wrong-1` or `C=duplicates(<ids>)` is drift and enters repair,
+   never create. Only `C=0` runs `gh issue comment <prd#> --body-file
+   /tmp/prd-archive.md`, then immediately paginate and reconcile again. Post:
+   `S=n/a`, `B=yes`, `C=exact-1`, `P=absent`.
+3. **Promote (`comment-written → promoted`).** Pre: `S=n/a`, `B=yes`,
+   `C=exact-1`, `P=absent`. Run `python3 scripts/board-sync.py promote --issue <prd#> --wave
+   "$WAVE"`, refetch body, comments, labels, Wave, and title. Post: `S=n/a`,
+   `B=yes`, `C=exact-1`, `P=complete`. Re-running `promote` with the same Wave
+   is the repair for `P=partial`; a different Wave remains a hard stop.
+
+Any other predicate combination is drift, not a fifth state. Repair it
+explicitly, then reclassify. `S=no` before transition 1 means **STOP**: report
+the diff between the fresh remote body and `/tmp/source-prd.md`, never write the
+stale render, re-fetch the remote body into a reviewed source snapshot, and
+rerender both outputs before recomputing `S`. `B=no` outside the valid `initial` tuple
+means **STOP**, report the body diff against `/tmp/anchor.md`, and require
+an explicit operator decision to restore the rendered anchor or adopt the remote
+edit and rerender both outputs; never overwrite remote journal evidence automatically.
+Only transition 1 performs the approved source-to-anchor body write without
+this drift gate. `C=wrong-1` → report its ID and explicitly update it to the
+rendered archive; `P=complete` with `C=0` → create/reconcile the archive without
+demoting. For `P=partial`, a different Wave is a hard stop; otherwise rerun
+same-Wave `promote`. `C=duplicates(<ids>)` always means **STOP and report every
+comment ID**. An operator must choose and explicitly delete/update the
+duplicates, then rerun the paginated lookup; never select the first match or
+silently discard one. No local operation journal is written: these
+observations are the journal.
+
+```bash
+# 3. Continue only from the `promoted` state.
 
 # 4. create each child (dependency order), then link it under the anchor — BEFORE the §7 exit audit,
 #    so the checker sees the anchor's children (a childless type:cluster anchor mis-reads as a leaf)

package/.agents/skills/to-prd/SKILL.md

@@ -49,11 +49,21 @@ gh project item-list 1 --owner <owner> --limit 500 --format json   # check targe
 - **Mode A — idempotency via two separate markers in the body:**
   - **Stable source identity** `<!-- prd-source-id: <id> -->` — **never** changes across plan content edits (otherwise search-before-create misses the changed re-run → duplicate). **Default rule** for `<id>` (identity ≠ content; set on the **first** to-prd run, **never** changed after — the slug then lives in the issue body and is discoverable via search-before-create): kebab-case slug of the plan topic. Priority: **(1)** explicitly passed ID / durable issue number → **(2)** existing slug from a prior run (found via search-before-create) → **(3)** new kebab-case slug from the plan/title topic. The `PLAN.md` path is only a **secondary hint** (not stable across worktrees; external specs have none), **never** the identity itself.
   - **Separate content fingerprint** `<!-- prd-content-fp: <hash> -->` — only for diff/audit/bump decisions, **not** for identity.
-- **search-before-create:** **no** reliance on GitHub Search (doesn't index HTML comments). Bounded, local:
+- **search-before-create:** use the shared all-state exact-marker lookup (it uses
+  `gh api --paginate`, discards REST pull-request items, and never relies on
+  GitHub Search or a capped issue list):
   ```bash
-  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
-  # filter locally on `prd-source-id: <id>` → 1 match ⇒ update; >1 ⇒ STOP+report; 0 ⇒ create
+  python3 scripts/find-by-marker.py --kind prd-source-id --slug "<id>"
   ```
+  Branch on its JSON contract (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → update
+  that issue; exactly one `closed` / `user-decision` → ask the user whether to
+  reopen, use a new identity, or stop; `>1` / `STOP` → stop and report every
+  number/state. Never auto-delete or silently replace a closed/duplicate identity.
+  Immediately after a Mode-A create, run the same lookup with
+  `--created <new-issue-number>`. Continue only when it returns exactly the
+  newly-created open issue; duplicate reconciliation is a loud `STOP` that
+  reports both/all numbers for user-decided resolution.
 
 ## 4. Write the Draft PRD (deliverable)
 

package/.agents/skills/to-waves/SKILL.md

@@ -192,10 +192,22 @@ A re-run of to-waves on the same program is **delta-apply** and doubles as
   bottom-up `wave-stub-source` marker; `<prd-source-id>` is the PRD's own source
   slug). These never change across revisions — they are the identity for
   search-before-create.
-- **Delta apply.** Filter existing issues locally by their source marker
-  (`gh issue list --json number,body` + a local filter, no reliance on GitHub search —
-  it does not index HTML comments). For each planned stub/leaf: **match** → update in
-  place (never duplicate); **missing** → create; a live issue carrying a
+- **Delta apply.** Resolve every planned identity through the shared all-state,
+  exact-marker CLI (it uses `gh api --paginate`, discards REST pull-request
+  items, and does not rely on GitHub Search or a capped issue list):
+  ```bash
+  python3 scripts/find-by-marker.py --kind program-stub-source --slug "<prd-source-id>/w<N>"
+  python3 scripts/find-by-marker.py --kind program-leaf-source --slug "<prd-source-id>/<local-id>"
+  ```
+  Branch on each JSON result (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → update in
+  place; exactly one `closed` / `user-decision` → ask the user whether to reopen,
+  use a new identity, or stop; `>1` / `STOP` → stop and report every number/state.
+  Never auto-delete or silently replace a closed/duplicate identity. Immediately
+  after every create, run the same lookup with `--created <new-issue-number>` and
+  continue only when exactly the newly-created open issue is returned; a duplicate
+  reconciliation stops loudly with both/all numbers for user-decided resolution.
+  A live issue carrying a
   `program-*-source` for this program that the current plan no longer references →
   report as **orphaned** (do not auto-close — closing is the abort convention, §8).
   Cross-check the native children (`children-of <prd#>` and each stub) against the

package/.agents/skills/wrapup/SKILL.md

@@ -79,5 +79,4 @@ STOP → diagnose in the main conversation, fix, re-run `land` (an already-merge
 
 ## Out of scope
 - Live-verify / DoD: must happen **before** `/wrapup` — this skill lands, it does not verify.
-- `/retro`: offered before landing (step 2), never run by this skill.
 - Other worktrees / their servers stay untouched.

package/.claude/skills/board-to-waves/SKILL.md

@@ -110,11 +110,21 @@ Body from `docs/agents/wave-anchor-template.md` **stage 1** (header + cluster or
 
 **Idempotency — stub marker + search-before-create (mandatory, BEFORE `create`).** Re-runs of board-to-waves must **not** produce duplicate stubs (a duplicate stub would confuse Mode-B identity in `to-prd`). Mirrors the `to-prd` pattern:
 - **Stable stub marker** `<!-- wave-stub-source: <topic-slug> -->` as the **first body line** of every stub. `<topic-slug>` = kebab-case slug of the gate outcome; set on the **first** run, **never** changed after (identity ≠ content — the slug stays findable even if members/size change later).
-- **search-before-create** per candidate **before** the `create`. **No** reliance on GitHub search (doesn't index HTML comments) — bounded, local:
+- **search-before-create** per candidate **before** the `create`, through the
+  shared all-state exact-marker lookup (it uses `gh api --paginate`, discards REST
+  pull-request items, and never relies on GitHub Search or a capped issue list):
   ```bash
-  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
-  # locally filter on `wave-stub-source: <topic-slug>` → 1 match ⇒ skip + report (stub exists); >1 ⇒ STOP + report; 0 ⇒ create
+  python3 scripts/find-by-marker.py --kind wave-stub-source --slug "<topic-slug>"
   ```
+  Branch on its JSON contract (`count`, `issues[].number`, `issues[].state`,
+  `verdict`): `0` / `create` → create; exactly one `open` / `update` → skip the
+  create and report/update that stub; exactly one `closed` / `user-decision` → ask
+  the user whether to reopen, use a new identity, or stop; `>1` / `STOP` → stop
+  and report every number/state. Never auto-delete or silently replace a
+  closed/duplicate identity. Immediately after create, run the same lookup with
+  `--created <new-issue-number>`; continue only when it returns exactly the
+  newly-created open issue. Duplicate reconciliation stops loudly and reports
+  both/all numbers for user-decided resolution.
 
 **Create the candidate stub (cluster/wave-less)** — issue **without** `type:cluster` and **without** `--wave` (exactly one `type:*` + one `priority:*`; title **without** a `Welle <N>` prefix, since the wave number is only assigned at promotion), **with `--wave-stub`** (a searchable "awaiting planning" filter — the HTML marker above is only locally greppable, GitHub doesn't index it), attach to the board, triaged-role status (clustered, not yet planned). `to-prd` then matures the stub (Mode B) into a Draft PRD, `to-issues` promotes it to an anchor (sets `type:cluster` + Wave then, **strips `wave-stub`** — the stub leaves the planning list):
 ```bash

package/.claude/skills/codex-build/SKILL.md

@@ -13,12 +13,14 @@ The role-flip of `/codex-review`: there, Claude builds the plan and Codex critiq
 
 ## Prerequisites (verify once, fast)
 
-- `codex --version` ≥ 0.130 (older CLIs error on the default `gpt-5.5` model).
-- Codex authenticated (prior `codex login`; ChatGPT account is fine). On auth/model error, surface it — don't silently retry.
+- Let `scripts/codex-exec.sh` preflight Codex before launch. It enforces the
+  exact tested-version allowlist, authentication, platform, and capabilities;
+  surface any failure rather than retrying silently.
 - Do NOT pin `-m` or model config (e.g. `model_reasoning_effort`) unless the user asks. Pinning `gpt-5.x-codex` variants 400s on ChatGPT-account auth; config defaults come from `~/.codex/config.toml`.
 - **Echo the active model at kickoff** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it with the resolved tunables. If the user objects, stop before launching the build.
-- **Codex has a native image-generation tool** in `codex exec` sessions (ChatGPT-account backed, no API key; upstream-verified 2026-07-08). Specs may therefore include "generate these image assets yourself" steps: name exact file paths, dimensions, and style in the prompt contract.
-- Run from the target working directory's root (both `exec` and `resume` then need no `-C`; `resume` doesn't support `-C` anyway).
+- **Codex has a native image-generation tool** in delegated sessions (ChatGPT-account backed, no API key; upstream-verified 2026-07-08). Specs may therefore include "generate these image assets yourself" steps: name exact file paths, dimensions, and style in the prompt contract.
+- Run the wrapper from the target working directory's root so every round keeps
+  the same bounded workspace.
 
 ## Tunables (read from args, else default)
 
@@ -63,17 +65,34 @@ OUTPUT: End with a report — files changed (one line each: path + what/why),
 EOF
 ```
 
-## Step 2 — Launch Codex (fresh session, capture `thread_id`)
+## Step 2 — Launch Codex (fresh wrapper-owned session)
 
 ```bash
-codex exec -s workspace-write --json -o "$CODEX_TMP/build.txt" - <"$P" 2>/dev/null | grep '"type":"thread.started"'
+if ROUND_RESULT=$(scripts/codex-exec.sh new --profile build --mode workspace-write --prompt-file "$P"); then
+  RUN_ID=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["runId"])')
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
+fi
 ```
 
-- **`-s workspace-write`, never `--yolo` / `--dangerously-bypass-approvals-and-sandbox`, and never weaken the approval policy.** The sandbox bounds Codex to the working directory; the allowed-write gate (Step 3) bounds it further to the declared set. If the build genuinely needs something outside the sandbox (network installs, system config), that step is Claude's, not Codex's — split it out of the spec.
-- Prompt goes via stdin (`- <"$P"`) — this both avoids quoting bugs AND sidesteps the non-TTY stdin hang (`codex exec` blocks forever waiting on stdin EOF under Claude Code's Bash tool; feeding the file gives immediate EOF).
-- Parse `thread_id` from the `{"type":"thread.started","thread_id":"..."}` line → `THREAD_ID`. Codex's final report lands in `$CODEX_TMP/build.txt` — read that file; don't parse the JSONL stream for content.
-- `2>/dev/null` suppresses cosmetic MCP/auth stderr noise. Confirm success by the report file + a `thread.started` line; neither → failed run (auth/model) — stop and tell the user.
-- **Timing:** foreground with `timeout: 600000` on the Bash tool call (default 2-min tool timeout kills real builds). If the spec is clearly >10 min of work (multi-file feature, migration, anything with image generation), launch with `run_in_background: true` instead and read the `-o` file when it exits. Don't kill a quiet background run early — Codex builds are legitimately slow.
+- The `build` profile establishes and persists `workspace-write`; never request
+  `danger-full-access` or weaken the approval policy. The wrapper bounds Codex
+  to the working directory, and the allowed-write gate (Step 3) narrows it to
+  the declared set. Work outside those bounds belongs to Claude and must be
+  split out of the spec.
+- The wrapper owns stdin closure, hang detection, the overall build timeout,
+  stderr redaction, and the launched process group. Never inspect, signal, or
+  kill foreign Codex processes.
+- `RUN_ID` is opaque. Retain it only for resume/finalize/abort; harvest the
+  report from `CODEX_REPORT` before deleting run state.
+- `handle-failure` surfaces every failed or cancelled structured result plus
+  cleanup metadata; the caller then stops before report handling. A surfaced
+  `HUNG` returns to the user for the choice to retry once with a fresh run or
+  stop delegation and let Claude take over. Never target a process directly.
+
 - **Heads-up on completion (required):** when a background Codex run finishes, the FIRST line of your next message to the user must be a loud standalone banner — `🔔 CODEX FINISHED — <what> (exit ok/fail) — verifying now` — BEFORE any verification output. The user is not watching tool calls; never let a completed build slide silently into the verify phase.
 
 ## Step 3 — Verify (Claude, always, never delegated)
@@ -83,33 +102,60 @@ Codex's report is advisory. Verify yourself:
 1. **Allowed-write gate:** `git status --porcelain=v1` — every changed AND untracked path must be inside the allowed-write set from Step 0.4. Any path outside it is a finding: surface it to the user before anything else, and don't fold it silently into the diff review.
 2. Read the FULL diff (`git diff`). Judge it like a contributor PR: correctness, spec fidelity, style match with surrounding code, nothing touched outside scope.
 3. Run `PROOF_CMD` yourself (or the focused tests for the changed area). Codex's pasted output doesn't count as proof.
-4. Append to `LOG_FILE` under `## Act 3 — Build`: `### Round <n> — Codex build` + its report summary + `### Claude's verdict` + what passed/failed review.
+4. Append to `LOG_FILE` under `## Act 3 — Build`: `### Round <n> — Codex build` + `CODEX_REPORT` + `### Claude's verdict` + what passed/failed review.
 
 ## Step 4 — Fix loop (same session, bounded)
 
 Problems found → resume the SAME session (Codex keeps its context; cheaper and better than a fresh run). Write the fix list to a second temp file (`$CODEX_TMP/fix-prompt.txt`), same contract discipline: exact problem, exact file, proof expected, same allowed-write set.
 
 ```bash
-# resume has no -s and no -C: run from the repo dir and force the sandbox via
-# config override, or Codex inherits config.toml's sandbox_mode (possibly
-# read-only — can't write; possibly danger-full-access — must never run).
-codex exec resume "$THREAD_ID" -c sandbox_mode="workspace-write" --json \
-  -o "$CODEX_TMP/build.txt" - <"$CODEX_TMP/fix-prompt.txt" 2>/dev/null >/dev/null
+if ROUND_RESULT=$(scripts/codex-exec.sh resume "$RUN_ID" --prompt-file "$CODEX_TMP/fix-prompt.txt"); then
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT" --run-id "$RUN_ID") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
+fi
 ```
 
-Re-verify (Step 3, including the allowed-write gate) after each round. After `MAX_FIX_ROUNDS` failed rounds: STOP delegating — Claude takes over and finishes the remaining fixes directly. Log the takeover. Ping-ponging trivia through delegation burns more than it saves.
+The wrapper enforces the persisted workspace-write mode on every resume.
+Re-verify (Step 3, including the allowed-write gate) after each round. After
+`MAX_FIX_ROUNDS` failed rounds: abort this run, STOP delegating, and let Claude
+take over and finish the remaining fixes directly. Log the takeover.
+
+```bash
+scripts/codex-exec.sh abort "$RUN_ID"
+```
 
 ## Step 5 — Human gate (diff sign-off)
 
 Present: 3-bullet summary of what was built, files-changed list, proof-test output (pass/fail, verbatim tail), rounds used, any spec deviations. Ask: *"Codex built it, proof passes, diff reviewed. Commit?"*
 
-- Commit ONLY on yes — and Claude writes the commit, never Codex.
-- Rejected → ask what's wrong, route back to Step 4 (or take over directly if fix rounds are spent).
+- On yes, harvest and log the final report, then delete the wrapper state before
+  Claude commits:
+
+  ```bash
+  scripts/codex-exec.sh finalize "$RUN_ID"
+  ```
+
+- Commit ONLY after that finalize succeeds — and Claude writes the commit,
+  never Codex.
+- Rejected with another requested fix → keep the known run and route back to
+  Step 4 (or take over directly if fix rounds are spent).
+- Cancellation or a decision to stop delegation → abort the known run before
+  returning control:
+
+  ```bash
+  scripts/codex-exec.sh abort "$RUN_ID"
+  ```
 
 ## Hard rules
 
 - Clean tree before launch. Always. No exceptions.
-- **Sandbox is bounded every round:** `-s workspace-write` on exec, `-c sandbox_mode="workspace-write"` on every resume. Never `--yolo`, never `danger-full-access`, never a weakened approval policy — if the task can't be done inside those bounds, it isn't a Codex delegation.
+- **The mode is bounded every round:** establish `workspace-write` in the
+  wrapper's new call and let every resume inherit it. Never `--yolo`, never
+  `danger-full-access`, never a weakened approval policy — if the task can't
+  be done inside those bounds, it isn't a Codex delegation.
 - The allowed-write gate runs after EVERY round — out-of-set writes are findings, not noise.
 - Claude never skips the diff read. Codex claims are advisory until Claude has read the diff and run the proof.
 - Fix loop terminates at `MAX_FIX_ROUNDS` — then Claude takes over. No unbounded delegation ping-pong.
@@ -121,6 +167,6 @@ Present: 3-bullet summary of what was built, files-changed list, proof-test outp
 - Don't build without a spec — that's designing by delegation, and it fails. Route to `/grill-me-codex` or `/codex-review` first.
 - Don't use for ~<20-line single-obvious-change edits — just make the edit.
 - Don't pin `-codex` model variants on ChatGPT-account auth — 400s.
-- Don't resume with `--last` — capture and use the explicit `THREAD_ID` (parallel sessions make `--last` grab the wrong thread). And ECHO the id into the command visibly before running: `resume` with a missing/garbage id can silently fall back to the most recent session instead of erroring (observed upstream 2026-07-08) — a wrong-target resume looks exactly like a successful one.
-- Don't parse the JSONL stream for the report — read the `-o` file.
+- Don't resume with `--last`; use the wrapper's explicit opaque `RUN_ID` so
+  parallel sessions cannot target each other.
 - Don't let Codex commit, and don't auto-commit yourself — human gate first.

package/.claude/skills/codex-review/SKILL.md

@@ -11,11 +11,13 @@ This is a **deliberate, high-stakes tool** — reach for it on auth, data models
 
 ## Prerequisites (verify once, fast)
 
-- Codex CLI installed and recent: `codex --version` (need ≥ 0.130; the default `gpt-5.5` model errors on older CLIs).
-- Codex authenticated: a prior `codex login` (ChatGPT account is fine). If a run returns an auth/model error, surface it to the user — do not silently retry.
+- Let `scripts/codex-exec.sh` preflight Codex before launch. It enforces the
+  exact tested-version allowlist, authentication, platform, and capabilities;
+  surface any failure to the user rather than retrying silently.
 - Do NOT pin `-m` unless the user asks. The user's `~/.codex/config.toml` default model is used. Pinning `gpt-5.x-codex` variants fails on ChatGPT-account auth.
 - **Echo the active model before Round 1** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it alongside the resolved tunables. If the user objects, stop before burning a round.
-- **Sandbox flag differs between the two commands.** `codex exec` accepts `-s read-only`. `codex exec resume` does NOT — it rejects `-s` ("unexpected argument"). On resume you MUST force read-only via `-c sandbox_mode="read-only"`, because `config.toml` may default `sandbox_mode` to `danger-full-access` (+ `approval_policy="never"`) — which would let Codex WRITE files mid-loop. This is the single most important safety detail in this skill: verified end-to-end on 2026-06-04.
+- Use `scripts/codex-exec.sh` for every round. Its `review` profile persists the
+  initial `read-only` mode across resumes and rejects mode drift.
 
 ## Tunable variables (read from skill args, else default)
 
@@ -37,7 +39,7 @@ The invocation itself is the kickoff. Confirm scope in one line: what is being p
 
 Do real planning: read the relevant code, think through the approach, surface decisions and tradeoffs. Then write the plan to `PLAN_FILE` in this structure:
 
-> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and run Codex from there (`-C <dir>` on the round-1 `exec`; `exec resume` rejects both `-C` and `-s`, so run resume from that cwd and force read-only via `-c sandbox_mode="read-only"`). A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
+> **Where to write it:** `PLAN.md` + `PLAN-REVIEW-LOG.md` are per-session scratch — write them in the working directory the implementing session will actually use, and invoke the wrapper from that directory. A project may gitignore these files, so don't rely on git to carry them across checkouts/worktrees. In worktree-based repos, create the issue worktree BEFORE this write and plan inside it.
 
 ```markdown
 # Plan: <task>
@@ -69,60 +71,66 @@ Show the user the plan inline and say you're sending it to Codex for adversarial
 
 ### Step 2 — The loop
 
-Maintain `ROUND` (start 1) and `THREAD_ID` (empty until round 1 returns).
+Maintain `ROUND` (start 1) and the wrapper's opaque `RUN_ID`.
 
 **The review prompt** sent to Codex each round (adjust the task line):
 
 > You are an adversarial reviewer for an implementation plan. Be skeptical and specific — your job is to find what breaks, not to be agreeable. Read the plan at `PLAN.md` (and any repo files you need; you are read-only). Identify concrete flaws: security holes, race conditions, missing edge cases, schema conflicts, wrong assumptions, observability gaps, simpler alternatives. For each, give a one-line fix. Do NOT modify any files. End your reply with EXACTLY one line: `VERDICT: APPROVED` if the plan is sound enough to implement, or `VERDICT: REVISE` if it still has material problems.
 
-**Round 1** (creates the session — capture `thread_id`):
-
-Stream `--json` to a FILE, never pipe to `grep` — `codex exec --json | grep` deadlocks on codex-cli ≥0.137. **Always launch with `< /dev/null`** — a backgrounded `codex exec … &` without it blocks on stdin and sits at **0 CPU / 0 bytes** forever (the #1 cause of the "silent hang"; verified 2026-06-09). Background it so a **90s liveness probe** still catches a genuine sandbox deadlock.
+**Round 1** creates the session and returns the opaque run ID plus the report:
 
 ```bash
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec -s read-only --json -o $CODEX_TMP/verdict.txt "$(cat REVIEW_PROMPT)" \
-  < /dev/null > $CODEX_TMP/r1.jsonl 2>/dev/null &
-CODEX_PID=$!
-sleep 90                                          # liveness probe (REQUIRED)
-if kill -0 "$CODEX_PID" 2>/dev/null; then
-  CPU=$(ps -o time= -p "$CODEX_PID" 2>/dev/null | tr -dc '0-9:')   # cumulative CPU, e.g. 00:00:00
-  BYTES=$(wc -c < $CODEX_TMP/r1.jsonl 2>/dev/null || echo 0)
-  if [ "${CPU:-00:00:00}" = "00:00:00" ] && [ "${BYTES:-0}" -eq 0 ]; then
-    kill -9 "$CODEX_PID" 2>/dev/null; echo "CODEX-HUNG"   # alive + 0 CPU + 0 bytes = blocked, NOT working
-  fi
+if ROUND_RESULT=$(scripts/codex-exec.sh new --profile review --mode read-only --prompt "$REVIEW_PROMPT"); then
+  RUN_ID=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["runId"])')
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
 fi
-wait "$CODEX_PID" 2>/dev/null
-THREAD_ID=$(grep -o '"thread_id":"[^"]*"' $CODEX_TMP/r1.jsonl | head -1 | cut -d'"' -f4)
 ```
-- **`CODEX-HUNG` printed** (alive + 0 CPU + 0 bytes at 90s) → **first suspect the stdin block**: confirm the launch has `< /dev/null` and retry. That fixes it in nearly every case. **NEVER `pgrep`/`kill` codex procs to "clear contention"** — that murders the user's live, unrelated codex sessions and does **not** fix a stdin hang. Only if `< /dev/null` is present and it still hangs (genuine sandbox deadlock) → **STOP**: tell the user, offer to proceed without the cross-model review or retry once. Don't touch other codex processes.
-- **Healthy:** CPU climbs past `00:00:00` and/or `$CODEX_TMP/r1.jsonl` grows; `THREAD_ID` parses; critique lands in `$CODEX_TMP/verdict.txt`. `2>/dev/null` hides cosmetic MCP/auth noise.
-- **Clean finish but no verdict file + no `THREAD_ID`** = auth/model failure → stop, tell the user.
 
-**Rounds 2..MAX** (resume the SAME session — Codex remembers its earlier critiques, won't re-litigate settled points):
+**Rounds 2..MAX** resume the same wrapper-owned session; do not pass a mode
+again because the wrapper enforces the persisted read-only mode:
 
 ```bash
-# NOTE: resume rejects -s. Force read-only via -c sandbox_mode, or Codex
-# inherits config.toml (possibly danger-full-access) and could write files.
-CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: STABLE across round-1+resume turns, collision-free under parallel sessions
-codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
-  -o $CODEX_TMP/verdict.txt \
-  "I revised the plan. Re-review PLAN.md. Same rules. End with VERDICT: APPROVED or VERDICT: REVISE." \
-  < /dev/null 2>/dev/null >/dev/null &
+if ROUND_RESULT=$(scripts/codex-exec.sh resume "$RUN_ID" --prompt "I revised the plan. Re-review PLAN.md. Same rules. End with VERDICT: APPROVED or VERDICT: REVISE."); then
+  CODEX_REPORT=$(printf '%s\n' "$ROUND_RESULT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["verdict"])')
+else
+  FAILURE_RESULT=$(scripts/codex-exec.sh handle-failure --result "$ROUND_RESULT" --run-id "$RUN_ID") || :
+  printf '%s\n' "$FAILURE_RESULT" >&2
+  exit 1
+fi
 ```
-Wrap resume in the **same 90s liveness probe** (background + `wait`). Resume discards the `--json` stream, so probe on the verdict file: `BYTES=$(wc -c < $CODEX_TMP/verdict.txt)` plus the `CPU` check — `00:00:00` CPU + empty verdict at 90s → kill, treat as `CODEX-HUNG`, same STOP path as round 1.
 
-**Overall ceiling (both rounds):** the 90s probe catches silent hangs, not long stuck runs. Cap every `codex exec` / `codex exec resume` at **10 minutes** — via Claude Code's Bash tool pass `timeout: 600000` on the tool call (the default 2-minute tool timeout would kill real reviews mid-run); in a plain shell prefix `timeout 600` (macOS: `gtimeout 600` via coreutils). If the ceiling trips, treat it as a failed round: stop and tell the user rather than retrying blind.
+The wrapper owns stdin closure, hang detection, the overall timeout, stderr
+redaction, and its process group. `handle-failure` surfaces the structured
+status and cleanup metadata, then the caller stops before report handling. A
+surfaced `HUNG` returns to the user for the choice to retry once with a fresh
+run or continue without cross-model review. Never inspect, signal, or kill
+foreign Codex processes.
+
+Separately, cancellation or a decision to stop orchestration after an OK round
+but before normal finalize must abort the known run:
 
-Both `codex exec` and `codex exec resume` support `--json` (stream → parse `thread_id` first round) and `-o/--output-last-message` (verdict capture).
+```bash
+scripts/codex-exec.sh abort "$RUN_ID"
+```
 
 **Each round, after Codex returns:**
-1. Read `$CODEX_TMP/verdict.txt`. Append to `LOG_FILE`: `## Round <n> — Codex` + the full critique.
+1. Read `CODEX_REPORT`. Append to `LOG_FILE`: `## Round <n> — Codex` + the full critique.
 2. Grep the last line for the verdict token.
    - `VERDICT: APPROVED` → break the loop, go to Step 3 (converged).
    - `VERDICT: REVISE` → Claude reads the critique, decides **what's actually worth acting on** (Claude has final say — Codex advises, it does not command). Revise `PLAN_FILE`. Append to `LOG_FILE`: `### Claude's response` + what you changed and what you rejected and why. Increment `ROUND`.
 3. If `ROUND > MAX_ROUNDS` → break to Step 3 (deadlock).
 
+After harvesting the final report and updating the log, delete the successful
+run state:
+
+```bash
+scripts/codex-exec.sh finalize "$RUN_ID"
+```
+
 ### Step 3 — Resolution (human gate #2)
 
 **If APPROVED:** Present to the user — the final `PLAN_FILE`, a 3-bullet summary of what the argument improved, and the round count. Ask: *"Plan survived N rounds of Codex. Implement it now — Codex builds it (`/codex-build`), Claude builds it, or stop here?"* Only on a yes is code written. **No code is written during the loop.** If the user picks Codex, invoke the `codex-build` skill with `SPEC_FILE=PLAN.md` and the same `LOG_FILE` — roles flip (Codex writes in a bounded workspace-write sandbox, Claude reviews the diff) and the build rounds append to the same log.
@@ -131,7 +139,9 @@ Both `codex exec` and `codex exec resume` support `--json` (stream → parse `th
 
 ## Hard rules
 
-- Codex is read-only EVERY round — `-s read-only` for the first call, `-c sandbox_mode="read-only"` for every resume (resume has no `-s`). It never writes. If you're tempted to give it write access, stop — that's a different skill.
+- Codex is read-only EVERY round. Establish that once with the wrapper's
+  `review` + `read-only` new call; every resume inherits it. If you're tempted
+  to give it write access, stop — that's a different skill.
 - The loop ALWAYS terminates at `MAX_ROUNDS`. No unbounded recursion.
 - Claude is the final arbiter on every REVISE — incorporate good critiques, reject bad ones *with a reason logged*. Don't cave to Codex on everything (that defeats the cross-model check) and don't ignore it (that defeats the point).
 - Code only after human gate #2.