@kbediako/codex-orchestrator 0.1.38 → 0.2.1

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

@@ -0,0 +1,113 @@
+# Downstream Setup
+
+This guide is the downstream-safe setup path shipped in the npm package.
+
+## Contract
+
+- 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
+
+1. Install CO:
+   ```bash
+   npm i -g @kbediako/codex-orchestrator
+   ```
+2. Authenticate Codex:
+   ```bash
+   codex login
+   # If browser auth is unavailable:
+   codex login --device-auth
+   ```
+## 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 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.
+3. Install `Codex Orchestrator`.
+4. 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`
+
+- 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 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 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
+
+- Uninstall the plugin from the Codex plugin browser when you want to remove it completely.
+- Set the plugin entry in `${CODEX_HOME:-~/.codex}/config.toml` to `enabled = false` when you want to keep it installed but turn it off.
+- Remove the marketplace registration if you no longer want Codex to read the shipped marketplace source:
+  ```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
+  ```
+
+## Once per repo
+
+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
+   ```
+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`
+4. Start with a task-scoped flow:
+   ```bash
+   codex-orchestrator flow --task <task-id>
+   ```
+
+## Version-Specific Notes
+
+- `codex exec` now accepts both a prompt argument and piped stdin; piped stdin is appended as a `<stdin>` block.
+- `codex login --device-auth` is available for environments where browser sign-in is not practical.
+- CO keeps review-wrapper prompt transport explicit and artifact-backed; do not assume every `codex review` code path matches `codex exec`.
+
+## First-run checks
+
+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>
+```
+
+## Provider onboarding
+
+For Linear and Telegram setup, continue with [provider-onboarding.md](provider-onboarding.md).

package/docs/public/provider-onboarding.md

@@ -0,0 +1,173 @@
+# Provider Onboarding
+
+This guide is the downstream-safe provider contract for Linear and Telegram.
+
+## Contract
+
+- Once per machine: install CO, authenticate Codex, and confirm `codex-orchestrator doctor --format json` works.
+- Once per repo: seed `.codex/providers/` with `codex-orchestrator init codex`.
+- Runtime env carries secrets and provider bindings.
+- Control policy carries `dispatch_pilot` and `transport_mutating_controls`.
+- Linear and Telegram should both have a machine-checkable readiness signal before live smoke.
+
+## Generated scaffolding
+
+`codex-orchestrator init codex` seeds:
+
+- `.codex/providers/README.md`
+- `.codex/providers/provider.env.example`
+- `.codex/providers/control.example.json`
+
+Use those files as the starting point for your repo-specific provider setup.
+
+## Environment variables
+
+Recommended Linear env:
+
+- `CO_LINEAR_API_TOKEN`
+- `CO_LINEAR_WORKSPACE_ID`
+- `CO_LINEAR_TEAM_ID`
+- `CO_LINEAR_PROJECT_ID`
+- `CO_LINEAR_WEBHOOK_SECRET`
+
+Supported Linear token fallbacks:
+
+- `CO_LINEAR_API_KEY`
+- `LINEAR_API_KEY`
+
+Telegram env:
+
+- `CO_TELEGRAM_POLLING_ENABLED`
+- `CO_TELEGRAM_BOT_TOKEN`
+- `CO_TELEGRAM_ALLOWED_CHAT_IDS`
+- `CO_TELEGRAM_ENABLE_MUTATIONS`
+- `CO_TELEGRAM_POLL_INTERVAL_MS`
+- `CO_TELEGRAM_PUSH_ENABLED`
+- `CO_TELEGRAM_PUSH_INTERVAL_MS`
+
+## Control policy
+
+Keep the provider policy explicit.
+
+`dispatch_pilot` should declare a Linear source and stay advisory-first:
+
+```json
+{
+  "feature_toggles": {
+    "dispatch_pilot": {
+      "enabled": true,
+      "source": {
+        "provider": "linear",
+        "live": true,
+        "workspace_id": "workspace-id",
+        "team_id": "team-id",
+        "project_id": "project-id"
+      }
+    }
+  }
+}
+```
+
+Telegram mutation policy should be explicit too:
+
+```json
+{
+  "feature_toggles": {
+    "transport_mutating_controls": {
+      "enabled": true,
+      "allowed_transports": ["telegram"]
+    }
+  }
+}
+```
+
+Nested `coordinator.dispatch_pilot` and `coordinator.transport_mutating_controls` remain valid compatibility paths.
+
+## Readiness
+
+`codex-orchestrator doctor --format json` is the machine-checkable readiness surface.
+
+Expect it to tell you:
+
+- whether delegation and DevTools wiring are present
+- whether Linear credentials and binding env are populated
+- whether `CO_LINEAR_WEBHOOK_SECRET` is present
+- whether Telegram polling, token, and allowlist env are populated
+- whether repo scaffolding under `.codex/providers/` exists
+
+## Smoke flow
+
+Use this minimal smoke flow:
+
+1. Check readiness:
+   ```bash
+   codex-orchestrator doctor --format json
+   ```
+2. Start the host in a dedicated terminal and keep it running:
+   ```bash
+   codex-orchestrator control-host --format json
+   ```
+   This prints a startup readiness payload and then keeps the host alive.
+3. In another terminal, inspect the current status snapshot:
+   ```bash
+   codex-orchestrator co-status --format json
+   ```
+4. Telegram read-only smoke:
+   - send `/help` from an allowlisted chat
+   - confirm the bot replies
+5. Linear advisory smoke:
+   - confirm the status snapshot reaches `dispatch_pilot.status=ready`
+   - confirm the selected tracked issue resolves from the configured workspace, team, or project binding
+
+## Help surfaces
+
+Use these commands when onboarding an operator:
+
+```bash
+codex-orchestrator doctor --help
+codex-orchestrator control-host --help
+codex-orchestrator co-status --help
+```
+
+`control-host --format json` is a persistent host startup handshake, not a one-shot status dump.
+
+## macOS launchd supervision
+
+On macOS, use the shipped supervision surface instead of a copied local shell wrapper:
+
+1. Make sure the `codex-orchestrator` currently on `PATH` is current enough to expose `control-host supervise`:
+   - source-checkout operator: from the checkout root, run `npm link` so the active `codex-orchestrator` bin points at this checkout's `bin/codex-orchestrator.js`
+   - packaged/global install operator: upgrade the active package (for example `npm install -g @kbediako/codex-orchestrator@latest`) before attempting the migration
+   - verify the active CLI with:
+   ```bash
+   codex-orchestrator control-host supervise status --format json
+   ```
+   If the current machine is still on the legacy shim rollout, the JSON status now reports that rollout mode and that migration is still required.
+2. Install the LaunchAgent-backed supervisor from the repo root:
+   ```bash
+   codex-orchestrator control-host supervise install --format json
+   ```
+   This rewrites the existing `com.kbediako.co.control-host` LaunchAgent in place, replacing the legacy shim rollout when present, and records the active package's `bin/codex-orchestrator.js` bootstrap as the managed entrypoint.
+3. Inspect the current launchd, rollout mode, config, and restart-reason state:
+   ```bash
+   codex-orchestrator control-host supervise status --format json
+   ```
+4. Restart the supervised host after config or env changes:
+   ```bash
+   codex-orchestrator control-host supervise restart --format json
+   ```
+   The restart payload records the previously tracked supervised child pid (`previous_child_pid`), the newly observed supervised child pid when available (`child_pid`), and `cleanup.result`. If launchd leaves the old supervised tree alive, the payload fails closed unless CO can force-clean that exact stale control-host process group first; any forced cleanup also records the orphaned process-group and descendant pids in `cleanup`.
+5. Remove the generated LaunchAgent, config, state, and logs:
+   ```bash
+   codex-orchestrator control-host supervise uninstall --format json
+   ```
+
+`control-host supervise status --format json` is the machine-checkable operator surface for whether the LaunchAgent is still on the legacy shim rollout or the managed packaged rollout, whether migration is still required, whether launchd is loaded, which supervised control-host child pid is currently recorded, and what last restart reason or health state the supervisor recorded.
+
+When a replacement host encounters an already-running owner during a restart race, inspect:
+
+```bash
+codex-orchestrator co-status --format json
+```
+
+The `polling.control_host_owner` payload carries the duplicate/stale owner diagnostic path plus owner pid/token metadata. Treat that owner diagnostic as control-host evidence, not as a provider-worker list: detached `provider-linear-worker` issue processes run independently in their own issue workspaces and are not the restart cleanup target.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.38",
+  "version": "0.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -12,10 +12,13 @@
   },
   "type": "module",
   "bin": {
-    "codex-orchestrator": "dist/bin/codex-orchestrator.js",
-    "codex-orch": "dist/bin/codex-orchestrator.js"
+    "codex-orchestrator": "bin/codex-orchestrator.js",
+    "codex-orch": "bin/codex-orchestrator.js"
   },
   "files": [
+    ".agents/plugins/marketplace.json",
+    "plugins/**",
+    "bin/codex-orchestrator.js",
     "dist/bin/**",
     "dist/orchestrator/**",
     "dist/packages/**",
@@ -27,7 +30,11 @@
     "templates/**",
     "skills/**",
     "codex.orchestrator.json",
-    "docs/assets/setup.gif",
+    "docs/README.md",
+    "docs/book/**",
+    "docs/guides/codex-version-policy.md",
+    "docs/public/downstream-setup.md",
+    "docs/public/provider-onboarding.md",
     "README.md",
     "LICENSE"
   ],
@@ -49,6 +56,9 @@
     "docs:archive-implementation": "node scripts/implementation-docs-archive.mjs",
     "docs:archive-tasks": "node scripts/tasks-archive.mjs",
     "docs:freshness": "node scripts/docs-freshness.mjs --check",
+    "docs:freshness:maintain": "node scripts/docs-freshness-maintain.mjs --check",
+    "done-closeout:check": "node scripts/done-closeout-provenance-check.mjs --check",
+    "repo:stewardship": "node scripts/repo-stewardship-audit.mjs --check",
     "docs:sync": "node --loader ts-node/esm scripts/docs-hygiene.ts --sync",
     "ci:cloud-canary": "node scripts/cloud-canary-ci.mjs",
     "canary:js-repl-usage": "node scripts/js-repl-usage-matrix.mjs",
@@ -59,11 +69,14 @@
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "prepack": "npm run clean:dist && npm run build && npm run pack:audit",
     "setup:design-tools": "node --loader ts-node/esm scripts/setup-design-tools.ts",
-    "test": "npm run test:orchestrator",
-    "test:orchestrator": "vitest run --config vitest.config.core.ts",
-    "test:adapters": "vitest run --passWithNoTests --config vitest.config.ts adapters",
-    "test:evaluation": "vitest run --passWithNoTests --config vitest.config.ts evaluation/tests",
-    "eval:test": "vitest run evaluation/tests",
+    "test": "npm run test:core --",
+    "test:core": "vitest run --config vitest.config.core.ts",
+    "test:all": "node scripts/run-test-all.mjs",
+    "test:orchestrator": "npm run test:core --",
+    "test:adapters": "vitest run --passWithNoTests --config vitest.config.adapters.ts",
+    "test:evaluation": "vitest run --passWithNoTests --config vitest.config.evaluation.ts",
+    "eval:test": "npm run test:evaluation --",
+    "eval:provider-adoption": "node scripts/provider-linear-adoption-eval.mjs",
     "test:watch": "vitest",
     "review": "node --loader ts-node/esm scripts/run-review.ts",
     "pr:watch-merge": "node scripts/pr-monitor-merge.mjs",
@@ -128,7 +141,7 @@
     "js-yaml": "^4.1.0",
     "react": "^18.3.1"
   },
-  "description": "![Setup demo](docs/assets/setup.gif)",
+  "description": "Codex-driven orchestration CLI with auditable manifests, downstream repo bootstrapping, and delegation MCP workflows.",
   "main": "dist/orchestrator/src/cli/orchestrator.js",
   "directories": {
     "doc": "docs",

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

@@ -0,0 +1,30 @@
+{
+  "name": "codex-orchestrator",
+  "version": "0.2.1",
+  "description": "Codex Orchestrator plugin metadata for the packaged CO runtime.",
+  "author": {
+    "name": "Kbediako",
+    "url": "https://github.com/Kbediako"
+  },
+  "homepage": "https://github.com/Kbediako/CO#readme",
+  "repository": "https://github.com/Kbediako/CO",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "mcp",
+    "orchestrator"
+  ],
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Codex Orchestrator",
+    "shortDescription": "Register CO's MCP orchestration server in Codex.",
+    "longDescription": "Connect Codex to Codex Orchestrator's MCP server for auditable task flows, manifests, and delegation workflows.",
+    "developerName": "Kbediako",
+    "category": "Productivity",
+    "capabilities": [
+      "MCP",
+      "Automation"
+    ],
+    "screenshots": []
+  }
+}

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

@@ -0,0 +1,13 @@
+{
+  "templateVersion": 1,
+  "mcpServers": {
+    "codex-orchestrator": {
+      "command": "node",
+      "args": [
+        "./launcher.mjs",
+        "mcp",
+        "serve"
+      ]
+    }
+  }
+}