preflight

Preflight (Phase 0 — run FIRST, it is a gate)

Nothing downstream is safe until these pass. Do not interview, plan, or execute until the gate is green.

Step 1 — Health gate

Call mcp__codex__codex_health with { deep: true } ONCE before anything else. The deep input adds a one-shot read-only codex exec probe and returns execProbe (ok | quota | model | error | skipped) plus execProbeMessage next to loggedIn; read execProbe from that single call instead of re-probing later phases.

• Tool call fails / server missing → the MCP server isn't set up. Point the user to the codex-mcp README install steps (or node scripts/doctor.mjs), then offer the command's Executor fallback: fix and re-check, or continue with Claude as executor. Never continue silently.
• loggedIn: false → tell the user to run codex login (ChatGPT Plus/Pro/Team, or set OPENAI_API_KEY), then offer the same Executor fallback choice. Proceed only after a re-check shows loggedIn: true or the user explicitly chose the fallback.
• execProbe: quota or execProbe: model → logged in but unable to execute. Quote execProbeMessage and offer the Executor fallback right away; a quota or model probe result is sufficient on its own and requires NO unhealthy health re-check.
• execProbe: error → report execProbeMessage verbatim, then offer the same fallback choice.
• loggedIn: true with execProbe: ok (or skipped) → report the Codex version, record executor: codex, and continue.
• The analysis lane of the Fast-path gate needs no Codex session and no fallback decision; when its optional Codex second opinion fails, the analysis is delivered Claude-only with the failure named in the "what I verified" note.

Step 2 — Resume check (don't clobber an interrupted run)

If .codex-flow/STATE.md exists, treat it as an interrupted run even when PLAN.md or TASKS.md has not been created yet:

• Read .codex-flow/STATE.md as the resume authority. Its approval fields decide which phases may be skipped; any phase whose approval is not recorded MUST be re-run. The existence of PLAN.md/TASKS.md is NOT proof of approval.
• When both .codex-flow/PLAN.md and .codex-flow/TASKS.md exist, run node "${CLAUDE_PLUGIN_ROOT}/scripts/context-slice.mjs" --resume and read .codex-flow/RESUME.md instead of the raw files. If the helper is unavailable in a standalone install, fall back to reading PLAN.md and TASKS.md directly. If the helper is present but exits non-zero, surface the error to the user and STOP; never use the standalone fallback for a failing helper. When either file does not exist, read only the control files that exist; do not require a missing TASKS.md to resume an earlier phase.
• When TASKS.md exists, show its task Statuses. Ask resume vs restart in every case except phase: complete, which archives and starts fresh without a resume offer (see below).
• Before scheduling anything, reconcile every task whose Status is in-progress. Read its recorded Session line. The resume slice's Task statuses section carries Session content for every in-progress task even though it embeds the full task text only for the first unfinished task; do not assume the other in-progress task blocks are embedded. A launching line may be sequential (- Session: launching (base: <short sha>)) or parallel (- Session: launching (base: <short sha>, worktree: <path>, branch: <name>)). Extract the base sha from either launching form or the completed-session form. Then cross-check git log --oneline <base sha>..HEAD and git status for changes to the task's declared Files: since that base. Report the evidence and ask the user to choose exactly one: continue in the recorded session (when a real session id exists) / review the work as-is / reset to pending. For reset to pending, roll back through the checkpoint commit when checkpointCommits is enabled. Never blindly re-execute an in-progress task.
• phase: complete → terminal, not resumable. Do NOT offer resume: archive the run's control files to .codex-flow/archive/<timestamp>/ and begin fresh, exactly as Restart does. Resume is offered only for a non-complete phase.
• Resume → first run node "${CLAUDE_PLUGIN_ROOT}/scripts/flow-state.mjs" check, adding --tasks .codex-flow/TASKS.md whenever that file exists so the terminal-status validation runs (node "${CLAUDE_PLUGIN_ROOT}/scripts/flow-state.mjs" check --tasks .codex-flow/TASKS.md); when it reports only missing keys on a legacy file, add them with set (currentTask -, taskStage idle, wave -) and continue; any other violation is surfaced to the user before routing. Then skip only the phases whose approvals STATE.md records, and route from STATE.md's recorded phase. For phase: execution, enter Phase 4 at the first task not marked done. Before that, first route by taskStage regardless of currentTask (currentTask names the task in sequential mode; in parallel mode it is - and wave names the wave): reviewing → resume Phase 5 for that task; launching or executing → run the in-progress reconciliation above before anything else; handoff → finish Phase 5 step 7's durable handoff (or the wave's Step 3.8); merge-conflict → surface the conflict to the user and STOP; idle → the next pending task. For phase: review, resume Phase 5 completion work; when all tasks are done but phase is not complete, also resume Phase 5 for the final dual review, requirement ID-walk, improvement gate, cost/report delivery gates, and completion write instead of concluding there is no work. For an earlier phase, enter its first unapproved gate. Treat every [verify] block as a hypothesis: confirm it against git diff and the current code before relying on it. Record the current git rev-parse HEAD as resumeHead and update phase; apart from the legacy-key backfill above, change no other STATE.md key as part of the resume operation. The reconciliation choice for an in-progress task (continue / review as-is / reset) is made first; the taskStage routing then applies to the task as the user left it.
• On resume, reuse the report dir recorded under ## Session report in PLAN.md; create it only if missing.
• Restart → archive the old control files that exist to .codex-flow/archive/<timestamp>/, then begin fresh.