@mmerterden/multi-agent-pipeline 12.10.0 → 13.0.0

package/pipeline/commands/multi-agent/testflight-validation/SKILL.md

@@ -0,0 +1,219 @@
+---
+description: "Pre-submission validation for a TestFlight / App Store build (iOS, local-only). Three gates: static archive audit, Apple's own `altool --validate-app`, and a Review-Guidelines check. ITMS codes are mapped to the rule each implies. Validates only, never uploads. Use when a build is about to go to TestFlight, or a submission was rejected and you need why."
+description-tr: "TestFlight / App Store yüklemesi öncesi doğrulama (iOS, yalnızca lokal). Repo + branch seç, sonra ya build'i sen ver ya da koşu archive alsın; üç kapıyı geç: statik 18-kurallı archive denetimi, Apple'ın kendi `altool --validate-app`'i, ve App Store Review Guidelines'a karşı guideline incelemesi. Her kapı için ayrı verdict, ITMS kodları ilgili kurala eşlenmiş. Sadece doğrular  -  asla yüklemez."
+argument-hint: "[repo]  -  empty = pick from prefs; repo name or path; --ipa=<path>; --archive=<path>; --resume"
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__dev-toolkit__ios_app_store_audit, mcp__dev-toolkit__ios_export_ipa, mcp__dev-toolkit__ios_testflight_validate, mcp__dev-toolkit__ios_xcodebuild, mcp__dev-toolkit__ios_xcresult
+---
+
+# /multi-agent:testflight-validation  -  pre-submission validation
+
+Catch, before you upload, what App Store Connect would send back after you do.
+
+**Local-only.** No commits, no push, no PR, no channels. The worktree exists only
+to archive without touching your working tree.
+
+**It never uploads.** Only `--validate-app` is ever invoked, never `--upload-app`.
+A validation run must not be able to ship a build by accident.
+
+## Why three gates and not one
+
+Each gate sees something the others structurally cannot. Reporting one of them as
+"the check" is how a build passes locally and gets rejected anyway.
+
+| Gate | What runs | Needs | Sees | Blind to |
+|---|---|---|---|---|
+| **1. Static** | `ios_app_store_audit` (18 rules, real ITMS codes) | an `.xcarchive` | privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, binary size | anything that depends on the App Store Connect account |
+| **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | an `.ipa` + credentials | unregistered bundle ID, profile that does not match the app record, **a version+build pair already used**, entitlements not provisioned for the App ID | the Review Guidelines  -  Apple's validator does not read them |
+| **3. Guideline** | `app-store-review` skill + repo evidence | repo checkout | ATT flow, privacy policy, account deletion, IAP rules, purpose-string wording, permission justification | anything not visible in source |
+
+Gate 2 is the only one that asks Apple, and Gate 3 is the only one that covers the
+rejections a human reviewer writes. Most "we passed validation and still got
+rejected" cases are Gate 3 findings.
+
+## Step 0  -  parse input
+
+| Input | Meaning |
+|---|---|
+| (empty) | ask which repo (Step 1) |
+| `my-ios-app` or a path | that repo |
+| `--ipa=<path>` | Mode B with an `.ipa`; Gate 1 cannot run (see Step 3) |
+| `--archive=<path>` | Mode B with an `.xcarchive`; all three gates run |
+| `--resume` | continue the last run from its state file |
+
+State lives at `$HOME/.claude/logs/multi-agent/<task_id>/agent-state.json` with
+`taskId = TFV-<repo>-<yyyymmddHHMM>`. Register phases with the tracker
+(`$HOME/.claude/multi-agent-refs/tracker-contract.md`) so `:resume` and `:status`
+work like any other run.
+
+## Step 1  -  pickers (native, always)
+
+Use `AskUserQuestion` for every step  -  never a numbered text menu. Questions and
+descriptions render in `prefs.global.outputLanguage`; `label` and `header` stay
+English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
+`Step <i>/<n>: <what this decides>` breadcrumb for each.
+
+1. **Repo**  -  from `prefs.projects` where the stack is iOS. A single match
+   auto-resolves (say so in the breadcrumb, do not silently skip the step).
+2. **Branch**  -  the branch to validate. Resolution order:
+   - `git fetch --prune` first, capturing **stderr**. **If the fetch fails, do not
+     silently fall back to a cached ref**, and **classify before naming a cause**  -
+     the same rule as the `/multi-agent:dev` remote gate:
+
+     | stderr contains | Cause | Remedy |
+     |---|---|---|
+     | `could not read Password`, `Authentication failed`, `403` | credential | store the PAT in the credential helper or switch the remote to SSH. **A VPN cannot fix this**, and the base ref being stale is unrelated to what broke  -  do not offer the cached-ref fallback. |
+     | `Could not resolve host`, `Operation timed out`, `Connection refused` | network | retry / continue on the cached ref with an explicit warning / switch remote / abort, per `$HOME/.claude/multi-agent-refs/rules.md` |
+     | `Repository not found`, `404` | wrong remote | show `git remote -v` and ask |
+
+     Always print the observed stderr line next to the classification. Asserting
+     `unreachable (VPN/DNS)` for a missing-credential error that returns in under a
+     second sends the user to fix something that was never broken.
+   - Offer the current branch, the default branch, and any `release/*` /
+     `tkdevelop/*` heads.
+3. **Mode**  -  how the build is obtained:
+   - `Supply a build` (Mode B, default)  -  fastest, no signing needed in-run.
+   - `Archive from this branch` (Mode A)  -  needs a distribution certificate and
+     profile in the keychain, and takes as long as a release archive.
+
+## Step 2  -  pre-flight, before anything expensive
+
+Report every line; a missing prerequisite is a halt, not a warning.
+
+```bash
+xcrun --find altool >/dev/null 2>&1 || echo "MISSING: altool (install Xcode)"
+xcodebuild -version | head -1
+```
+
+Then resolve credentials, and **state which tier is active in the report**:
+
+| Tier | Source | Effect |
+|---|---|---|
+| 1 | ASC API key  -  key id + issuer id from the keychain via `prefs.global.keychainMapping`, `.p8` at `~/.appstoreconnect/private_keys/AuthKey_<keyId>.p8` | Gate 2 runs |
+| 2 | Apple ID + app-specific password, referenced as a keychain item | Gate 2 runs |
+| 3 | neither | **Gate 2 reports `SKIPPED`, and the run says so in the verdict line** |
+
+Credentials come from `/multi-agent:setup`; never prompt for a secret value in
+chat. If nothing is configured, tell the user which of the two tiers they can set
+up and that tier 2 needs no elevated App Store Connect role.
+
+Multi-provider accounts need `--provider-public-id`. When it is not in prefs, run
+`ios_testflight_validate({list_providers: true})` once and ask which provider.
+
+## Step 3  -  obtain the build
+
+### Mode B  -  a build you supply
+
+- `.xcarchive` → Gate 1 runs on it. To reach Gate 2 the archive must be exported,
+  so run `ios_export_ipa` (see Mode A step 3 for the signing inputs).
+- `.ipa` only → **Gate 1 is reported `SKIPPED (needs .xcarchive)`.** The static
+  audit reads archive structure that an `.ipa` does not carry. Do not present a
+  two-gate run as a full pass; say which gate did not run and why, and offer to
+  re-run with the archive.
+
+### Mode A  -  archive from the branch
+
+1. Worktree at `{projectRoot}/{worktreeBasePath}/{taskId}` on the chosen branch.
+   **Never under `$HOME`**, never a direct checkout of the main working tree.
+2. Resolve the scheme and workspace/project from prefs; ask if ambiguous.
+3. Archive:
+   `ios_xcodebuild({workspace|project, scheme, action: "archive", configuration: "Release", destination: "generic/platform=iOS"})`
+   Note the destination: the simulator default would produce an archive that
+   cannot be exported for distribution.
+4. Export:
+   `ios_export_ipa({archive_path, output_dir, method: "app-store-connect", team_id, provisioning_profiles?, signing_style?})`
+   Leave `allow_provisioning_updates` off unless the user asks: it lets xcodebuild
+   create or modify profiles in the developer account, which a validation run has
+   no business doing.
+5. A failed export halts with the parsed errors. The usual causes are a missing
+   distribution certificate, a profile that does not match the bundle ID, or
+   `signing_style: "manual"` with no `provisioning_profiles` map.
+
+## Step 4  -  Gate 1, static audit
+
+`ios_app_store_audit({archive_path, rules: "all"})`.
+
+`error` findings are blocking; `warning` is advisory. Group the output by severity
+and keep each finding's ITMS code  -  Gate 2 may return the same code, and seeing
+it in both places tells the user it is real rather than a heuristic.
+
+## Step 5  -  Gate 2, Apple's own validation
+
+`ios_testflight_validate({ipa_path, platform: "ios", <credential args>})`.
+
+Render the verdict exactly as returned:
+
+- `PASS`  -  Apple accepted the binary for delivery.
+- `FAIL`  -  list each issue with its ITMS code, the mapped guideline, and the hint.
+- `SKIPPED`  -  print the reason. **Never render this as a pass.** The verdict line
+  for the whole run must read `2 of 3 gates cleared, 1 skipped`, not `passed`.
+
+Gate 2 is the only gate that catches a build number already used  -  the most
+common wasted upload  -  so when it fails on that, say so plainly and name the next
+free build number.
+
+## Step 6  -  Gate 3, guideline review
+
+Load the `app-store-review` skill and review the repo against it. This is the gate
+that catches what a human reviewer rejects, so it reads source, not the binary:
+
+| Area | Evidence to gather |
+|---|---|
+| Purpose strings | every `NS*UsageDescription` in Info.plist  -  present, specific, user-facing, and matching what the code actually does with the data |
+| Privacy manifest | `PrivacyInfo.xcprivacy` exists, declares required-reason APIs, and matches the SDKs actually linked |
+| Tracking | if any tracking API or SDK is present, an ATT prompt exists and runs before collection |
+| Account deletion | if the app creates accounts, an in-app deletion path exists (guideline 5.1.1(v)) |
+| Privacy policy | reachable in-app and in the metadata |
+| IAP | anything unlocking features goes through StoreKit, with no external purchase path |
+| Sign in with Apple | present when a third-party social login is offered |
+
+For each: `pass` / `fail` / `not-applicable` with the evidence path that justifies
+it. `not-applicable` needs a reason  -  an unexamined area is not a pass.
+
+## Step 7  -  report
+
+Write to `~/TestFlightChecks/<repo>-<branch>-<timestamp>/report.md` and print a
+summary. Structure:
+
+```
+Verdict: <N> of 3 gates cleared[, <M> skipped]
+Build:   <ipa or archive path>  ·  <bundle id> <version> (<build>)
+Auth:    tier <1|2|none>  ·  <method>
+
+Gate 1  static audit        PASS | FAIL (<n> blocking, <n> advisory) | SKIPPED (<reason>)
+Gate 2  Apple validation    PASS | FAIL (<n> issues) | SKIPPED (<reason>)
+Gate 3  guideline review    PASS | FAIL (<n> findings) | <n> not-applicable
+
+Blocking  -  fix before uploading
+  [ITMS-90683] Info.plist: NSCameraUsageDescription missing
+      guideline 5.1.1 Data Collection and Storage
+      <hint>
+      <file:line>
+
+Advisory
+  ...
+
+Not run
+  Gate 1: needs an .xcarchive; only an .ipa was supplied
+```
+
+Rules for the report:
+
+- A skipped gate is never folded into the pass count. The verdict line states the
+  skip.
+- Every blocking finding carries a file path or an ITMS code. A finding the user
+  cannot act on is noise.
+- No AI or assistant attribution anywhere, per
+  `$HOME/.claude/rules/git-conventions.md`.
+- Real newlines, no HTML entities, per
+  `$HOME/.claude/rules/pipeline-output-formatting.md`.
+
+## Step 8  -  offer the next action, do not take it
+
+Print, and stop:
+
+- the exact `xcrun altool --upload-app` command for when the gates are clear, so
+  uploading stays an explicit human act
+- `/multi-agent:testflight-validation --resume` to re-run after fixes
+- `/multi-agent:fix-bug` when Gate 3 produced code-level findings
+
+Never upload, never bump the build number, never commit.

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -52,15 +52,18 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
-4c. **Prune retired adapter files** (Cursor / Antigravity / Codex / Copilot Chat were removed in v10.7.0 - the pipeline now targets Claude Code + Copilot CLI only):
+4c. **Prune retired adapter files** (Cursor / Antigravity / Copilot Chat were removed in v10.7.0 - the pipeline targets Claude Code, Copilot CLI and Codex CLI):
    ```bash
-   # Global Codex adapter prompt is safe to remove (no longer produced).
-   rm -f "$HOME/.codex/prompts/multi-agent.md"
-   echo "  -> pruned retired global Codex adapter prompt (if present)"
    # Per-project adapter files (.cursor/, .agent/, .github/copilot-instructions.md)
    # live in your repos and are left untouched - remove them manually if you like.
+   echo "  -> no global adapter files to prune"
    ```
 
+   > **Do NOT delete `$HOME/.codex/prompts/multi-agent.md`.** Releases up to
+   > v12.11.0 removed it here as a retired v9.7.0 adapter leftover. Codex CLI is a
+   > supported target again as of v13.0.0 and the installer writes that file, so
+   > deleting it silently breaks the `/multi-agent` slash command on Codex.
+
 5. **Migrate preferences** (if there is an old schema):
    ```bash
    if [ -f "$HOME/.claude/scripts/migrate-prefs.mjs" ]; then

package/pipeline/multi-agent-refs/_input-parser.md

@@ -6,7 +6,7 @@ description: "Internal  -  input type detection for multi-agent dispatcher."
 
 The top-level `multi-agent` command classifies user arguments per the rules below.
 
-> **Language**: Schema reference only  -  no user-facing text. Picker UI strings always English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads stay English.
+> **Language**: Schema reference only  -  no user-facing text. Picker `label` + `header` always English (`promptLanguage` is locked to `"en"`); `question` + `description` follow `outputLanguage` per the `rules.md` matrix. Commit/PR/Jira payloads stay English.
 
 ## Type Table
 

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,19 +1,19 @@
-# Cross-CLI Contract (Claude Code ↔ Copilot CLI)
+# Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 > **Non-negotiable**. Any change that breaks this contract blocks merge. Validated by `smoke-cross-cli-behavior.sh`.
 
-**Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which CLI invokes it. This file is the source of truth for "what must stay the same."
+**Purpose**: every pipeline command must produce identical artifacts (state, logs, outputs) and respect identical placeholder vocabulary regardless of which of the three host CLIs invokes it. This file is the source of truth for "what must stay the same."
 
 ---
 
-## 1. Command Inventory (42 commands)
+## 1. Command Inventory (43 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
 ```
 
 Categories:
@@ -24,6 +24,7 @@ Categories:
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
+- **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
@@ -110,14 +111,43 @@ Legacy names found during the v3.7 audit  -  replaced per this contract.
 
 ---
 
-## 2.6 Intentional structural divergence  -  `multi-agent.md` vs `multi-agent/SKILL.md`
+## 2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator
 
-The top-level orchestrator has two deliberately different shapes on the two CLIs. This is **not drift**  -  it reflects a real capability gap between the host CLIs, and auditors must not flag it as a parity violation.
+The top-level orchestrator has two deliberately different shapes. This is **not
+drift**  -  it reflects a real capability gap between the host CLIs, and auditors
+must not flag it as a parity violation.
 
 | Surface | File | Shape | Why |
 |---|---|---|---|
-| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines  -  thin dispatcher that routes to `$HOME/.claude/multi-agent-refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
-| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+| Claude Code (colon-form) | `pipeline/commands/multi-agent/SKILL.md` | ~300 lines  -  thin dispatcher that routes to `$HOME/.claude/multi-agent-refs/phases/phase-N-*.md` on demand | Claude Code lazy-loads reference files, so only the active phase's docs enter the context window. Saves tokens. |
+| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md once the skill is dispatched; it has no equivalent of Claude's ref-file loading. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+| Codex CLI | installed as `~/.codex/skills/multi-agent/SKILL.md`, generated from the Claude dispatcher | thin dispatcher, refs under `~/.codex/multi-agent-refs/` | Codex reads files on demand, so it takes the Claude shape  -  **and it has to.** See below. |
+
+### Why Codex takes the thin-dispatcher shape, and must keep it
+
+Codex assembles every discovered skill's name + description into a single prompt
+block and **silently drops entries when that block overflows**. Measured against
+Codex 0.145 during the install design: installing one plugin that declares 142
+skills took the block from 11 skills / 4,710 bytes to 83 skills / 22,111 bytes  -
+only **75 of the 142** surfaced, **and an unrelated user-scope skill was evicted**.
+Removing the plugin brought it back.
+
+So shipping the 43 sub-commands as peer skills on Codex would silently lose
+pipeline commands next to any stack toolkit, with no error anywhere. The pipeline
+therefore contributes **exactly one** skill on Codex (`multi-agent`) and keeps the
+43 sub-command specs as reference files that cost nothing until read.
+
+**Do not "fix" this by adding per-command skills on Codex.** The layout is
+capability-derived, and `smoke-install-layout.sh` fails if the Codex skills tree
+gains a second pipeline entry.
+
+### Parity axis differs per host
+
+Claude Code and Copilot CLI are compared on their **skill directory sets**. Codex is
+compared on its **ref set**: the 43 command specs must all exist under
+`~/.codex/multi-agent-refs/commands/<cmd>/SKILL.md`, and
+`smoke-codex-install.sh` asserts the count against the source tree. Comparing Codex
+on skill directories would demand exactly the layout that breaks it.
 
 **What must stay identical** (byte-level) across the two files:
 
@@ -175,13 +205,17 @@ argument-hint: "<input hint>"
 
 ### 4.1 TaskCreate ↔ phase-tracker.sh
 
-| Concept | Claude Code | Copilot CLI |
-|---|---|---|
-| Register a phase | `TaskCreate` tool call with subject/description | `phase-tracker.sh add <N> <name>` |
-| Mark a phase in-progress | `TaskUpdate` → `in_progress` | `phase-tracker.sh update <N> in_progress` |
-| Mark a phase complete | `TaskUpdate` → `completed` | `phase-tracker.sh update <N> completed` |
-| Mark a phase failed | `TaskUpdate` → `completed` + log failure in agent-log | `phase-tracker.sh update <N> failed` |
-| Sub-phase progress | TaskCreate with `addBlockedBy` | `phase-tracker.sh sub <N> <sub> <name> <status>` |
+| Concept | Claude Code | Copilot CLI | Codex CLI |
+|---|---|---|---|
+| Register a phase | `TaskCreate` tool call with subject/description | `phase-tracker.sh add <N> <name>` | `update_plan` step, `status: pending` |
+| Mark a phase in-progress | `TaskUpdate` → `in_progress` | `phase-tracker.sh update <N> in_progress` | `update_plan` step → `in_progress` |
+| Mark a phase complete | `TaskUpdate` → `completed` | `phase-tracker.sh update <N> completed` | `update_plan` step → `completed` |
+| Mark a phase failed | `TaskUpdate` → `completed` + log failure in agent-log | `phase-tracker.sh update <N> failed` | `update_plan` step → `completed` + failure in agent-log |
+| Sub-phase progress | TaskCreate with `addBlockedBy` | `phase-tracker.sh sub <N> <sub> <name> <status>` | `phase-tracker.sh sub ...` (the plan tool has no nesting) |
+
+`update_plan` takes the FULL step list, not a delta, so each boundary rewrites the
+whole plan. It must never be called in parallel with another tool, and it is
+unavailable in Codex plan mode  -  fall back to `phase-tracker.sh render` there.
 
 ### 4.2 Contract
 
@@ -227,9 +261,9 @@ Modifier flags are orthogonal and compose:
 
 ## 7. Platform Guards (macOS / Linux / WSL)
 
-Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
+Commands invoked via Copilot CLI or Codex CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
 
-For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on those installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
 
 | Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
 |---|---|---|

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -101,3 +101,32 @@ per-phase `model` field already carries the override).
   reviewer models (GPT-5.4 + Opus + Sonnet - Fable 5 is not offered there) and
   does not use this persona ladder. Only Claude Code dispatches Reviewer-1 on
   Fable.
+
+## Codex CLI
+
+Codex offers no Anthropic models, so the tier names map onto OpenAI models plus a
+reasoning effort - effort carries the depth distinction that the model id carries
+on Claude Code. The map is applied at install time by
+`install/_codex-agents.mjs`, which writes `model` + `model_reasoning_effort` into
+each `~/.codex/agents/<persona>.toml`:
+
+| Tier | Codex model | Effort |
+|---|---|---|
+| `fable` | `gpt-5.6` | `xhigh` |
+| `opus` | `gpt-5.6` | `high` |
+| `sonnet` | `gpt-5.4` | `medium` |
+| `haiku` | `gpt-5.6-terra` | `low` |
+
+Ladder on Codex: `gpt-5.6 @ xhigh -> gpt-5.6 @ high -> gpt-5.4 -> gpt-5.6-terra`.
+The first step down lowers effort rather than switching model, which is the
+cheapest useful degradation when the top tier is rate-limited rather than
+unavailable.
+
+**Per-dispatch override on Codex** goes through `spawn_agent`, and it MUST pass
+`fork_turns: "none"` (or a positive integer). A full-history fork inherits the
+parent model and reasoning effort and silently discards the override, so a
+fallback that omits it appears to apply while changing nothing.
+
+The three model ids above live in exactly three places - this table,
+`pipeline/scripts/cost-table.json`, and the Phase 4 reviewer matrix - so an OpenAI
+rename is a three-file change.

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -20,7 +20,7 @@ for proj in $(jq -r '.projects[] | "\(.name)\t\(.worktreePath)\t\(.baseBranch)"'
 done
 ```
 
-Same reviewer set (Fable-or-Opus / GPT-5.4 / Sonnet) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
+Same reviewer set (per host: Fable+Sonnet on Claude Code, Opus/GPT-5.4/Sonnet on Copilot CLI, gpt-5.6/gpt-5.4/gpt-5.6 on Codex CLI) receive `COMBINED_DIFF` with a multi-repo prefix in the system prompt:
 
 ```
 This is a multi-repo task spanning {N} repos: {repo names}.

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -101,7 +101,7 @@ Every phase that dispatches a billable LLM agent MUST forward its token totals t
 
 ```bash
 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
-  model=<fable|opus|sonnet|haiku|gpt-5.4> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED duration_ms=$DUR
+  model=<fable|opus|sonnet|haiku|gpt-5.4|gpt-5.6|gpt-5.6-terra> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED duration_ms=$DUR
 LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> tokens \
   model=<...> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED
 ```

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -300,11 +300,23 @@ Branch name is deterministic  -  no user confirmation needed.
 6. If empty after kebab (e.g. all-emoji title) → fall back to `task-{shortId}`
 
 **Collision handling** (automatic  -  no prompt):
-- Probe local + remote for existing branch:
+- Probe local + remote for existing branch. **Distinguish "no such ref" from "the
+  probe failed"**: with `2>/dev/null` and an empty-output test they look identical,
+  so an auth or network failure reads as "no collision" and the run creates a
+  branch that already exists on the remote  -  surfacing as a rejected push at
+  Phase 6, far from its cause.
   ```bash
   LOCAL_HIT=$(git -C "$root" rev-parse --verify --quiet "refs/heads/$branch")
-  REMOTE_HIT=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>/dev/null)
+  REMOTE_ERR=$(git -C "$root" ls-remote --exit-code --heads origin "$branch" 2>&1 >/dev/null)
+  REMOTE_RC=$?
+  # 0 = ref exists (collision) · 2 = no matching ref (authoritative "free")
+  # anything else = the probe itself failed; REMOTE_ERR holds why
   ```
+- `REMOTE_RC` is 0 or 2 → treat as authoritative
+- `REMOTE_RC` is anything else → the remote answer is **unknown**, not "free". Log
+  `Remote collision probe failed: <REMOTE_ERR>`, fall back to the local check only,
+  and record `"remoteCollisionProbe": "failed"` in `agent-state.json` so Phase 6
+  expects a possible non-fast-forward and re-checks before pushing.
 - No collision → use as-is
 - Collision found → append `-v2`, `-v3`, etc. until unique:
   `bugfix/ABC-12345` exists → `bugfix/ABC-12345-v2`

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -218,11 +218,42 @@ Launch Agent instances **in parallel** using the shared `code-reviewer` subagent
 
 **Scope from Step 1.77.** `$REVIEW_SCOPE == "single"` → dispatch **Reviewer 1 only**, and skip Step 2.5 + 3.6 (both no-ops with one reviewer). `"full"` (default + fail-safe) → the whole set below. Either way record the count in `consensus.reviewerCount`.
 
-| Reviewer   | subagent_type     | Model               | Focus                             | Skills Referenced                             | Where it runs        |
-| ---------- | ----------------- | ------------------- | --------------------------------- | --------------------------------------------- | -------------------- |
-| Reviewer 1 | `code-reviewer`   | `claude-fable-5` (Claude Code) / `claude-opus-4-8` (Copilot CLI) | Deep security + architecture      | `api-security-best-practices`, `architecture` | Both CLIs            |
-| Reviewer 2 | `code-reviewer`   | `gpt-5.4`           | Edge cases, different perspective | cross-model diversity                         | **Copilot CLI only** |
-| Reviewer 3 | `code-reviewer`   | `claude-sonnet-4-6` | Quality + correctness + naming    | `clean-code`, stack-specific skill            | Both CLIs            |
+| Reviewer   | subagent_type   | Claude Code | Copilot CLI | Codex CLI | Focus | Skills Referenced |
+| ---------- | --------------- | --- | --- | --- | --- | --- |
+| Reviewer 1 | `code-reviewer` | `claude-fable-5` | `claude-opus-4-8` | `gpt-5.6` @ `xhigh` | Deep security + architecture | `api-security-best-practices`, `architecture` |
+| Reviewer 2 | `code-reviewer` | (not dispatched) | `gpt-5.4` | `gpt-5.4` @ `high` | Edge cases, different perspective | cross-model diversity |
+| Reviewer 3 | `code-reviewer` | `claude-sonnet-4-6` | `claude-sonnet-4-6` | `gpt-5.6` @ `medium` | Quality + correctness + naming | `clean-code`, stack-specific skill |
+| Triage     | triage persona  | `claude-fable-5` | `claude-opus-4-8` | `gpt-5.6` @ `max` | Filter false positives + out-of-scope | - |
+
+Reviewer count per host: **Claude Code 2, Copilot CLI 3, Codex CLI 3**.
+
+#### Codex CLI  -  two constraints that fail silently
+
+Both were measured against Codex 0.145, not inferred. Getting either wrong produces
+a review that looks like it ran.
+
+1. **Every `spawn_agent` that sets `model` or `reasoning_effort` MUST pass
+   `fork_turns: "none"`** (or a positive integer). Codex states that a full-history
+   fork "inherits the parent model and reasoning effort and does not accept
+   overrides"  -  so omitting `fork_turns` silently collapses the whole panel onto
+   the orchestrator's model, with three reviewers reporting from one perspective
+   and no error anywhere.
+2. **Three concurrent children is the ceiling.** Codex advertises 4 concurrency
+   slots *including the orchestrator*, so a 3-reviewer panel saturates it and a 4th
+   child queues instead of running in parallel. The reviewer count on Codex is
+   capability-derived, not a preference.
+
+Codex also refuses to spawn sub-agents at all unless instructions ask for it
+explicitly; the pipeline's `~/.codex/AGENTS.md` managed block carries that
+authorization. Without it Phase 4 degrades to a single in-thread review.
+
+**Single-vendor caveat.** Every Codex reviewer is an OpenAI model, so the
+cross-vendor disagreement that Claude Code and Copilot CLI get for free is absent.
+The diversity budget shifts to reasoning effort and persona focus: Reviewer 1 runs
+`xhigh` on security and architecture, Reviewer 2 runs a different model family
+member on edge cases, Reviewer 3 runs `medium` on quality. Treat consensus among
+them as weaker evidence than the same consensus on a two-vendor host, and say so
+in the triage note when all three agree on a borderline finding.
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 

package/pipeline/multi-agent-refs/progress-contract.md

@@ -129,7 +129,7 @@ Every phase that dispatches a billable LLM agent MUST forward the call's token t
 
 ```bash
 LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
-  model=<fable|opus|sonnet|haiku|gpt-5.4> \
+  model=<fable|opus|sonnet|haiku|gpt-5.4|gpt-5.6|gpt-5.6-terra> \
   tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -24,7 +24,8 @@ The agent detects which CLI it's running in and uses the appropriate visual mech
 ```
 1. system prompt mentions "Claude Code"             → claude-code
 2. system prompt mentions "Copilot" / "GitHub Copilot" → copilot
-3. None of the above                                 → generic (bash stdout)
+3. system prompt mentions "Codex"                    → codex
+4. None of the above                                 → generic (bash stdout)
 ```
 
 Visual mechanism per CLI:
@@ -33,12 +34,27 @@ Visual mechanism per CLI:
 |---|---|
 | **claude-code** | `TaskCreate({subject, activeForm})` then `TaskUpdate({status, activeForm})`. Native sticky widget; ⏺ tiles, spinner header. |
 | **copilot** | Inline call: `bash phase-tracker.sh render`. The bordered ANSI card lands as the last tool result in the chat. |
+| **codex** | The native `update_plan` tool: one plan step per phase, `status: pending \| in_progress \| completed`. Rewrite the whole step list on each boundary  -  the tool takes the full plan, not a delta. |
 | **generic** (plain shell, Git Bash, WSL, tmux) | Same bash render  -  the bordered ANSI card prints to terminal stdout in place. |
 
 **Common to every CLI**: `phase-tracker.sh add/update/meta/tokens` calls run identically → the state file is always correct, and `:resume` / `:log` / `:status` work on every CLI.
 
 **Claude Code only**: in addition, `TaskCreate` / `TaskUpdate` native tool calls → the sticky widget pins the phase stack in the user's view.
 
+### Codex specifics
+
+Two constraints on `update_plan`, both of which fail quietly if ignored:
+
+- **Never call it in parallel with another tool.** Codex states this explicitly. A
+  phase boundary that batches `update_plan` alongside other calls loses the update.
+- **It is unavailable in Codex plan mode.** Fall back to
+  `bash phase-tracker.sh render` there rather than skipping the visual channel.
+
+The plan step is the phase label, not a restatement of the work: `Phase 4  -  Review`
+in the step list, with detail going to the agent log. A plan that mirrors the phase
+list is legible; one that mirrors the task list duplicates what the log already
+holds.
+
 ## Call pattern
 
 At every phase boundary the agent takes **two steps**: