@kbediako/codex-orchestrator 0.2.0 → 0.2.1

package/docs/book/public-posture.md

@@ -0,0 +1,34 @@
+# Public Posture
+
+## Stable Compatibility Vs Local Posture
+
+CO's current release-facing package/downstream-smoke compatibility target is Codex CLI `0.125.0`. Current `gpt-5.5` / `xhigh` local ChatGPT-auth/appserver posture and release-facing package Codex CLI pins are already adopted; cloud execution remains separately gated by the canonical version policy.
+
+Newer stable and prerelease Codex CLI builds remain evidence-gated. The canonical policy is [docs/guides/codex-version-policy.md](../guides/codex-version-policy.md).
+
+## Current Model / Runtime Posture
+
+- Current model posture: `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions.
+- Portable packaged/generated defaults keep `gpt-5.4` / `xhigh` as fallback values when `gpt-5.5`, API, or cloud portability is unavailable.
+- Local `gpt-5.5` use is the current CO posture after live access smoke; legacy marker metadata is ignored for posture decisions.
+- `explorer_fast` remains the explicit `gpt-5.3-codex-spark` exception for file/codebase search only.
+- Local appserver remains the expected default runtime path.
+- Provider workers keep the current `codex exec` / `codex exec resume` supervision seam until a separate governed lane promotes a replacement.
+
+## Evidence Gates
+
+Local model-posture updates must record:
+
+1. Local appserver path success on the candidate Codex CLI and model posture.
+2. Delegated/review surface verification under the actual auth provider.
+3. `node scripts/runtime-mode-canary.mjs` success.
+4. No P0/P1 regression versus the current stable baseline.
+
+Cloud execution or release-facing promotion additionally requires:
+
+1. Required cloud canary success with configured cloud env.
+2. Cloud fallback contract success.
+
+## Marketplace Split
+
+Marketplace/plugin support is additive. npm remains the supported baseline install path. Release-facing smoke lanes can stay pinned to a marketplace-capable Codex CLI while newer candidates are audited separately for cloud/runtime posture.

package/docs/book/setup.md

@@ -0,0 +1,91 @@
+# Setup
+
+## Baseline Install
+
+CO is shipped as the scoped npm package `@kbediako/codex-orchestrator`.
+
+```bash
+npm i -g @kbediako/codex-orchestrator
+codex-orchestrator --version
+```
+
+Node.js `>=20` is required. npm remains the supported baseline because it gives downstream operators the CLI directly without requiring Codex plugin support.
+
+## Machine Setup
+
+```bash
+codex login
+codex-orchestrator --version
+```
+
+Use `codex login --device-auth` when browser auth is not practical.
+
+Run repo-bound `codex-orchestrator setup --yes --repo /path/to/repo` after bootstrapping the downstream repository so delegation is registered with the repo root while bundled skills are installed and DevTools wiring is applied at the machine level.
+
+## Codex Marketplace / Plugin Install
+
+Use this path only on Codex releases that expose the marketplace/plugin flow. The npm install remains the baseline CLI path.
+
+Packaged npm source:
+
+```bash
+# Codex 0.121.0 accepts either command.
+codex marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+
+# Codex 0.122.0+ uses the plugin command.
+codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+```
+
+For a local checkout, pass the repository root instead of the npm install path. For a Git-backed source, pass `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL. Use `codex marketplace add ...` only on Codex `0.121.0`; use `codex plugin marketplace add ...` on `0.122.0+`.
+
+On current Codex CLI `0.125.0`, refresh a Git-backed marketplace checkout with:
+
+```bash
+codex plugin marketplace upgrade codex-orchestrator
+```
+
+Then open `/plugins` in Codex, install `Codex Orchestrator`, and restart Codex if the plugin does not appear immediately.
+
+The shipped marketplace files are:
+
+- `.agents/plugins/marketplace.json`
+- `plugins/codex-orchestrator/.codex-plugin/plugin.json`
+- `plugins/codex-orchestrator/.mcp.json`
+- `plugins/codex-orchestrator/launcher.mjs`
+
+The plugin launcher reads the `codex-orchestrator` marketplace entry in `${CODEX_HOME:-~/.codex}/config.toml` and resolves the recorded source checkout before starting the packaged CO CLI with `node`. Local-directory sources run from the recorded path. Git-backed sources run from Codex's installed marketplace checkout under `${CODEX_HOME:-~/.codex}/.tmp/marketplaces/codex-orchestrator`.
+
+Re-run the version-appropriate marketplace add command after moving a local-directory source, replacing it, or removing Codex's installed marketplace checkout.
+
+CO-355 only rebaselines marketplace/downstream-smoke compatibility to Codex CLI `0.125.0`. Model/runtime posture remains governed by `docs/guides/codex-version-policy.md` and the CO-351/CO-352 validation lanes: use `gpt-5.5` / `xhigh` for validated local ChatGPT-auth/appserver access, and keep `gpt-5.4` / `xhigh` as the portable fallback when access, API/cloud portability, or downstream/no-network evidence is missing.
+
+## Rollback / Removal
+
+- Uninstall `Codex Orchestrator` from the Codex plugin browser to remove the plugin.
+- Set the plugin entry in `${CODEX_HOME:-~/.codex}/config.toml` to `enabled = false` to disable without uninstalling.
+- On Codex CLI `0.125.0` or newer, remove the marketplace registration with `codex plugin marketplace remove codex-orchestrator`; on older support lanes or when that command is unavailable, remove the `[marketplaces.codex-orchestrator]` block from `${CODEX_HOME:-~/.codex}/config.toml` manually.
+- Remove the standalone CLI with:
+  ```bash
+  npm uninstall -g @kbediako/codex-orchestrator
+  ```
+
+## Repository Bootstrap
+
+```bash
+codex-orchestrator init codex --cwd /path/to/repo
+cd /path/to/repo
+codex-orchestrator setup --yes --repo /path/to/repo
+codex-orchestrator doctor --format json
+codex-orchestrator flow --task <task-id>
+```
+
+`init codex` seeds:
+
+- `AGENTS.md`
+- `.codex/config.toml`
+- `.codex/providers/README.md`
+- `.codex/providers/provider.env.example`
+- `.codex/providers/control.example.json`
+- `codex.orchestrator.json`
+
+Provider-specific setup continues in [docs/public/provider-onboarding.md](../public/provider-onboarding.md).

package/docs/book/skills.md

@@ -0,0 +1,11 @@
+# Bundled Skills
+
+Install bundled skills into `$CODEX_HOME/skills`:
+
+```bash
+codex-orchestrator skills install
+```
+
+The canonical shipped roster lives in [skills/README.md](../../skills/README.md). `docs:check` uses that file as the shipped-file parity surface so the GitHub front door can stay concise.
+
+Prefer globally installed skills when present, fall back to bundled `skills/<name>/SKILL.md`, and refresh skills after upgrading the npm package when you need new workflow instructions.

package/docs/guides/codex-version-policy.md

@@ -0,0 +1,104 @@
+# Codex Version Policy (CO)
+
+## Purpose
+Define the current stable compatibility/adoption target for CO and keep newer CLI/model moves evidence-gated.
+
+## Current Posture
+- Current CO-local ChatGPT-auth/appserver model posture is `gpt-5.5` / `xhigh` on Codex CLI `0.125.0` when live access smoke passes. CO-352 adopted that posture after local top-level, delegated, review-wrapper fallback, and runtime evidence passed.
+- Current release-facing package/downstream-smoke compatibility target is Codex CLI `0.125.0`. CO-355 rebaselined marketplace/downstream-smoke compatibility to `0.125.0`, and current release-facing workflows (`core-lane`, `release`, and `pack-smoke-backstop`) already pin `@openai/codex@0.125.0`.
+- Current cloud execution candidate remains Codex CLI `0.124.0`. The configured environment id failure remains a cloud-only blocker for `cloud-canary` promotion; it does not roll back the validated local ChatGPT-auth appserver/model posture or the separate `0.125.0` release-facing package/downstream-smoke pack-smoke contract.
+- Latest app-server control-seam candidate audited by CO-351 is Codex CLI `0.125.0`; CO-351 approves explicit task-scoped control-host/proof use of the 0.125 app-server seam after local transport/schema/proxy/config/permission-profile/untrusted-config/resume-fork metadata/WebSocket checks passed. This is the accepted re-scoped adoption direction for those proven control/proof surfaces, not a blanket HOLD; it does not promote `0.125.0` as the provider runtime, provider supervision, cloud execution target, or `cloud-canary` target, and provider supervision remains gated on sticky environments, real turn-backed pagination, runtime-mode, and cloud evidence.
+- Marketplace/downstream-smoke compatibility is separately rebaselined to Codex CLI `0.125.0` by CO-355 for the package-smoke contract only. Release-facing downstream-smoke workflows (`core-lane`, `release`, and `pack-smoke-backstop`) pin `@openai/codex@0.125.0` because `scripts/pack-smoke.mjs` now verifies current `codex plugin marketplace add`, `upgrade`, and `remove` support while preserving the older top-level `codex marketplace add` fallback for supported legacy pins. This is not a broad `0.125.0` active-posture, provider-runtime, provider-supervision, or `cloud-canary` promotion; those still require the runtime-mode and cloud evidence gates below.
+- `cloud-canary` pins `@openai/codex@0.124.0` as the explicit cloud execution candidate.
+- The current `0.125.0` local CLI/package posture keeps the previously recorded onboarding-sensitive help guarantees: `codex exec` accepts a prompt argument plus piped stdin (stdin appends as a `<stdin>` block), `codex login --device-auth` is available, and `codex review --help` exposes `[PROMPT]` alongside `--uncommitted` / `--base` / `--commit`.
+- Current model posture is `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions.
+- Portable packaged/generated defaults still keep `gpt-5.4` / `xhigh` as fallback values when `gpt-5.5`, API/cloud portability, or downstream/no-network access is unavailable.
+- CO-local `gpt-5.5` / `xhigh` configuration is the current ChatGPT-auth/appserver posture after live app-server/model smoke evidence; this is not a claim that every auth provider or cloud surface can select `gpt-5.5`.
+- `codex-orchestrator doctor` treats `gpt-5.5` as non-drift when `codex debug models` verifies current model access. Additive defaults keep fresh implicit configs on portable fallback values; `--auth-scope chatgpt` writes current ChatGPT-auth/appserver defaults after live access smoke, and compatible prior `gpt-5.5` role files remain preserved without marker metadata.
+- Keep `explorer_fast` as the only explicit `gpt-5.3-codex-spark` exception for file/codebase search only. CO-352 found `gpt-5.3-codex-spark` in the live `0.125.0` catalog but not in the bundled catalog, so no downstream/no-network role change is justified.
+- For delegated/review surfaces, use `gpt-5.5` after local smoke or fresh provider-lane evidence validates that access; fall back to `gpt-5.4` only on concrete access failure.
+- App-server `model/list` still reports `gpt-5.4` as `isDefault=true`; CO-341 has live app-server `model/list` plus `codex exec` evidence that explicit local `gpt-5.5` supports `xhigh`.
+- The bundled debug model catalog may lag the live app-server catalog; use live app-server `model/list` and live exec evidence as the source of truth for model availability decisions.
+- Residual plugin warnings seen during CO-341 came from local temporary plugin cache state, not CO-owned plugin manifests.
+- CO-341 reran `node scripts/runtime-mode-canary.mjs` after `npm run build`; all scenario checks passed in `out/linear-4a684a5e-64b0-47fb-835a-d792eba29071/manual/runtime-mode-canary/post-build/runtime-mode-canary.log`, and both required cloud and fallback cloud contracts passed on the branch.
+- Newer stable/prerelease Codex builds may run only in task-scoped lanes with captured evidence.
+- Local appserver remains the expected default runtime path after the `CO-22` canary.
+- Provider workers must keep `codex exec` / `codex exec resume` as the rollback supervision seam and must not adopt `0.125.0` app-server for provider runtime or local runtime operations until the required promotion gates pass. The proven `0.125.0` surfaces are limited to explicit control-host/proof use.
+- Codex CLI `0.125.0` app-server Unix socket/proxy support is approved for guarded CO control proof usage. Local help and upstream tagged README document the `unix://` path, while hosted OpenAI app-server docs checked in CO-351 did not expose that wording; provider-supervision migration still requires configured-environment sticky proof, real turn-backed pagination proof, runtime-mode evidence, and cloud gate evidence.
+- Treat `thread/shellCommand` as a sensitive unsandboxed surface; it is not part of the default provider-worker authority model.
+- Manual Codex re-review requests are quota-aware: send at most one `@codex` ping per PR head SHA, then wait for a new head before re-requesting.
+- Codex review quota exhaustion is an operational availability event, not an adoption/promotion signal; if it blocks review, use the merge-waiver path documented in `AGENTS.md` and `docs/AGENTS.md` (checks green, unresolved actionable threads = `0`, waiver evidence recorded).
+- Do not newly promote, re-promote, or carry forward a newer cloud/release-facing Codex CLI target after baseline drift unless the candidate posture has recorded results for `node scripts/runtime-mode-canary.mjs`, `CODEX_CLOUD_ENV_ID=<env-id> CODEX_CLOUD_CANARY_REQUIRED=1 npm run ci:cloud-canary`, and the intentional fallback contract `CODEX_CLOUD_ENV_ID="" CODEX_CLOUD_CANARY_REQUIRED=1 CLOUD_CANARY_EXPECT_FALLBACK=1 npm run ci:cloud-canary`.
+
+## Candidate Audit Notes
+- 2026-04-14: `CO-180` audited local `codex-cli 0.120.0` after baseline drift. The command-surface audit found no P0/P1 regression for `codex exec`, `codex exec resume`, `codex review`, or `codex login --device-auth`; raw logs are under `out/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/manual/codex-0120-audit/` and `.runs/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/manual/codex-0120-audit/`.
+- 2026-04-14: the runtime-mode canary passed after building `dist`; the first canary attempt failed only because the package canary packs with `--ignore-scripts` and `dist/bin/codex-orchestrator.js` was absent before `npm run build`. Passing evidence is under `out/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/manual/runtime-mode-canary-r2/`.
+- 2026-04-14: promotion is held because the required cloud canary contract could not execute in this provider workspace without `CODEX_CLOUD_ENV_ID`. The cloud fallback run produced a successful local fallback manifest with `cloud_fallback.mode_used=mcp`, but the CI wrapper still exited failed under `CODEX_CLOUD_CANARY_REQUIRED=1` because the missing environment remains a required configuration blocker. Required/fallback logs are under `out/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/manual/cloud-canary-required/` and `out/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/manual/cloud-canary-fallback/`; fallback manifest: `.runs/linear-acdc2c4c-b8b1-46e8-8e21-c9a9c014213d/cli/2026-04-14T10-13-58-564Z-94eab37d/manifest.json`.
+- 2026-04-14: `CO-183` expanded the candidate audit to official `rust-v0.119.0` and `rust-v0.120.0` release notes plus local help surfaces. The documented adoption target stayed at `0.118.0` because the required cloud canary had not passed or been explicitly waived. Evidence is under `out/linear-df69fabe-63c2-4b98-a226-9c37892b4f9d/manual/codex-0120-release-audit/`.
+- 2026-04-14: `CO-183` classified the release-note deltas as follows: MCP resources/custom-server/file uploads/elicitations are adopt-as-compatible; MCP `outputSchema` is held for CO delegation tools because current outputs are pass-through control results with variable shapes and broad schemas would be false precision; `tool_search` ordering is no-op for CO wrappers; app-server and exec-server remote control stay behind the guarded resident-session authority seam; Realtime v2 / Agent Turn API is no-op for CO; scoped review prompt transport, runtime-mode canary, cloud-required canary, and cloud-fallback canary remain evidence gates recorded in the task packet.
+- 2026-04-16: `CO-195` audited official `rust-v0.121.0`, OpenAI changelog, npm `@openai/codex latest=0.121.0`, and local `codex-cli 0.121.0` command surfaces. Local `codex exec`, `codex exec resume`, `codex review --help`, `codex login --device-auth`, `codex marketplace add --help`, app-server, MCP, and cloud help surfaces showed no P0/P1 regression. Runtime-mode canary passed 20/20. Promotion remains held because `CODEX_CLOUD_ENV_ID` is absent. The required cloud canary exited at preflight, and the fallback canary produced a successful local MCP fallback manifest while the required wrapper still exited failed under the missing-env configuration blocker. Evidence: `out/linear-4122489e-1a3b-43cf-a181-e98ada0a55e1/manual/codex-version-canary/compare/decision-go-no-go.md`, `out/linear-4122489e-1a3b-43cf-a181-e98ada0a55e1/manual/codex-0121-release-audit/`, `out/linear-4122489e-1a3b-43cf-a181-e98ada0a55e1/manual/runtime-mode-canary/`, `out/linear-4122489e-1a3b-43cf-a181-e98ada0a55e1/manual/cloud-canary-required/`, and `out/linear-4122489e-1a3b-43cf-a181-e98ada0a55e1/manual/cloud-canary-fallback/`.
+- 2026-04-16: `CO-199` classifies `rust-v0.121.0` sandbox/security deltas without promoting `0.121.0`:
+  - Local-only: secure devcontainer posture, macOS private DNS, macOS Unix sockets, Windows elevated denial, WSL1 bubblewrap behavior, exec-server filesystem sandboxing, websocket token hash auth, `danger-full-access`, and `thread/shellCommand`.
+  - Cloud-only: remote exec environment policy.
+  - Not applicable to CO preflight: pinned inputs.
+  - MCP sandbox-state metadata: shared metadata only; it does not expand tool authority or replace cloud canary evidence.
+  - `doctor --cloud-preflight` now reports detectable local-only security advisories separately from cloud preflight blockers.
+- 2026-04-21: `CO-269` audited official `rust-v0.122.0` release facts (`published_at=2026-04-20T18:38:40Z`), npm latest `@openai/codex@0.122.0` (`time.modified=2026-04-21T00:30:22.721Z`), and local `codex-cli 0.122.0` command/help surfaces (`timestamp=2026-04-21T01:50:53Z`). Local `codex exec`, `codex review --help`, `codex login --device-auth`, `codex app-server --help`, and `codex mcp --help` showed no P0/P1 regression. Evidence: `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/codex-0122-release-audit/`, `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/codex-0122-command-surface/`, and `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/codex-version-canary/compare/decision-go-no-go.md`.
+- 2026-04-21: `CO-269` runtime-mode evidence passes on the post-build sample (`ready_for_default_flip=true`, all four scenario checks passed 1/1). Required cloud evidence still blocks promotion: the required canary failed before task submission because the configured environment id was not found, and the fallback contract fell back to MCP for missing `CODEX_CLOUD_ENV_ID` but still terminated failed because the fallback rerun hit existing docs-freshness/spec-baseline debt before producing a clean success manifest. Evidence: `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/runtime-mode-canary/post-build-sample/runtime-canary-summary.json`, `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/cloud-canary-required/cloud-canary-required.log`, `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/cloud-canary-fallback/cloud-canary-fallback.log`, `.runs/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3-cloud-required/cli/2026-04-21T01-55-01-176Z-ec12a719/run-summary.json`, and `.runs/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3-cloud-fallback/cli/2026-04-21T01-56-29-071Z-a7ced7cf/run-summary.json`.
+- 2026-04-21: `CO-269` directly compared marketplace capability across the workflow-candidate versions. `npx --yes @openai/codex@0.121.0 marketplace --help` exposes `add`, while `npx --yes @openai/codex@0.122.0 marketplace --help` falls back to top-level Codex help and does not expose the old marketplace surface. At the time of that posture lane, `scripts/pack-smoke.mjs` still failed closed when `codex marketplace add` was unavailable, so downstream marketplace smoke workflows stayed pinned to `0.121.0` pending a follow-up command-surface rebaseline. Evidence: `out/linear-a2949fd4-2319-4cd0-acd1-68e6404766f3/manual/codex-0122-command-surface/marketplace-capability-compare.log`, `scripts/pack-smoke.mjs`, and `tests/pack-smoke.spec.ts`.
+- 2026-04-21: `CO-269` classified `rust-v0.122.0` deltas for CO as follows:
+  - Adopt now: pin `cloud-canary` to explicit `@openai/codex@0.122.0` and document the workflow split so canary evidence no longer floats latest.
+  - Superseded by `CO-268`: release-facing downstream-smoke workflows no longer need to stay on `@openai/codex@0.121.0` because `pack:smoke` now intentionally uses the `0.122.0` `codex plugin marketplace add` contract with evidence.
+  - Hold: active-target promotion from `0.118.0` to `0.122.0` until the required cloud canary and fallback contract both complete with clean evidence in a configured environment.
+  - No-op for current CO posture: standalone installer changes, TUI `/side` conversations, plan-mode fresh-context start, plugin browsing/marketplace UX expansion, tool-search/image-generation defaults, and general docs/chore refactors because this lane found no CO-specific regression or required workflow change beyond the audited candidate pin policy.
+- 2026-04-21: `CO-268` completed the marketplace follow-up by proving local `codex-cli 0.122.0` exposes `codex plugin marketplace add` and `codex plugin marketplace remove`, while `codex marketplace add --help` fails, then rebaselining public docs, launcher recovery guidance, pack-smoke detection/invocation, focused tests, and release-facing smoke workflow pins to `@openai/codex@0.122.0`. This does not promote the active CO compatibility target from `0.118.0`; it only updates the marketplace-dependent smoke contract and preserves the `CO-196` packaged marketplace architecture.
+- 2026-04-23: `CO-322` audited official `rust-v0.123.0` release facts (`publishedAt=2026-04-23T01:26:06Z`) and npm latest `@openai/codex@0.123.0` (`time["0.123.0"]=2026-04-23T01:27:03.972Z`, `time.modified=2026-04-23T02:46:36.597Z`). Local command-surface checks using temporary `@openai/codex@0.123.0` execution found no P0/P1 drift for `codex exec`, `codex review --help`, `codex login --device-auth`, `codex mcp`, or `codex app-server`. Evidence: `out/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f/manual/codex-0123-release-audit/`, `out/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f/manual/command-surface-0123/help-surface.log`, and `out/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f/manual/codex-version-canary/compare/decision-go-no-go.md`.
+- 2026-04-23: `CO-322` runtime-mode evidence passes for the `0.123.0` candidate (`20/20`, `ready_for_default_flip=true`), but required cloud evidence still blocks promotion: the required canary failed before task submission because the configured environment id was not found. After replaying onto current main, the fallback canary passed the expected contract with `cloud_fallback.mode_requested=cloud`, `cloud_fallback.mode_used=mcp`, and only the expected `missing_environment` fallback issue; this validates fallback behavior but does not replace required cloud execution. Evidence: `out/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f/manual/runtime-mode-canary-0123/runtime-canary-summary.json`, `.runs/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f-cloud-required-0123-current/cli/2026-04-23T04-56-19-486Z-012f562d/manifest.json`, and `.runs/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f-cloud-fallback-0123-current/cli/2026-04-23T04-56-47-062Z-7a811dfb/manifest.json`.
+- 2026-04-23: `CO-322` directly compared the marketplace-sensitive surface across `0.122.0` and `0.123.0`. `npx --yes @openai/codex@0.123.0 marketplace --help` still falls back to top-level Codex help, but `npx --yes @openai/codex@0.123.0 plugin marketplace add --help` and `plugin marketplace remove --help` both expose the current plugin marketplace contract. Result: no marketplace-smoke regression versus the current `0.122.0` plugin-marketplace baseline, but no release-facing pin moves to `0.123.0` without clean cloud gates. Evidence: `out/linear-ed46eae2-f0f5-402f-9dc7-dd8dbc36e61f/manual/command-surface-0123/plugin-marketplace-0123.log`.
+- 2026-04-23: `CO-322` classifies `rust-v0.123.0` deltas for CO as follows:
+  - Hold: do not promote the active target from `0.118.0` to `0.123.0` until required cloud and fallback cloud evidence both complete cleanly.
+  - Hold: keep `0.122.0` as the held release-planning candidate and keep `.github/workflows/cloud-canary.yml` pinned to explicit `@openai/codex@0.122.0` until a future `0.123.0` lane has clean cloud gates.
+  - Hold: release-facing downstream-smoke workflows remain on `@openai/codex@0.122.0` because current main already rebaselined smoke to `codex plugin marketplace add`, and 0.123.0 promotion is cloud-gate blocked rather than marketplace-surface blocked.
+  - No-op for current CO posture: Amazon Bedrock provider, `/mcp verbose`, broader `.mcp.json` plugin loading shapes, realtime handoff improvements, `remote_sandbox_config`, and refreshed model metadata because this lane found no CO-specific required workflow change without clean cloud-gate evidence.
+- 2026-04-23: `CO-335` reran the `0.123.0` cloud gates after cloud env/auth rotation and supersedes the CO-322 cloud HOLD. Required cloud canary passed with `cloud_execution.status=ready`, environment `Kbediako/CO`, task `task_e_69e9ef5628408327b88b1fcd0ab14b24`, `poll_count=24`, and manifest `reference/linear-919ecdfa-9be9-4d93-995b-7f8e4a784e6f/cloud-gates/required-manifest.json`. Fallback cloud contract passed with `cloud_fallback.mode_requested=cloud`, `cloud_fallback.mode_used=mcp`, and issue `missing_environment` at `reference/linear-919ecdfa-9be9-4d93-995b-7f8e4a784e6f/cloud-gates/fallback-manifest.json`.
+- 2026-04-23: `CO-335` promotion decision:
+  - Promote: active CO compatibility/adoption target moves from `0.118.0` to `0.123.0` because CO-322 found no P0/P1 local command, marketplace, or runtime-mode regression and CO-335 completed both cloud gates cleanly.
+  - Promote: release-facing downstream-smoke and `cloud-canary` workflows move to explicit `@openai/codex@0.123.0`.
+  - Release ship remains out of scope for CO-335; CO-316 may proceed with the cloud-gate blocker cleared, subject to its own release prerequisites.
+- 2026-04-24: `CO-337` rechecked the marketplace command relocation truth that older notes had partially compressed. Local `codex-cli 0.123.0` still exposes `plugin` at top level, `codex plugin marketplace add --help` succeeds, and top-level `codex marketplace add --help` fails. Versioned repro confirms `0.121.0` accepts both add paths, while `0.122.0` and `0.123.0` require `codex plugin marketplace add`. This does not change the promoted `0.123.0` posture or workflow pins on current `main`; it corrects the command-surface wording used by `pack:smoke`, launcher/operator messages, and downstream setup docs.
+- 2026-04-24: `CO-341` audited `rust-v0.124.0` / npm `@openai/codex@0.124.0` and aligns the repo CLI posture to `0.124.0` while keeping packaged/generated model defaults on `gpt-5.4` / `xhigh`. Local `codex-cli 0.124.0`, `codex exec`, `codex review --help`, and `codex login --help` keep the required prompt/device-auth surfaces. Live app-server `model/list` shows explicit local `gpt-5.5` supports `xhigh` while `gpt-5.4` remains the app-server catalog default; the bundled debug model catalog may lag. Residual plugin warnings are local temporary plugin cache warnings, not CO-owned plugin manifests. Runtime-mode canary, required cloud canary, fallback cloud contract, and pack-smoke evidence passed for the CO-341 branch. Evidence: `out/linear-4a684a5e-64b0-47fb-835a-d792eba29071/manual/local-probes/`, `out/linear-4a684a5e-64b0-47fb-835a-d792eba29071/manual/runtime-mode-canary/post-build/runtime-mode-canary.log`, `.runs/linear-4a684a5e-64b0-47fb-835a-d792eba29071/cli/2026-04-23T19-44-14-410Z-2e596753/manifest.json`, `.runs/linear-4a684a5e-64b0-47fb-835a-d792eba29071/cli/2026-04-23T19-49-46-024Z-0d81d04d/manifest.json`, and `tests/pack-smoke.spec.ts`.
+- 2026-04-24: `CO-351` audited Codex CLI `0.125.0` app-server control-seam surfaces. Release facts were stable: local `/opt/homebrew/bin/codex --version` returned `codex-cli 0.125.0`, npm latest was `0.125.0`, and GitHub release `rust-v0.125.0` was published `2026-04-24T18:00:38Z`.
+- 2026-04-24: `CO-351` generated app-server TypeScript and JSON Schema artifacts and ran a local Unix socket/proxy/WebSocket canary. Passing checks covered local `unix://` help, `app-server proxy --sock`, generated schema surfaces for thread start/resume/fork/turn pagination and permission profile fields, Unix socket creation, config/read under explicit untrusted project setup, `model/list` pagination, disabled permission-profile thread start, explicit untrusted project preservation, synthetic history injection, resume/fork metadata loading with `excludeTurns`, proxy auth status over `--sock`, and bursty WebSocket command output. Evidence: `out/linear-267f73e1-6347-496d-ad78-2f4177bfe450/manual/codex-0125-appserver-canary/runtime-canary-summary.json` and `docs/findings/linear-267f73e1-6347-496d-ad78-2f4177bfe450-codex-0125-appserver-control-seam.md`.
+- 2026-04-24: `CO-351` approves the 0.125 app-server seam for explicit control-host/proof usage, not as a blanket provider-supervision replacement or provider-runtime promotion. Remaining constraints: `sticky-environment-explicit-id` failed closed with unknown environment id `co351-local-env`, and `thread/turns/list` only proved the response shape on a synthetic-history thread with `0` persisted turns. Provider workers must keep `codex exec` / `codex exec resume` as rollback supervision until a configured lane proves sticky environments and real turn-backed pagination cleanly and the normal promotion gates pass.
+- 2026-04-24: `CO-352` audited `rust-v0.125.0` / npm `@openai/codex@0.125.0` model-catalog posture and adopts `gpt-5.5` / `xhigh` as the current CO-local ChatGPT-auth/appserver model posture. Local top-level and delegated `gpt-5.5` canaries passed, standalone review fallback passed, and runtime-mode canary passed `20/20`. Required cloud execution failed before task submission because the configured environment id was not found; the fallback contract passed with `missing_environment`. That exact failure blocks cloud execution and release-facing pin promotion, not local appserver posture. Live and bundled catalogs still disagree, so the prior portable model remains a fallback for unavailable surfaces. Evidence: `docs/findings/linear-f4469614-cfdf-49a6-a7ff-366f58229816-codex-0125-model-catalog-posture.md`, `out/linear-f4469614-cfdf-49a6-a7ff-366f58229816/manual/0.125-model-posture/`, `.runs/linear-f4469614-cfdf-49a6-a7ff-366f58229816-cloud-required/cli/2026-04-24T20-53-34-738Z-cf054a86/manifest.json`, and `.runs/linear-f4469614-cfdf-49a6-a7ff-366f58229816-cloud-fallback/cli/2026-04-24T20-54-06-599Z-bd863a12/manifest.json`.
+- 2026-04-24: The `explorer_fast` file/codebase search only role stays unchanged; the `gpt-5.3-codex-spark` file/codebase search only role passed a live no-tool smoke, but live `codex debug models` and bundled `codex debug models --bundled` still diverge.
+- 2026-04-24: `CO-355` rebaselined marketplace/downstream-smoke compatibility for Codex CLI `0.125.0` without promoting the broader active CO target, provider runtime, provider supervision, or cloud-canary target. Observed evidence: local `/opt/homebrew/bin/codex --version` reported `codex-cli 0.125.0`, npm `@openai/codex` latest/version returned `0.125.0`, `codex plugin marketplace add --help` accepted owner/repo, HTTP(S), SSH, and local marketplace roots, and `codex plugin marketplace upgrade --help` plus `remove --help` were available. Legacy `codex marketplace add --help` failed on `0.125.0`. After `scripts/pack-smoke.mjs` was updated to prefer `plugin marketplace add` with upgrade/remove help checks, preserve older top-level add fallback for supported legacy pins, and fail closed on incomplete current plugin help without a legacy path, an isolated npm-installed `@openai/codex@0.125.0` `npm run pack:smoke` canary passed. This supports moving only the release-facing downstream-smoke workflow pins from `@openai/codex@0.124.0` to `@openai/codex@0.125.0`; any broader `0.125.0` active-posture, provider-supervision, provider-runtime, or `cloud-canary` promotion remains pending until `node scripts/runtime-mode-canary.mjs`, `CODEX_CLOUD_ENV_ID=<env-id> CODEX_CLOUD_CANARY_REQUIRED=1 npm run ci:cloud-canary`, and the fallback cloud contract pass for that lane.
+
+## Required Evidence Gates
+For any change to the current CO-local `gpt-5.5` / `xhigh` operator posture or portable `gpt-5.4` fallback defaults:
+1. Local appserver path passes on the candidate Codex CLI + model posture.
+2. Delegated/review surfaces are verified on the actual auth provider in use; for ChatGPT auth, require explicit local smoke before using `gpt-5.5`, otherwise fall back to the portable `gpt-5.4` defaults.
+3. Runtime-mode canary passes (`node scripts/runtime-mode-canary.mjs`).
+4. No P0/P1 regression versus the current stable baseline.
+
+For any cloud execution or release-facing promotion of a newer Codex build in CO, also require:
+1. Cloud canary required contract passes (`CODEX_CLOUD_ENV_ID=<env-id> CODEX_CLOUD_CANARY_REQUIRED=1 npm run ci:cloud-canary`).
+2. Cloud fallback contract behavior remains correct (`CODEX_CLOUD_ENV_ID="" CODEX_CLOUD_CANARY_REQUIRED=1 CLOUD_CANARY_EXPECT_FALLBACK=1 npm run ci:cloud-canary`).
+
+## Cadence
+- Re-verify the current posture when auth/provider behavior changes materially.
+- Run canary on each newer stable/prerelease candidate considered for CO.
+- Run weekly backstop canary while CO is actively adopting a non-baseline Codex build.
+
+## Rollback
+- Failed gates hold or roll back only the surface they gate. Cloud gate failures block cloud execution and release-facing promotion; they do not roll back validated local appserver posture unless the evidence also shows a provider/model compatibility regression or P0/P1 signal.
+- Record rollback decision in:
+  - `docs/TASKS.md`
+  - `tasks/index.json`
+  - task checklists under `tasks/` and `.agent/task/`
+
+## Evidence Paths
+- Manifests: `.runs/<task-id>/cli/<run-id>/manifest.json`
+- Logs/summaries: `out/<task-id>/manual/`
+- Handover notes: `out/handovers/`
+- Decision summary: `out/<task-id>/manual/codex-version-canary/compare/decision-go-no-go.md`

package/docs/public/downstream-setup.md

@@ -4,10 +4,13 @@ This guide is the downstream-safe setup path shipped in the npm package.
 
 ## Contract
 
-- Once per machine: install Codex CLI, authenticate, install bundled skills, and register delegation or DevTools wiring.
-- Once per repo: seed the CO templates, review the generated config, and start using task-scoped runs.
-- CO currently targets Codex CLI `0.123.0`; newer candidates stay evidence-gated in the version policy.
-- CO-196 posture lineage remains unchanged: npm is the supported baseline because it is the simplest supported CLI install path, and marketplace packaging is an additive registration path for newer Codex releases that expose `codex plugin marketplace add` and `codex plugin marketplace remove`.
+- Once per machine: install Codex CLI and authenticate.
+- Once per repo: seed the CO templates, run setup with the repo root so delegation is repo-scoped while bundled skills are installed and DevTools wiring is applied at the machine level, review the generated config, and start using task-scoped runs.
+- CO-local ChatGPT-auth/appserver posture now uses `gpt-5.5` / `xhigh` on Codex CLI `0.125.0` when live access smoke passes; release-facing cloud/downstream pins remain evidence-gated in the version policy.
+- Portable generated downstream defaults keep `gpt-5.4` / `xhigh` as a fallback when `gpt-5.5`, API/cloud portability, or downstream/no-network access is not proven.
+- Local ChatGPT-auth `gpt-5.5` / `xhigh` is the preferred CO posture after `codex debug models` verifies current model access.
+- `codex-orchestrator doctor` treats `gpt-5.5` as non-drift when `codex debug models` verifies current model access, and additive defaults keep fresh configs on portable fallback values unless `--auth-scope chatgpt` is explicitly requested after live access smoke; compatible prior `gpt-5.5` role files are preserved without requiring extra marker metadata.
+- CO-196 posture lineage remains unchanged: npm is the supported baseline because it is the simplest supported CLI install path, and marketplace packaging is an additive registration path for newer Codex releases. `0.121.0` accepts both `codex marketplace add` and `codex plugin marketplace add`; `0.122.0+` require `codex plugin marketplace add`, and current `0.125.0` also exposes `codex plugin marketplace upgrade` / `remove`.
 
 ## Once per machine
 
@@ -21,21 +24,15 @@ This guide is the downstream-safe setup path shipped in the npm package.
    # If browser auth is unavailable:
    codex login --device-auth
    ```
-3. Install bundled skills and register delegation or DevTools wiring:
-   ```bash
-   codex-orchestrator setup --yes
-   ```
-4. Check readiness:
-   ```bash
-   codex-orchestrator doctor --format json
-   ```
-
 ## Codex plugin marketplace install
 
 Use this when you want Codex to discover and enable CO from the plugin browser, while keeping npm available as the baseline CLI install path.
 
-1. Add the packaged marketplace root:
+1. Add the packaged marketplace root with the command that matches your Codex version:
    ```bash
+   # Codex 0.121.0: either command works
+   codex marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+   # Codex 0.122.0+:
    codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
    ```
 2. Open `/plugins` inside Codex.
@@ -50,9 +47,11 @@ The shipped marketplace files are:
 - `plugins/codex-orchestrator/launcher.mjs`
 
 - Launcher behaviour: The plugin entry points at `plugins/codex-orchestrator`, and its launcher reads the `codex-orchestrator` marketplace entry in `${CODEX_HOME:-~/.codex}/config.toml` to locate the recorded source checkout before it execs the packaged CO CLI there via `node`. Local-directory sources run from the recorded source path. Git-backed sources run from Codex's installed checkout under `${CODEX_HOME:-~/.codex}/.tmp/marketplaces/codex-orchestrator`, so the MCP registration path stays independent of a second `codex-orchestrator` path entry after install.
-- Local-directory add: Run `codex plugin marketplace add <repository-root>` against the repository root that contains those files instead of the npm install directory.
+- Local-directory add: Run the version-appropriate add command against the repository root that contains those files instead of the npm install directory. `0.121.0` accepts either `codex marketplace add <repository-root>` or `codex plugin marketplace add <repository-root>`; `0.122.0+` require `codex plugin marketplace add <repository-root>`.
 - Git-backed add: Pass a Git identifier or URL such as `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL rather than a local path.
-- When to re-run add: Re-run `codex plugin marketplace add ...` if you move or replace a local-directory source, or if you remove Codex's installed marketplace checkout and want to restore the Git-backed install. `codex plugin marketplace add --help` currently documents local directories plus Git-backed sources such as `owner/repo[@ref]`, HTTPS Git URLs, and SSH Git URLs.
+- When to re-run add: Re-run the same version-appropriate add command if you move or replace a local-directory source, or if you remove Codex's installed marketplace checkout and want to restore the Git-backed install. `0.121.0` documents the add flow under both marketplace paths; `0.122.0+` document local directories plus Git-backed sources under `codex plugin marketplace add --help`.
+- Marketplace updates/removal: On current Codex CLI `0.125.0`, run `codex plugin marketplace upgrade codex-orchestrator` to refresh a Git-backed marketplace checkout when you want Codex to pull a newer source ref. Run `codex plugin marketplace remove codex-orchestrator` to remove the marketplace registration.
+- Debug caveats: The bundled debug catalog can lag runtime posture briefly, and residual plugin warnings are local temporary plugin cache warnings rather than CO posture failures.
 
 ## Rollback and removal
 
@@ -62,6 +61,7 @@ The shipped marketplace files are:
   ```bash
   codex plugin marketplace remove codex-orchestrator
   ```
+  Use this command on Codex CLI `0.125.0` or newer. On older support lanes, or if the remove command is unavailable, remove the `[marketplaces.codex-orchestrator]` block from `${CODEX_HOME:-~/.codex}/config.toml` manually.
 - Remove the npm install when you no longer want the standalone CLI or when you no longer need it as the marketplace source:
   ```bash
   npm uninstall -g @kbediako/codex-orchestrator
@@ -72,15 +72,21 @@ The shipped marketplace files are:
 1. Seed the repo:
    ```bash
    codex-orchestrator init codex --cwd /path/to/repo
+   cd /path/to/repo
+   codex-orchestrator setup --yes --repo "$(pwd)"
+   ```
+2. Check readiness:
+   ```bash
+   codex-orchestrator doctor --format json
    ```
-2. Review the generated files:
+3. Review the generated files:
    - `AGENTS.md`
    - `.codex/config.toml`
    - `.codex/providers/README.md`
    - `.codex/providers/provider.env.example`
    - `.codex/providers/control.example.json`
    - `codex.orchestrator.json`
-3. Start with a task-scoped flow:
+4. Start with a task-scoped flow:
    ```bash
    codex-orchestrator flow --task <task-id>
    ```
@@ -96,6 +102,7 @@ The shipped marketplace files are:
 Use these before asking a reviewer to trust a new repo:
 
 ```bash
+cd /path/to/repo
 codex-orchestrator doctor --format json
 codex-orchestrator flow --task <task-id>
 NOTES="Goal: ... | Summary: ... | Risks: ..." codex-orchestrator review --task <task-id>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,6 +30,9 @@
     "templates/**",
     "skills/**",
     "codex.orchestrator.json",
+    "docs/README.md",
+    "docs/book/**",
+    "docs/guides/codex-version-policy.md",
     "docs/public/downstream-setup.md",
     "docs/public/provider-onboarding.md",
     "README.md",

package/plugins/codex-orchestrator/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-orchestrator",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Codex Orchestrator plugin metadata for the packaged CO runtime.",
   "author": {
     "name": "Kbediako",

package/plugins/codex-orchestrator/launcher.mjs

@@ -9,6 +9,8 @@ import process from 'node:process';
 const FORWARDABLE_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
 const MARKETPLACE_NAME = 'codex-orchestrator';
 const MARKETPLACE_SECTION = `[marketplaces.${MARKETPLACE_NAME}]`;
+const MARKETPLACE_ADD_HELP =
+  'Re-run codex marketplace add for Codex 0.121.0, or codex plugin marketplace add for Codex 0.122.0+.';
 const MARKETPLACE_SECTION_PATTERN = new RegExp(
   `^marketplaces\\s*\\.\\s*(?:"${escapeRegExp(MARKETPLACE_NAME)}"|'${escapeRegExp(MARKETPLACE_NAME)}'|${escapeRegExp(MARKETPLACE_NAME)})$`,
   'u'
@@ -19,7 +21,7 @@ function main() {
   const entrypoint = join(sourceRoot, 'bin', 'codex-orchestrator.js');
   if (!existsSync(entrypoint)) {
     throw new Error(
-      `Codex Orchestrator marketplace source is missing ${entrypoint}. Keep the marketplace source installed or re-run codex plugin marketplace add.`
+      `Codex Orchestrator marketplace source is missing ${entrypoint}. Keep the marketplace source installed. ${MARKETPLACE_ADD_HELP}`
     );
   }
 
@@ -59,7 +61,7 @@ function main() {
 function resolveMarketplaceSourceRoot() {
   const { codexHome, configPath } = resolveCodexPaths();
   if (!existsSync(configPath)) {
-    throw new Error(`Unable to locate Codex config at ${configPath}. Re-run codex plugin marketplace add for Codex Orchestrator.`);
+    throw new Error(`Unable to locate Codex config at ${configPath}. ${MARKETPLACE_ADD_HELP}`);
   }
 
   const raw = readFileSync(configPath, 'utf8');
@@ -68,7 +70,7 @@ function resolveMarketplaceSourceRoot() {
   const sourceType = marketplaceConfig?.sourceType;
   if (!source) {
     throw new Error(
-      `Codex config at ${configPath} is missing ${MARKETPLACE_SECTION}. Re-run codex plugin marketplace add for Codex Orchestrator.`
+      `Codex config at ${configPath} is missing ${MARKETPLACE_SECTION}. ${MARKETPLACE_ADD_HELP}`
     );
   }
   if (sourceType === 'local') {
@@ -98,7 +100,7 @@ function resolveInstalledMarketplaceSourceRoot(codexHome, source) {
     return installedMarketplaceRoot;
   }
   throw new Error(
-    `Codex marketplace source resolved to ${JSON.stringify(source)}, but ${installedMarketplaceRoot} is unavailable. Re-run codex plugin marketplace add for Codex Orchestrator.`
+    `Codex marketplace source resolved to ${JSON.stringify(source)}, but ${installedMarketplaceRoot} is unavailable. ${MARKETPLACE_ADD_HELP}`
   );
 }
 

package/schemas/manifest.json

@@ -70,6 +70,12 @@
     "provider_launch_source": { "type": ["string", "null"] },
     "provider_control_host_task_id": { "type": ["string", "null"] },
     "provider_control_host_run_id": { "type": ["string", "null"] },
+    "provider_linear_worker_tokens": {
+      "anyOf": [
+        { "type": "null" },
+        { "$ref": "#/definitions/providerLinearWorkerTokenUsage" }
+      ]
+    },
     "summary": { "type": ["string", "null"] },
     "metrics_recorded": { "type": "boolean" },
     "resume_token": { "type": "string", "minLength": 1 },
@@ -1569,6 +1575,17 @@
         "notes": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "providerLinearWorkerTokenUsage": {
+      "type": "object",
+      "required": ["input_tokens", "output_tokens", "total_tokens"],
+      "additionalProperties": false,
+      "properties": {
+        "input_tokens": { "type": ["integer", "null"], "minimum": 0 },
+        "output_tokens": { "type": ["integer", "null"], "minimum": 0 },
+        "total_tokens": { "type": ["integer", "null"], "minimum": 0 },
+        "reasoning_output_tokens": { "type": ["integer", "null"], "minimum": 0 }
+      }
+    },
     "designMetrics": {
       "type": "object",
       "additionalProperties": false,

package/skills/README.md

@@ -0,0 +1,26 @@
+# Bundled Skills
+
+Install bundled skills into `$CODEX_HOME/skills`:
+
+```bash
+codex-orchestrator skills install
+```
+
+Bundled skills:
+- `agent-first-adoption-steering`
+- `chrome-devtools`
+- `codex-orchestrator`
+- `collab-deliberation`
+- `collab-evals`
+- `collab-subagents-first`
+- `delegate-early`
+- `delegation-usage`
+- `docs-first`
+- `elegance-review`
+- `land`
+- `linear`
+- `long-poll-wait`
+- `release`
+- `standalone-review`
+
+Prefer globally installed skills when present, fall back to bundled `skills/<name>/SKILL.md`, and refresh skills after upgrading the npm package when you need new workflow instructions.

package/skills/collab-subagents-first/SKILL.md

@@ -175,7 +175,7 @@ Do not treat wrapper handoff-only output as a completed review.
 - Rebuild managed CLI only (optional): `codex-orchestrator codex setup --source <codex-repo> --yes --force`.
 - Managed routing is explicit opt-in: `export CODEX_CLI_USE_MANAGED=1` (stock/global `codex` remains default otherwise).
 - If local codex is materially behind upstream, sync before diagnosing collab behavior differences.
-- In Codex CLI `0.123.0`, built-in `explorer` inherits top-level model defaults unless you attach a role `config_file`; reserve spark for optional `[agents.explorer_fast]` file/codebase search only.
+- In Codex CLI `0.124.0`, built-in `explorer` inherits top-level model defaults unless you attach a role `config_file`; reserve spark for optional `[agents.explorer_fast]` file/codebase search only, and use `gpt-5.5` only in validated ChatGPT-auth lanes.
 - For cloud-heavy streams, treat fallback as a safety net only; set `CODEX_ORCHESTRATOR_CLOUD_FALLBACK=deny` in fail-fast lanes.
 - If compatibility remains unstable, continue with non-collab execution path and document the degraded mode.
 

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -133,11 +133,13 @@ If you need delegation to respect a repo’s `.codex/orchestrator.toml` (e.g., s
 
 ## Version guard (JSONL handshake)
 
-Delegation MCP expects JSONL. Keep `codex-orchestrator` aligned with the current CO compatibility or adoption target (`codex-cli 0.123.0`) unless a task-scoped canary is explicitly evaluating something newer.
+Delegation MCP expects JSONL. Keep `codex-orchestrator` aligned with the current CO compatibility or adoption target (`codex-cli 0.125.0` for local ChatGPT-auth/appserver posture) unless a task-scoped canary is explicitly evaluating something newer.
 
-Current `0.123.0` posture also confirms that:
+Current `0.125.0` CO-local posture also confirms that:
 - `codex exec` accepts a prompt argument plus piped stdin, with stdin appended as a `<stdin>` block.
 - `codex login --device-auth` is available for non-browser sign-in fallback.
+- App-server model/list evidence under ChatGPT auth can vary by account; keep `gpt-5.4` only as the fallback packaged default because it may still appear as the app-server `isDefault`.
+- The bundled debug catalog can lag runtime posture briefly, and residual plugin warnings are local temporary plugin cache warnings rather than CO posture failures.
 
 - Check: `codex-orchestrator --version`
 - Update global: `npm i -g @kbediako/codex-orchestrator@latest`
@@ -155,18 +157,21 @@ Current `0.123.0` posture also confirms that:
 - `spawn_agent` omission defaults to `default`; require explicit `agent_type` for every spawn.
 - For symbolic collab runs, include a first-line role tag in spawned prompts: `[agent_type:<role>]`.
 - Multi-turn subagent loops are supported (`spawn_agent` -> `send_input` -> `wait`/`resume_agent` -> `close_agent`).
-- In Codex CLI `0.123.0`, built-in `explorer` continues to inherit top-level defaults unless overridden in `~/.codex/config.toml`.
-- Recommended baseline:
+- In Codex CLI `0.125.0`, built-in `explorer` continues to inherit top-level defaults unless overridden in `~/.codex/config.toml`.
+- Current model posture is `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions.
+- Portable generated config keeps `gpt-5.4` / `xhigh` as fallback values.
+- Recommended packaged baseline:
   - `model = "gpt-5.4"`
   - `review_model = "gpt-5.4"`
   - `model_reasoning_effort = "xhigh"`
-  - `[agents] max_threads = 12` is the seeded baseline; keep explicit `max_depth = 4` only when your local Codex parser accepts it, and treat `max_spawn_depth` as a legacy local override rather than current baseline guidance
+  - For normal `features.multi_agent=true` and older Codex behavior, `[agents] max_threads = 12` is the seeded baseline. For Codex CLI `0.125+` with `features.multi_agent_v2=true`, do not write or recommend `agents.max_threads`; upstream rejects the key, so doctor/default setup must omit it. Keep explicit `max_depth = 4` only when your local Codex parser accepts it, and treat `max_spawn_depth` as a legacy local override rather than current baseline guidance
   - Leave `[agents.explorer]` undefined unless you intentionally want to override built-in explorer behavior.
   - Add optional `[agents.explorer_fast]` for `gpt-5.3-codex-spark` (file/codebase search only).
   - Add optional `[agents.awaiter]` override for `gpt-5.4` + `high` while preserving awaiter instructions.
   - Add `[agents.worker_complex]` for high-risk edits (`gpt-5.4`, `xhigh`).
-  - Keep delegated subagent and review surfaces on `gpt-5.4` under ChatGPT auth unless a fresh provider lane explicitly validates `gpt-5.4-codex`.
-  - Fallback posture is contingency-only: `8/2` (constrained/high-risk), legacy `6/1/1` break-glass when an older parser/runtime still consumes spawn-depth caps.
+  - Use `gpt-5.5` for delegated/review surfaces after access smoke validates the local posture; otherwise use the portable `gpt-5.4` fallback defaults.
+  - Caveat: app-server `isDefault` may still report `gpt-5.4` even when newer local models are available.
+  - Fallback posture is contingency-only and applies only to v1/older configs that still accept thread/depth caps: `8/2` (constrained/high-risk), legacy `6/1/1` break-glass when an older parser/runtime still consumes spawn-depth caps.
   - If native `codex` startup fails with `invalid type: integer ... expected struct AgentRoleToml` under `[agents]`, remove only the live `max_depth` and `max_spawn_depth` keys from `~/.codex/config.toml` and leave the role subtables unchanged.
 
 ## Common failures

package/skills/delegation-usage/SKILL.md

@@ -105,8 +105,10 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 
 ### 0a) Version guard (JSONL handshake)
 
-- Delegation MCP uses JSONL; keep `codex-orchestrator` aligned with the current CO compatibility or adoption target (`codex-cli 0.123.0`).
-- Current `0.123.0` posture confirms two onboarding-relevant behaviors: `codex exec` accepts a prompt argument plus piped stdin, and `codex login --device-auth` is available for non-browser sign-in fallback.
+- Delegation MCP uses JSONL; keep `codex-orchestrator` aligned with the current CO compatibility or adoption target (`codex-cli 0.125.0` for local ChatGPT-auth/appserver posture).
+- Current `0.125.0` CO-local posture keeps the onboarding-relevant behaviors from `0.124.0`: `codex exec` accepts a prompt argument plus piped stdin, and `codex login --device-auth` is available for non-browser sign-in fallback.
+- App-server model/list evidence under ChatGPT auth can vary by account; keep `gpt-5.4` only as the fallback packaged default because it may still appear as the app-server `isDefault`.
+- The bundled debug catalog can lag runtime posture briefly, and residual plugin warnings are local temporary plugin cache warnings rather than CO posture failures.
   - Check installed version: `codex-orchestrator --version`
   - Preferred update path: `npm i -g @kbediako/codex-orchestrator@latest`
   - Deterministic pin path (for reproducible environments): `npx -y @kbediako/codex-orchestrator@<version> delegate-server`
@@ -123,19 +125,22 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 - `spawn_agent` omission defaults to `default`; require explicit `agent_type` for every spawn.
 - For symbolic collab runs, include a first-line role tag in spawned prompts: `[agent_type:<role>]`.
 - Multi-turn subagent loops are supported (`spawn_agent` -> `send_input` -> `wait`/`resume_agent` -> `close_agent`).
-- In Codex CLI `0.123.0`, built-in `explorer` continues to inherit top-level model defaults unless a role `config_file` overrides it.
-- Recommended baseline in `~/.codex/config.toml`:
+- In Codex CLI `0.125.0`, built-in `explorer` continues to inherit top-level model defaults unless a role `config_file` overrides it.
+- Current model posture is `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions.
+- Portable generated config keeps `gpt-5.4` / `xhigh` as fallback values.
+- Recommended packaged baseline in `~/.codex/config.toml`:
   - `model = "gpt-5.4"`
   - `review_model = "gpt-5.4"`
   - `model_reasoning_effort = "xhigh"`
-  - `[agents] max_threads = 12` is the seeded baseline; keep explicit `max_depth = 4` only when your local Codex parser accepts it, and treat `max_spawn_depth` as a legacy local override rather than current baseline guidance
+  - For normal `features.multi_agent=true` and older Codex behavior, `[agents] max_threads = 12` is the seeded baseline. For Codex CLI `0.125+` with `features.multi_agent_v2=true`, do not write or recommend `agents.max_threads`; upstream rejects the key, so doctor/default setup must omit it. Keep explicit `max_depth = 4` only when your local Codex parser accepts it, and treat `max_spawn_depth` as a legacy local override rather than current baseline guidance
   - Leave `[agents.explorer]` undefined unless you intentionally want to override built-in explorer behavior
   - Optional `[agents.explorer_fast]` -> `~/.codex/agents/explorer-fast.toml` (`gpt-5.3-codex-spark`, file/codebase search only)
   - Optional `[agents.awaiter]` override -> `~/.codex/agents/awaiter-high.toml` when you want awaiter at `gpt-5.4` + `high` while preserving awaiter instructions
   - `[agents.worker_complex]` -> `~/.codex/agents/worker-complex.toml` (`gpt-5.4`, `xhigh`)
-- Keep delegated subagent and review surfaces on `gpt-5.4` under ChatGPT auth unless a fresh provider lane explicitly validates `gpt-5.4-codex`.
-- Fallback posture is contingency-only: `8/2` for constrained/high-risk lanes, legacy `6/1/1` as break-glass when an older parser/runtime still consumes spawn-depth caps.
-- Downstream users should converge on this baseline via `codex-orchestrator init codex`.
+- Use `gpt-5.5` for delegated/review surfaces when access smoke validates current ChatGPT-auth/appserver availability; otherwise use the portable `gpt-5.4` fallback defaults.
+- Caveat: app-server `isDefault` may still report `gpt-5.4` even when newer local models are available.
+- Fallback posture is contingency-only and applies only to v1/older configs that still accept thread/depth caps: `8/2` for constrained/high-risk lanes, legacy `6/1/1` as break-glass when an older parser/runtime still consumes spawn-depth caps.
+- Downstream users should converge on this baseline via `codex-orchestrator init codex`; when `features.multi_agent_v2=true`, init/default setup must omit `agents.max_threads`.
 - If native `codex` startup fails with `invalid type: integer ... expected struct AgentRoleToml` under `[agents]`, remove only the live `max_depth` and `max_spawn_depth` keys from `~/.codex/config.toml` and leave the role subtables unchanged.
 
 ### 0b) Background terminal bootstrap (required when MCP is disabled)