Codex Workflows

Use this skill for headless parallel Codex dispatch or when cmux is unavailable. Healthy cmux panes remain the default for visible, reachable single-worker tasks; headless mode is a fan-out engine and degraded fallback, not a cmux replacement.

Run the harness through scripts/codex-workflows.sh. Detailed interfaces are in workflows/agent.md, workflows/parallel.md, and workflows/pipeline.md.

Primitives

• agent creates one isolated worktree, launches one worker, verifies startup, and records it in an explicit manifest.
• parallel validates a JSON fan-out spec, launches every worker before watching, and keeps every outcome in one manifest.
• pipeline runs ordered stages, parallel within a stage, and stops on failure before the next stage unless continue_on_failure is explicitly enabled.
• watch observes process exit first, then parses the finished log once.
• status and harvest inspect and collect a completed run. The dispatching lead owns harvesting and retiring its nested .codex-workflows lanes. Nightly GC deliberately excludes .worktrees/.codex-workflows/ and $HOME/Gits/worktrees/.codex-workflows/; it is not their backstop. Cleanup uses the workspace retirement guard and records its receipt in the lease ledger. The lead must inventory and preserve artifacts, local history and consumer obligations before authorizing retirement. Harvest alone is insufficient; cleanup is not automatic. Untracked files retain the worktree.

Interrupted cleanup token recovery

Cleanup publishes its private close token atomically in the run directory, outside the worker worktree. A crash after begin-close returns but before token publication can leave a lease in closing without a usable token file. Run lease.py audit --json and inspect that lease's closing_since and closing_age_seconds; it never expires or releases itself. If the token from the begin-close stdout log was securely preserved, the operator can run lease.py abort-close --lease-id <id> --close-token <token> and then reconcile any stale token file before another cleanup attempt. Treat that token as a secret. The workflow normally captures stdout in memory and does not create a token log, so it may be unavailable after a crash. If it cannot be recovered, leave the lease reported as closing; do not auto-release it or delete the worktree. Inspect and preserve any stale or partial token file before reconciliation; its presence alone does not prove a complete token was published.

Non-Negotiable Guards

1. Discover the real default branch with git remote show origin. Never assume main or master.
2. Launch $HOME/.local/bin/codex through /usr/bin/nohup. Never invoke bare codex; a captured PID is not a worker.
3. Use one worktree, branch, and log per worker. Grant workspace-write access to the repository Git directory and explicit reporting paths with --add-dir.
4. Verify startup after a grace period. Report FAILED_LAUNCH loudly when the process died or launcher diagnostics show an executable, command, or fetch failure.
5. Never live-grep a worker stream. Wait for process exit, then extract exact TASK_DONE, PR URLs, and failures from structured finished-log events.
6. Choose the pin through agent-routing/references/model-and-effort.md, which owns the routing and escalation rules. When model is omitted, the harness resolves codex.implement through scripts/model-roles.mjs --field model --stable. Installed copies need a linked checkout or GOLEMS_MODEL_ROLES_ROOT=<golems-checkout>; missing registries and unbenched defaults fail closed. Record effective model/effort, output tokens and wall-clock duration in the manifest and run log.
7. Treat TASK_DONE as a signal, not artifact proof. Harvest only declared worktree-relative, non-symlink artifacts; do not clean up before harvest.

Worktree Hygiene (folded from superpowers:using-git-worktrees, 2026-09-02)

Guard 3 says one worktree per worker; these two checks say the worktree is safe to work in. Folded when the superpowers plugin was dropped (XS-2) — source superpowers/3.4.1/skills/using-git-worktrees/SKILL.md L55-69 and L120-134.

1. Verify the worktree root is git-ignored BEFORE creating anything in it. Repo law puts worktrees at <repo>/.worktrees/<name> (AGENTS.md), so the only open question is whether git ignores that path here:

   # Probe a CHILD path, not the bare root: `.worktrees*/` is a directory-only
   # pattern, so `git check-ignore -q .worktrees` returns 1 on a fresh checkout
   # where the directory does not exist yet — a false "NOT ignored".
   git check-ignore -q .worktrees/probe || { echo ".worktrees NOT ignored"; exit 1; }

   Not ignored means every worker's checkout shows up as untracked files in the parent repo and can be committed by accident. Fix it (add the line, commit it) before the first git worktree add, never after. (L55-69)

2. Prove a clean baseline before the worker implements anything. Run the project's test command in the fresh worktree first and record the result in the manifest. A green baseline is what lets you attribute a later failure to the worker's change; without it you cannot tell a new bug from a pre-existing one. Baseline red is not a blocker by itself — report the failures and get an explicit go/no-go rather than silently building on top of them. (L120-134)

Degraded-Mode Contract

Every headless run and worker record must state the same four facts:

• lead-reachable-only
• no-pane
• no-listen-name
• no-self-monitor

Name the dispatching lead. ARM-MONITORS registration must describe the worker as lead-reachable-only; do not invent a pane, listen-name, or monitor.

Completion Interpretation

parallel without --watch proves launch only, records completion_proven: false, prints LAUNCH_ONLY, and exits 75 so it cannot be mistaken for completed work. With --watch, success requires every worker to reach completed. failed_launch, failed, run-level watch_timeout, parser_failed, and incomplete all return nonzero. A watch timeout preserves the live process and log so another watch can resume.

See references/manifest.md for states and references/composition.schema.json for the fan-out/pipeline input contract.