@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/schemas/manifest.json

@@ -62,6 +62,20 @@
     "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"] },
+    "provider_linear_worker_tokens": {
+      "anyOf": [
+        { "type": "null" },
+        { "$ref": "#/definitions/providerLinearWorkerTokenUsage" }
+      ]
+    },
     "summary": { "type": ["string", "null"] },
     "metrics_recorded": { "type": "boolean" },
     "resume_token": { "type": "string", "minLength": 1 },
@@ -239,6 +253,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 +484,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 +573,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,6 +1261,24 @@
           "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": {
@@ -1175,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.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.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

@@ -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,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 release line.
+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.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`
@@ -145,16 +157,22 @@ 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`.
-- Recommended baseline:
-  - `model = "gpt-5.3-codex"`
+- 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` with `max_depth = 4` and `max_spawn_depth = 4`
+  - 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` (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`).
+  - 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

@@ -61,9 +61,9 @@ Optional (only if you need it):
 - If the task needs external docs or APIs, enable only the relevant MCP server for that environment.
 - If `delegate.spawn` is missing, re-register the MCP server with full mode (server config controls tool surface):
   - `codex mcp remove delegation`
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- codex-orchestrator delegate-server`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server`
 - To raise RLM budgets for delegated runs, re-register with an override (TOML-quoted):
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- codex-orchestrator delegate-server`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server`
 
 For deeper background patterns and troubleshooting, see `DELEGATION_GUIDE.md`.
 For runner + delegation coordination (short `--task` flow), see `docs/delegation-runner-workflow.md`.
@@ -89,10 +89,12 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
   - Optional low-friction MCP enable pass: `codex-orchestrator mcp enable --yes`
     - Enables disabled MCP servers from existing Codex config entries (plan mode redacts env/secret values in displayed command lines).
   - `codex-orchestrator delegation setup --yes`
-    - Delegation-only setup (wraps `codex mcp add delegation ...` and keeps wiring discoverable via `codex-orchestrator doctor`).
-  - `codex mcp add delegation -- codex-orchestrator delegate-server`
+    - Delegation-only setup (registers the direct dist transport and keeps wiring discoverable via `codex-orchestrator doctor`).
+  - `codex mcp add delegation -- node /path/to/@kbediako/codex-orchestrator/dist/bin/codex-orchestrator.js delegate-server`
   - Optional: append `--repo /path/to/repo` to pin the server to one repo (not recommended if you work across repos).
   - `delegate-server` is the canonical name; `delegation-server` is supported as an alias.
+  - `codex-orchestrator delegation cleanup-stale --yes`
+    - Safe cleanup for orphaned delegate-server processes that are no longer rooted in a live Codex client.
 - Per-run `-c 'mcp_servers.delegation.enabled=true'` only works **after** registration.
 - If `delegate.*` tools are missing mid-task, start a new run with:
   - `codex -c 'mcp_servers.delegation.enabled=true' ...`
@@ -103,7 +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 release line.
+- 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`
@@ -120,17 +125,23 @@ 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.105.0`, built-in `explorer` inherits top-level model defaults unless a role `config_file` overrides it.
-- Recommended baseline in `~/.codex/config.toml`:
-  - `model = "gpt-5.3-codex"`
+- 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` with `max_depth = 4` and `max_spawn_depth = 4`
+  - 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`, text-only)
-  - Optional `[agents.awaiter]` override -> `~/.codex/agents/awaiter-high.toml` when you want awaiter at `gpt-5.3-codex` + `high` while preserving awaiter instructions
-  - `[agents.worker_complex]` -> `~/.codex/agents/worker-complex.toml` (`gpt-5.3-codex`, `xhigh`)
-- Fallback posture is contingency-only: `8/2/2` for constrained/high-risk lanes, `6/1/1` as break-glass under severe contention.
-- Downstream users can get this baseline via `codex-orchestrator init codex` (ships `.codex/config.toml` + role files).
+  - 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`)
+- 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)