Skip to content

Codex worker profile: serena and codebase-memory required at session start #436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
seathatflowsinourveins wants to merge 6 commits into from
Closed

Codex worker profile: serena and codebase-memory required at session start #436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2da1144
Codex worker profile: serena and codebase-memory required at session …
Sep 27, 2026
bb35c5e
Codex worker lane: repair round for the required start-up review
Sep 27, 2026
4450860
Decision record: reflow the grace paragraph; note the native class rerun
Sep 27, 2026
97d9b2d
Decision record: the added start-up wait is only the part past the grace
Sep 27, 2026
2ba0e79
Codex worker lane: GPT-6 repair round for the required start-up
Sep 27, 2026
b18d9f0
Hot files: evidence registration and generated reports
Sep 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions adoption/templates/codex.omniroute.config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,13 @@
# `tools/adoption/render_config.py --check` keeps comparing a host's base config with it. Install it with
# `tools/adoption/apply_codex_lane.py --omniroute-profile` as $CODEX_HOME/omniroute.config.toml. A worker has one
# --profile slot, which stack-worker holds, so the landscape sweep's gateway lane writes its own lane home
# (tools/sota-convergence/landscape-sweep/build_args.py) with this file's model, effort, provider and [features]
# keys, and tests/test_codex_worker_lane.py checks each one it writes against this file. That home has no
# env_key_instructions and no [shell_environment_policy.filters]; its web_search = "live" comes from the
# stack-worker profile and the runner's -c flag. Without the filter Codex hands commands its whole environment
# (inherit "all", default excludes ignored: codex-rs/config/src/shell_environment_policy.rs L135-136 at
# rust-v0.157.1), so a real OMNIROUTE_API_KEY exported for a sweep reaches the commands its model runs.
# (tools/sota-convergence/landscape-sweep/build_args.py stage_lane_home) with this file's model, effort, provider,
# [features] and key filter, and tests/test_codex_worker_lane.py checks each one it writes against this file. That
# home's config.toml writes the same [shell_environment_policy.filters] OMNIROUTE_API_KEY = "exclude" (build_args.py
# L259-261 and L270-271), since without a filter Codex hands commands its whole environment (inherit "all", default
# excludes ignored: codex-rs/config/src/shell_environment_policy.rs L135-136 at rust-v0.157.1) and a real
# OMNIROUTE_API_KEY exported for a sweep would reach the commands its model runs. The home has no
# env_key_instructions; its web_search = "live" comes from the stack-worker profile and the runner's -c flag.
#
# Effort: OmniRoute 3.8.50 caps any model missing from MAX_EFFORT_BY_MODEL at xhigh, gpt-6-astra included
# (open-sse/executors/codex.ts L331-355 at 5458026c). release/v3.8.51 at a58000c7 caps gpt-6-astra at ultra, one
Expand Down
15 changes: 15 additions & 0 deletions adoption/templates/codex.stack-worker.config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,26 @@ CHUB_FEEDBACK = "0"
# Default is 30 s (codex-mcp/src/rmcp_client.rs:103); connection_manager.rs consumes it.
# https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/codex-mcp/src/rmcp_client.rs#L103
# Partial tables retain user commands; profile 21 < project 25 < -c 30 (source in header).
# required = true: session start waits for the server and fails if it cannot start, so a worker never runs
# without these tools. Field: config/src/mcp_types.rs L233-235; the wait: codex-mcp/src/connection_manager/
# required.rs L15-59, awaited with `?` at core/src/session/session.rs L1860-1867 (all at rust-v0.157.1).
# https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/config/src/mcp_types.rs#L233-L235
# https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/codex-mcp/src/connection_manager/required.rs#L15-L59
# Without it, a server still starting one shared 1 s grace after the first tool-list build
# (codex-mcp/src/mcp/mod.rs L195) is left out of that request (connection_manager/tool_catalog.rs L251-277).
# Both servers answer initialize in 1.2-2.3 s here, and a custom provider such as the OmniRoute gateway has no
# websocket prewarm to hide it. mcp_optional_startup_grace_ms stays unset: it would wait for every optional
# server and never fail. Every -p stack-worker session start now waits for both, `debug prompt-input` included,
# so run workers under the account's HOME: codebase-memory-mcp 0.11.0 does not start beside its account daemon
# under another home (measured 2026-09-27).
# Decision record: docs/decisions/2026-09-26-codex-worker-lane.md, addendum 2026-09-27 "Required start-up".
[mcp_servers.serena]
startup_timeout_sec = 60
required = true

[mcp_servers.codebase-memory]
startup_timeout_sec = 60
required = true

# These three servers declare no MCP tool annotations, so under approval_policy = "never" Codex refuses every call
# to them ("MCP tool call requires approval, but approval policy is never"). Workers get their read tools, approved.
Expand Down
163 changes: 163 additions & 0 deletions docs/decisions/2026-09-26-codex-worker-lane.md
View file
Open in desktop

Large diffs are not rendered by default.

28 changes: 14 additions & 14 deletions manifests/evidence.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3732,13 +3732,13 @@
},
{
"path": "adoption/templates/codex.omniroute.config.toml",
"sha256": "0751419f445daaa7735e952af41fa93b1b0464de36282d22b38573653891aba8",
"bytes": 4932
"sha256": "aef7d77408c8d47047ea21056528d9e37a512aef420dc28e35d5a1e1c2d42fe2",
"bytes": 5066
},
{
"path": "adoption/templates/codex.stack-worker.config.toml",
"sha256": "922e6c5f8fd5f07973345148514c215d7ca9768eee94be92eadb7d5efadbc169",
"bytes": 4458
"sha256": "51be338ec5cc80261ef7b9a73119e857cf16c87de2968086997003198dea3621",
"bytes": 5815
},
{
"path": "adoption/templates/project.codex.config.template.toml",
Expand Down Expand Up @@ -13818,8 +13818,8 @@
},
{
"path": "docs/decisions/2026-09-26-codex-worker-lane.md",
"sha256": "15092d762e018a24df27f04019d5d14542ddf739f054380f142224d1837e7f5a",
"bytes": 50684
"sha256": "d639711f173054c8a3402e5095b2478fa9559d400c9cc53b508b0a8e5b04d555",
"bytes": 67334
},
{
"path": "docs/decisions/2026-09-26-harness-rules-cleanup.md",
Expand Down Expand Up @@ -38693,8 +38693,8 @@
},
{
"path": "recipes/README.md",
"sha256": "1ed331c14a48569a991ee03ae72a5b0af778e1b393ef08d00064b5486ce55ca5",
"bytes": 121039
"sha256": "bff34a5507ec373fbf2b33bb3d752e2dda50fe37f158763afac7568d04487a5f",
"bytes": 122265
},
{
"path": "recipes/claude-codex-cooperation-lanes.md",
Expand Down Expand Up @@ -39263,8 +39263,8 @@
},
{
"path": "tests/test_codex_worker_lane.py",
"sha256": "3338942353fbcf0464e2437969c81da6d3e8a02baee87fdba07fc98fcd5d3cbf",
"bytes": 95109
"sha256": "99f339b842989ee38ae85d8d55e29debfa721859d4ecd1bc62e45939437223c5",
"bytes": 119866
},
{
"path": "tests/test_codex_worker_skill.py",
Expand Down Expand Up @@ -39863,8 +39863,8 @@
},
{
"path": "tools/adoption/apply_codex_lane.py",
"sha256": "a5605cb436cb5fad97394d7c35634e3901c2321a1f7aa33a8aa293a8e4f159db",
"bytes": 62148
"sha256": "7c452c6d2d8843d42465ceb704f7110bd7b2e8dc9c6cd2e09e2304a859afc2e7",
"bytes": 66775
},
{
"path": "tools/adoption/embed_acceptance.py",
Expand All @@ -39883,8 +39883,8 @@
},
{
"path": "tools/adoption/prove_codex_lane.py",
"sha256": "a399117aa14bec57fd5be59badc0121523148449ae758d7d37ecf052f7c92e23",
"bytes": 31531
"sha256": "7a7be185540091f164ffe07fdfdaf0ac5262e361e0c6fe3f048bdeec2717703e",
"bytes": 31685
},
{
"path": "tools/adoption/render_config.py",
Expand Down
2 changes: 2 additions & 0 deletions recipes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,8 @@ This lane changed after `v2026.09.26.2`: a host checked out at that tag has none

The 2026-09-27 custom-agent and worker-profile update adds `CHUB_TELEMETRY = "0"` and `CHUB_FEEDBACK = "0"` under the worker profile's `[shell_environment_policy.set]`. A worker with another `HOME` or `CHUB_DIR` can miss the user's Context Hub configuration; the explicit worker profile opts out for its shell commands, including when the home is shared. Codex `rust-v0.157.1` loads the separate profile file as a full second user layer ([loader](https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/config/src/loader/mod.rs)), and Context Hub `v0.1.4` checks these variables before home-scoped settings ([telemetry](https://github.com/andrewyng/context-hub/blob/v0.1.4/cli/src/lib/telemetry.js), [config](https://github.com/andrewyng/context-hub/blob/v0.1.4/cli/src/lib/config.js)). The [decision addendum](../docs/decisions/2026-09-26-codex-worker-lane.md#2026-09-27-addendum-custom-agents-and-context-hub) verifies profile environment loading with source and a native sandbox test, and covers the [F4 RTK guidance](../docs/decisions/2026-09-26-token-practice-f1-f9.md#f4-codex-rtk-guidance-2026-09-26) refresh in the [three custom-agent templates](../examples/codex-native/README.md#2026-09-27-custom-agent-instruction-refresh).

The profile also marks serena and codebase-memory `required` (2026-09-27). At `rust-v0.157.1` Codex gives a server that is not required one shared second after it first builds the tool list, then sends the request without it ([`tool_catalog.rs` L251-277](https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs#L251-L277)); both servers answer `initialize` in 1.2-2.3 s here, and a custom provider such as the OmniRoute gateway has no websocket prewarm to cover the wait. Every `-p stack-worker` session start, `codex debug prompt-input` included, now waits for both and stops with "required MCP servers failed to initialize: <name>: <error>" when one cannot start ([`required.rs` L15-59](https://github.com/openai/codex/blob/rust-v0.157.1/codex-rs/codex-mcp/src/connection_manager/required.rs#L15-L59)). Run workers under the account's own `HOME`: codebase-memory-mcp 0.11.0 does not start beside its account daemon under another home. The apply script's dry run relaxes the two for its scratch home only; its apply read-back starts them. Evidence and alternatives: [the addendum](../docs/decisions/2026-09-26-codex-worker-lane.md#2026-09-27-addendum-required-start-up).

Start every worker with the profile **and** the model, effort and web search on its command line, with stdin closed:

```sh
Expand Down
Loading
Loading