@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/schemas/manifest.json

@@ -62,6 +62,14 @@
     "artifact_root": { "type": "string", "minLength": 1 },
     "compat_path": { "type": "string", "minLength": 1 },
     "log_path": { "type": "string", "minLength": 1 },
+    "issue_provider": { "type": ["string", "null"] },
+    "issue_id": { "type": ["string", "null"] },
+    "issue_identifier": { "type": ["string", "null"] },
+    "issue_updated_at": { "type": ["string", "null"] },
+    "workspace_path": { "type": ["string", "null"], "minLength": 1 },
+    "provider_launch_source": { "type": ["string", "null"] },
+    "provider_control_host_task_id": { "type": ["string", "null"] },
+    "provider_control_host_run_id": { "type": ["string", "null"] },
     "summary": { "type": ["string", "null"] },
     "metrics_recorded": { "type": "boolean" },
     "resume_token": { "type": "string", "minLength": 1 },
@@ -239,6 +247,10 @@
       }
     },
     "guardrails_required": { "type": ["boolean", "null"] },
+    "guardrails_required_source": {
+      "type": ["string", "null"],
+      "enum": ["explicit", "stage_detection", null]
+    },
     "runtime_mode_requested": { "type": "string", "enum": ["cli", "appserver"] },
     "runtime_mode": { "type": "string", "enum": ["cli", "appserver"] },
     "runtime_provider": { "type": "string", "enum": ["CliRuntimeProvider", "AppServerRuntimeProvider"] },
@@ -466,6 +478,88 @@
             "type": "array",
             "items": { "type": "string", "minLength": 1 }
           },
+          "retrieval_policy": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": ["kind", "min_score", "score_weights", "anti_dominance_normalization"],
+            "properties": {
+              "kind": { "type": "string", "const": "competitive_scoring_v1" },
+              "min_score": {
+                "type": ["number", "null"],
+                "minimum": 0
+              },
+              "score_weights": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["gt_score", "relative_rank"],
+                "properties": {
+                  "gt_score": { "type": "number", "minimum": 0 },
+                  "relative_rank": { "type": "number", "minimum": 0 }
+                }
+              },
+              "anti_dominance_normalization": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["enabled", "strength", "source_grouping"],
+                "properties": {
+                  "enabled": { "type": "boolean" },
+                  "strength": { "type": "number", "minimum": 0 },
+                  "source_grouping": { "type": "string", "const": "provenance_fallback_v1" }
+                }
+              }
+            }
+          },
+          "retrieval_selection": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": [
+              "candidate_count",
+              "selected_count",
+              "diagnostics_path",
+              "selected_ids",
+              "suppressed_source_keys",
+              "selected"
+            ],
+            "properties": {
+              "candidate_count": { "type": "integer", "minimum": 0 },
+              "selected_count": { "type": "integer", "minimum": 0 },
+              "diagnostics_path": { "type": ["string", "null"] },
+              "selected_ids": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "suppressed_source_keys": {
+                "type": "array",
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "selected": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "id",
+                    "source_key",
+                    "source_kind",
+                    "raw_score",
+                    "competitive_score",
+                    "dominance_penalty"
+                  ],
+                  "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "source_key": { "type": "string", "minLength": 1 },
+                    "source_kind": {
+                      "type": "string",
+                      "enum": ["group_id", "run_id", "manifest_path", "stamp_signature"]
+                    },
+                    "raw_score": { "type": "number" },
+                    "competitive_score": { "type": "number" },
+                    "dominance_penalty": { "type": "number", "minimum": 0 }
+                  }
+                }
+              }
+            }
+          },
           "experiences": {
             "type": ["array", "null"],
             "items": { "type": "string", "minLength": 1 }
@@ -473,6 +567,288 @@
         }
       }
     },
+    "memory": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "block_memory": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": ["schema_version", "kind", "index_path", "generated_at", "block_count"],
+          "properties": {
+            "schema_version": { "type": "integer", "minimum": 1 },
+            "kind": { "type": "string", "const": "index" },
+            "index_path": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+            },
+            "generated_at": { "type": "string", "minLength": 1 },
+            "block_count": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "source_0": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": [
+            "schema_version",
+            "kind",
+            "object_id",
+            "pointer",
+            "dir_path",
+            "index_path",
+            "source_path",
+            "byte_length",
+            "chunk_count",
+            "created_at",
+            "origin",
+            "inherited_from"
+          ],
+          "properties": {
+            "schema_version": { "type": "integer", "minimum": 1 },
+            "kind": { "type": "string", "const": "context_object" },
+            "object_id": { "type": "string", "minLength": 1 },
+            "pointer": { "type": "string", "minLength": 1 },
+            "dir_path": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+            },
+            "index_path": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+            },
+            "source_path": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+            },
+            "byte_length": { "type": "integer", "minimum": 0 },
+            "chunk_count": { "type": "integer", "minimum": 1 },
+            "created_at": { "type": "string", "minLength": 1 },
+            "origin": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["run_id", "task_id", "manifest_path"],
+              "properties": {
+                "run_id": { "type": "string", "minLength": 1 },
+                "task_id": { "type": "string", "minLength": 1 },
+                "manifest_path": { "type": "string", "minLength": 1 }
+              }
+            },
+            "inherited_from": {
+              "type": ["object", "null"],
+              "additionalProperties": false,
+              "required": ["run_id", "task_id", "manifest_path"],
+              "properties": {
+                "run_id": { "type": "string", "minLength": 1 },
+                "task_id": { "type": "string", "minLength": 1 },
+                "manifest_path": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        },
+        "observability": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": [
+            "schema_version",
+            "recorded_at",
+            "selected_memory",
+            "rejected_candidates",
+            "rediscovered_memory",
+            "manual_repairs",
+            "counters"
+          ],
+          "properties": {
+            "schema_version": { "type": "integer", "minimum": 1 },
+            "recorded_at": { "type": "string", "minLength": 1 },
+            "selected_memory": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "selection",
+                "pointer",
+                "object_id",
+                "dir_path",
+                "index_path",
+                "source_path",
+                "created_at",
+                "origin",
+                "inherited_from"
+              ],
+              "properties": {
+                "selection": {
+                  "type": "string",
+                  "enum": ["root", "inherited_reuse", "fresh_rebuild"]
+                },
+                "pointer": { "type": "string", "minLength": 1 },
+                "object_id": { "type": "string", "minLength": 1 },
+                "dir_path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                },
+                "index_path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                },
+                "source_path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                },
+                "created_at": { "type": "string", "minLength": 1 },
+                "origin": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["run_id", "task_id", "manifest_path"],
+                  "properties": {
+                    "run_id": { "type": "string", "minLength": 1 },
+                    "task_id": { "type": "string", "minLength": 1 },
+                    "manifest_path": { "type": "string", "minLength": 1 }
+                  }
+                },
+                "inherited_from": {
+                  "type": ["object", "null"],
+                  "additionalProperties": false,
+                  "required": ["run_id", "task_id", "manifest_path"],
+                  "properties": {
+                    "run_id": { "type": "string", "minLength": 1 },
+                    "task_id": { "type": "string", "minLength": 1 },
+                    "manifest_path": { "type": "string", "minLength": 1 }
+                  }
+                }
+              }
+            },
+            "rejected_candidates": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "pointer",
+                  "object_id",
+                  "dir_path",
+                  "index_path",
+                  "source_path",
+                  "created_at",
+                  "origin",
+                  "inherited_from",
+                  "reason",
+                  "detail"
+                ],
+                "properties": {
+                  "pointer": { "type": "string", "minLength": 1 },
+                  "object_id": { "type": "string", "minLength": 1 },
+                  "dir_path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                  },
+                  "index_path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                  },
+                  "source_path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "^(?![A-Za-z]:[\\\\/])(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).+$"
+                  },
+                  "created_at": { "type": "string", "minLength": 1 },
+                  "origin": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["run_id", "task_id", "manifest_path"],
+                    "properties": {
+                      "run_id": { "type": "string", "minLength": 1 },
+                      "task_id": { "type": "string", "minLength": 1 },
+                      "manifest_path": { "type": "string", "minLength": 1 }
+                    }
+                  },
+                  "inherited_from": {
+                    "type": ["object", "null"],
+                    "additionalProperties": false,
+                    "required": ["run_id", "task_id", "manifest_path"],
+                    "properties": {
+                      "run_id": { "type": "string", "minLength": 1 },
+                      "task_id": { "type": "string", "minLength": 1 },
+                      "manifest_path": { "type": "string", "minLength": 1 }
+                    }
+                  },
+                  "reason": {
+                    "type": "string",
+                    "enum": ["missing_artifacts", "provenance_contradiction"]
+                  },
+                  "detail": { "type": ["string", "null"] }
+                }
+              }
+            },
+            "rediscovered_memory": {
+              "type": ["object", "null"],
+              "additionalProperties": false,
+              "required": [
+                "from_pointer",
+                "from_object_id",
+                "to_pointer",
+                "to_object_id",
+                "reason"
+              ],
+              "properties": {
+                "from_pointer": { "type": "string", "minLength": 1 },
+                "from_object_id": { "type": "string", "minLength": 1 },
+                "to_pointer": { "type": "string", "minLength": 1 },
+                "to_object_id": { "type": "string", "minLength": 1 },
+                "reason": {
+                  "type": "string",
+                  "enum": ["missing_artifacts", "provenance_contradiction"]
+                }
+              }
+            },
+            "manual_repairs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["timestamp", "actor", "reason", "outcome", "detail"],
+                "properties": {
+                  "timestamp": { "type": "string", "minLength": 1 },
+                  "actor": { "type": "string", "minLength": 1 },
+                  "reason": { "type": "string", "minLength": 1 },
+                  "outcome": { "type": "string", "const": "accepted" },
+                  "detail": { "type": ["string", "null"] }
+                }
+              }
+            },
+            "counters": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "contradiction_count",
+                "rediscovery_count",
+                "resume_latency_ms",
+                "manual_repair_count",
+                "repeated_failure_streak",
+                "retrieval_hits",
+                "retrieval_misses"
+              ],
+              "properties": {
+                "contradiction_count": { "type": "integer", "minimum": 0 },
+                "rediscovery_count": { "type": "integer", "minimum": 0 },
+                "resume_latency_ms": { "type": ["integer", "null"], "minimum": 0 },
+                "manual_repair_count": { "type": "integer", "minimum": 0 },
+                "repeated_failure_streak": { "type": "integer", "minimum": 0 },
+                "retrieval_hits": { "type": "integer", "minimum": 0 },
+                "retrieval_misses": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        }
+      }
+    },
     "tfgrpo": {
       "type": ["object", "null"],
       "additionalProperties": false,
@@ -879,7 +1255,26 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "sender_agent_path": { "type": ["string", "null"], "minLength": 1 },
+        "receiver_agent_paths": {
+          "type": ["array", "null"],
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "receiver_agents": {
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "thread_id": { "type": ["string", "null"], "minLength": 1 },
+              "agent_nickname": { "type": ["string", "null"], "minLength": 1 },
+              "agent_role": { "type": ["string", "null"], "minLength": 1 },
+              "agent_path": { "type": ["string", "null"], "minLength": 1 }
+            }
+          }
+        },
         "prompt": { "type": ["string", "null"] },
+        "fork_context": { "type": ["boolean", "null"] },
         "agents_states": {
           "type": ["object", "null"],
           "additionalProperties": true

package/skills/chrome-devtools/SKILL.md

@@ -36,5 +36,5 @@ Use this skill when you need browser-grounded evidence (UI screenshots, console
 
 - `standalone-review`: route ad-hoc review checks through a manifest-backed review loop when findings need auditability.
 - `collab-subagents-first`: isolate heavy browser exploration in a dedicated subagent stream to protect parent context.
-- `frontend-design-review`: use when the task emphasis is structured UI/UX critique with evidence-backed recommendations.
+- `frontend-design-review`: optional global skill (not bundled in CO release); use when the task emphasis is structured UI/UX critique with evidence-backed recommendations.
 - `long-poll-wait`: monitor long-running browser-driven checks or CI replay loops to terminal state.

package/skills/codex-orchestrator/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: codex-orchestrator
+description: "Primary entrypoint for Codex Orchestrator usage: route tasks to the right pipeline, mode, and supporting skills with minimal, auditable steps."
+---
+
+# Codex-Orchestrator Workflow Router
+
+## Overview
+
+Use this skill as the default entrypoint for work in CO or downstream repos using `@kbediako/codex-orchestrator`. It routes intent to the smallest correct command path and points to specialized skills only when needed.
+
+## Core Contract
+
+- Keep MCP as the control plane by default.
+- Use docs-first before implementation edits.
+- Use delegation early for non-trivial work with bounded stream ownership.
+- Keep runtime and execution modes explicit and orthogonal:
+  - `runtimeMode=cli|appserver`
+  - `executionMode=mcp|cloud`
+
+## Default Command Path
+
+For most task-scoped work:
+- `codex-orchestrator flow --task <task-id>`
+- `codex-orchestrator doctor --usage --window-days 30 --task <task-id>`
+- `codex-orchestrator review --task <task-id>`
+
+For explicit stage control:
+- `codex-orchestrator start docs-review --task <task-id> --format json`
+- `codex-orchestrator start implementation-gate --task <task-id> --format json`
+- `codex-orchestrator status --run <run-id> --watch --interval 10`
+
+## Intent Router
+
+1) Task/spec scaffolding and mirror sync:
+- Use `docs-first`.
+
+2) Delegation setup/run-control and subagent evidence discipline:
+- Use `delegation-usage`.
+
+3) Stream decomposition across independent bounded work:
+- Use `collab-subagents-first`.
+
+4) Option analysis, tradeoffs, and decision framing before implementation:
+- Use `collab-deliberation`.
+
+5) Long-running checks/reviews/cloud jobs that need patience-first monitoring:
+- Use `long-poll-wait`.
+
+6) Implementation checkpoint reviews and final handoff:
+- Use `standalone-review`, then `elegance-review`.
+
+7) Release/tag/publish workflows:
+- Use `release`.
+
+8) Collab/multi-agent scenario testing and evidence capture:
+- Use `collab-evals`.
+
+## Feature Posture
+
+- `js_repl` is default-on globally (local + cloud lanes); use explicit cloud feature lanes for deterministic contracts.
+- `memories` stays scoped to explicit eval lanes.
+- Subagent context forking (`fork_context`) is guidance-first: keep it `false` for bounded streams, and set `true` only when the child must inherit prior thread history.
+- Compatibility note: upstream still accepts the legacy alias `memory_tool`; use `memories` in new CO guidance unless documenting legacy compatibility behavior.
+
+## Related Docs
+
+- `AGENTS.md`
+- `docs/AGENTS.md`
+- `README.md`
+- `docs/README.md`
+
+## Related Skills
+
+- `docs-first`
+- `delegation-usage`
+- `collab-subagents-first`
+- `collab-deliberation`
+- `standalone-review`
+- `elegance-review`
+- `long-poll-wait`
+- `release`
+- `agent-first-adoption-steering`

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

@@ -102,6 +102,7 @@ Skip subagents when all conditions are true:
   - `message` (plain text), or
   - `items` (structured input).
 - Do not send both `message` and `items` in one spawn call.
+- Keep `fork_context` disabled by default to preserve bounded context. Enable `fork_context=true` only when the subagent needs prior thread history that would otherwise be costly/risky to restate.
 - `spawn_agent` falls back to `default` when `agent_type` is omitted; always set `agent_type` explicitly.
 - Prefix spawned prompts with `[agent_type:<role>]` on line one so role intent is auditable from collab JSONL/manifests.
 - Use `items` when you need explicit structured context (for example `mention` paths like `app://...` or selected `skill` entries) instead of flattening everything into one long string.
@@ -174,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.105.0`, built-in `explorer` inherits top-level model defaults unless you attach a role `config_file`; reserve spark for optional `[agents.explorer_fast]` (text-only caveat).
+- 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.
 - 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

@@ -5,7 +5,7 @@ Use this guide for deeper context on delegation behavior, tool surfaces, and tro
 
 ## Mental model
 
-- The delegation MCP server is a local stdio process (`codex-orchestrator delegate-server`; `delegation-server` is an alias).
+- The delegation MCP server is a local stdio process. Register the direct dist entrypoint (`node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server`); `delegation-server` is still accepted as an alias.
 - It does **not** provide general tools itself; it only exposes `delegate.*` + optional `github.*` tools.
 - Child runs get tools based on `delegate.mode` + `delegate.tool_profile` + repo caps.
 - Delegation MCP stays enabled by default (only MCP on by default); disable it only when required by safety constraints.
@@ -63,7 +63,7 @@ Fix by re-registering the server with a TOML-quoted override:
 codex mcp remove delegation
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' \
-  -- codex-orchestrator delegate-server
+  -- node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server
 ```
 
 ## Server mode vs child mode (don’t mix them up)
@@ -108,12 +108,18 @@ If you want deeper recursion or longer wall-clock time for delegated runs, set R
 ```bash
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' \
-  -- codex-orchestrator delegate-server
+  -- node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server
 ```
 
 For the `rlm` pipeline specifically, use:
 - `RLM_MAX_MINUTES=240` for a 4-hour cap.
 
+If stale delegate-server processes accumulate from prior sessions, remove only the orphaned ones with:
+
+```bash
+codex-orchestrator delegation cleanup-stale --yes
+```
+
 ## delegate.spawn start-only (default)
 
 - `delegate.spawn` defaults to `start_only=true` (requires `task_id`).
@@ -127,7 +133,11 @@ 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 release line.
+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.
+
+Current `0.123.0` 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.
 
 - Check: `codex-orchestrator --version`
 - Update global: `npm i -g @kbediako/codex-orchestrator@latest`
@@ -145,16 +155,19 @@ Delegation MCP expects JSONL. Keep `codex-orchestrator` aligned with the current
 - `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.105.0`, built-in `explorer` inherits top-level defaults unless overridden in `~/.codex/config.toml`.
+- In Codex CLI `0.123.0`, built-in `explorer` continues to inherit top-level defaults unless overridden in `~/.codex/config.toml`.
 - Recommended baseline:
-  - `model = "gpt-5.3-codex"`
+  - `model = "gpt-5.4"`
+  - `review_model = "gpt-5.4"`
   - `model_reasoning_effort = "xhigh"`
-  - `[agents] max_threads = 12` with `max_depth = 4` and `max_spawn_depth = 4`
+  - `[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
   - 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` (text-only caveat).
-  - Add optional `[agents.awaiter]` override for `gpt-5.3-codex` + `high` while preserving awaiter instructions.
-  - Add `[agents.worker_complex]` for high-risk edits (`gpt-5.3-codex`, `xhigh`).
-  - Fallback posture is contingency-only: `8/2/2` (constrained/high-risk), `6/1/1` break-glass.
+  - 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.
+  - 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