Document reliable Codex review-fix loops

README.md

@@ -9,12 +9,12 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `
 | Skill | Version | Description |
 |-------|---------|-------------|
 | [choosing-swarm-patterns](skills/choosing-swarm-patterns/SKILL.md) | 1.1.3 | Pick the right Agent Relay orchestration pattern across the 10 core swarm patterns plus specialized patterns. |
-| [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.10 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, verification gates, mandatory Claude-then-Codex review/fix loops with test hardening, channels, and chat-native coordination recipes. |
+| [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.12 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, verification gates, mandatory Claude-then-Codex review/fix loops with test hardening, channels, and chat-native coordination recipes. |
 | [setting-up-relayfile](skills/setting-up-relayfile/SKILL.md) | 1.1.0 | Set up Relayfile mounts and writeback for provider files through local filesystem access. |
 | [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.2.0 | Coordinate agents in real time with Relaycast messaging, channels, threads, reactions, search, and webhooks. |
 | [running-headless-orchestrator](skills/running-headless-orchestrator/SKILL.md) | 1.0.5 | Self-bootstrap Agent Relay infrastructure and manage worker agents without human intervention. |
 | [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.7 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, mandatory Claude-then-Codex review/fix with test hardening, and commit gates. |
-| [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.0 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. |
+| [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.1 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. |
 
 ## Slash Commands
 

prpm.json

@@ -28,7 +28,7 @@
     },
     {
       "name": "writing-agent-relay-workflows",
-      "version": "1.6.11",
+      "version": "1.6.12",
       "description": "Use when building multi-agent workflows with relay broker-sdk. Covers conversation vs pipeline coordination, WorkflowBuilder/DAG steps, agents, {{steps.X.output}} chaining, repairable verification gates, evidence-based completion, mandatory Claude-then-Codex fresh-eyes review/fix loops with test hardening, channels, chat-native recipes, error handling, event listeners, step sizing, lead+workers teams, and parallel waves.",
       "format": "claude",
       "subtype": "skill",
@@ -126,7 +126,7 @@
     },
     {
       "name": "review-fix-signoff-loop",
-      "version": "1.0.0",
+      "version": "1.0.1",
       "description": "Use when writing Agent Relay or Ricky workflows that must loop review, fix, and validation with fresh agent context until independent signoff agents both agree the work is comprehensively complete",
       "format": "claude",
       "subtype": "skill",

skills/review-fix-signoff-loop/SKILL.md

@@ -15,6 +15,7 @@ Pair this with `writing-agent-relay-workflows` for SDK syntax and `relay-80-100-
 
 1. Run deterministic preflight before agents start.
    - Confirm repository root, required specs, declared write scope, credentials needed for PR comments, and whether commit/push/PR creation is in scope.
+   - Probe the CLIs used by later agent steps. For Codex, `codex login status` is not enough; run a tiny `codex exec --ephemeral --json --sandbox read-only -m <supported-model>` prompt and fail early with a clear re-login instruction if it cannot return the expected token.
    - Write preflight evidence to `.workflow-artifacts/<workflow>/iteration-N/preflight.md`.
 
 2. Implement with scoped owners.
@@ -39,6 +40,7 @@ Pair this with `writing-agent-relay-workflows` for SDK syntax and `relay-80-100-
 6. Break only on dual signoff.
    - The loop may exit only when both reviewers write the exact satisfied verdict and final deterministic acceptance is green.
    - If either reviewer finds issues or is blocked, run a Codex fix pass and start a new fresh-context review iteration.
+   - Make the Codex fix pass a non-interactive one-shot worker (`preset: 'worker'`) with a `file_exists` verification for its durable report. Do not rely on interactive PTY idle detection or `/exit` for loop progress.
 
 7. Report final signoff.
    - Write a final `SIGNOFF.md` that includes iteration count, validation evidence, Claude rationale, Codex rationale, remaining risks, and artifact paths.
@@ -77,6 +79,7 @@ Prefer an outer loop that starts a new Agent Relay workflow run per iteration:
 ```typescript
 for (let iteration = 1; ; iteration += 1) {
   await runIteration(iteration, runStamp); // new workflow name, channel, and agent names
+  clearStartFromAfterResumedIteration();
   if (hasDualSignoff(iteration)) {
     writeAndPostSignoffReport(iteration);
     break;
@@ -96,6 +99,30 @@ workflow(`my-feature-completion-${suffix}`)
 
 This prevents reviewer memory from a previous loop from becoming the reason the loop exits.
 
+If the outer loop supports `--start-from`, consume it for only the resumed iteration. `START_FROM=fix-review-findings` must not leak into the next fresh-context iteration, or the next iteration will skip review/validation and fail on missing artifacts. After a completed resumed iteration, delete `process.env.START_FROM` and `process.env.PREVIOUS_RUN_ID` before continuing the loop.
+
+## Codex Fixer Reliability
+
+For review-fix loop steps, prefer this shape:
+
+```typescript
+.agent(`codex-review-fixer-${suffix}`, {
+  cli: 'codex',
+  model: CodexModels.GPT_5_4,
+  preset: 'worker',
+  role: 'Review-finding fixer. Repairs valid findings and hardens tests/proofs.',
+  retries: 2,
+})
+.step('fix-review-findings', {
+  agent: `codex-review-fixer-${suffix}`,
+  dependsOn: ['dual-signoff-gate'],
+  task: `Read iteration artifacts. Fix every valid finding, rerun relevant checks, and write ${dir}/review-fix-report.md.`,
+  verification: { type: 'file_exists', value: `${ROOT}/${dir}/review-fix-report.md` },
+})
+```
+
+Use interactive PTY Codex only when the step genuinely needs live channel coordination. For bounded artifact-producing fix/review steps, `preset: 'worker'` exits through the subprocess lifecycle, and `file_exists` proves the required artifact exists.
+
 ## PR Signoff Comment
 
 Final signoff should be both a durable artifact and a PR comment.

skills/writing-agent-relay-workflows/SKILL.md

@@ -1085,6 +1085,8 @@ Steps with `dependsOn` wait for all listed steps. Steps with no dependencies sta
 
 Do NOT add exit instructions to task strings. The runner handles this automatically.
 
+For bounded Codex steps that must produce one artifact or a structured answer, use a non-interactive preset (`preset: 'worker'`, `reviewer`, or `analyst`) instead of interactive PTY. This runs through one-shot subprocess mode (`codex exec`), so completion is the process lifecycle plus verification. Interactive Codex is for live channel coordination; it is weaker for "write one file then exit" loops because idle detection can see an auth or prompt-delivery failure as silence.
+
 ### Step Completion Model
 
 Steps complete through a multi-signal pipeline (highest priority first):
@@ -1950,6 +1952,7 @@ When you set `.pattern('supervisor')` (or `hub-spoke`, `fan-out`), the runner au
 | Self-review step with no timeout | Set `timeout: 300_000` (5 min) — Codex hangs in non-interactive review |
 | One giant workflow per feature | Split into smaller workflows that can run in parallel waves |
 | Adding exit instructions to tasks | Runner handles self-termination automatically |
+| Interactive PTY Codex for one-shot artifact steps | Use `preset: 'worker'` plus `file_exists` or `custom` verification |
 | Setting `timeoutMs` on agents/steps | Use global `.timeout()` only |
 | Using `general` channel | Set `.channel('wf-name')` for isolation |
 | `{{steps.X.output}}` without `dependsOn: ['X']` | Output won't be available yet |
@@ -1978,6 +1981,7 @@ When you set `.pattern('supervisor')` (or `hub-spoke`, `fan-out`), the runner au
 | Single step editing 4+ files | Agents modify 1-2 then exit. Split to one file per step with verify gates |
 | Relying on agents to `git commit` | Agents emit markers without running git. Use deterministic commit step |
 | File-writing steps without `file_exists` verification | `exit_code` auto-passes even if no file written |
+| Codex login checked only with `codex login status` | Add a tiny `codex exec --ephemeral --json --sandbox read-only` preflight probe so stale refresh tokens fail before agent steps |
 | Edit gate uses `git diff --quiet` for new files/packages | `git diff` ignores untracked files and can fail a valid implementation with `NO_CHANGES`; use `git status --short -- <paths>` for materialization gates |
 | Hard-stop validation gates in product workflows | A red check stops the agent team at the exact moment it should fix the problem. Capture gate output with `failOnError: false`, add a repair agent step, rerun, and reserve hard failure for exhausted repair budget or external blockers |
 | Final acceptance before repair and dual review | Broken work can stop or commit without giving the team a final chance to fix it. Run repairable gates first, then the Claude-then-Codex review/fix loops, then final deterministic acceptance before commit/PR |