Codex templates: OmniRoute gateway profile, verified base keys and the Codex-template token gaps - #395

Codex templates: OmniRoute gateway profile, verified base keys and the Codex-template token gaps

Recommended label: lane:foundation. The branch changes foundation paths (adoption/, tools/, recipes/),
plus tests and three docs that serve only the foundation lane (docs/lanes.md: an unlisted path follows the lane
its change serves). The only shared hot file is manifests/evidence.json. That change only re-registers hashes of
this branch's files through the hot-file protocol, in the last commit, and re-registration alone does not make a PR
shared (docs/lanes.md, "Labels and PRs").

A new host now gets the Codex base keys, the gateway profile and the MCP start-up allowances from the repository's
own writers, not from hand edits:

• tools/adoption/render_config.py for the base template;
• tools/adoption/apply_codex_lane.py for the lane and the profile.

Base: origin/main 5f3a7c21, unchanged on the remote at hand-off. Commits:

• 35219f5e the change;
• cc54d6d1 the fixes for the GPT-6 review;
• f4911c5b a follow-on fix found in the final self-review;
• df30ed50 the fix for the independent verifier's first finding;
• b7493ce8 the evidence manifest, last. It replaces the earlier evidence commit 81c32f17, so the manifest
  change stays in one last commit.

Rebase note. The docs/harness-defaults.md change appends one row to the anti-pattern log, a table that other
2026-09-27 units also append to. Expect a trivial conflict there: keep every row. For manifests/evidence.json,
take main's copy and re-register this branch's ten files (docs/lanes.md, hot-file protocol).

What changed

1. OmniRoute profile template: new adoption/templates/codex.omniroute.config.toml, an opt-in profile-v2 file
   for codex -p omniroute.

   • The provider block lives in the profile, not the base config (K2).
   • Model cx/gpt-6-astra with no router alias (K1), effort max, web_search = "live".
   • [features] standalone_web_search = true and shell_snapshot = false.
   • supports_standalone_web_search = true on the provider; websockets left at the default false (K5).
   • The env_key plus env_key_instructions naming inventory id omniroute, and the keyed
     [shell_environment_policy.filters] exclude for the key (K3).

   The workstation's installed ~/.codex/omniroute.config.toml has the same keys and values (compared by key name on
   2026-09-27, values not printed). The template adds only env_key_instructions.

   The profile's comments state what a gateway build needs, from upstream's own PR text:

   • PR #14904: HTTP 500 on every /v1/responses request on release/v3.8.51;
   • PR #13788: POST /v1/alpha/search, where Codex sends standalone searches.

   The profile's header and the recipe also say what the landscape sweep's lane home shares with the profile. It
   writes the same model, effort, provider and [features] keys, and a test checks each one against the profile.
   It lacks env_key_instructions and the key filter. So a real OMNIROUTE_API_KEY in the sweep harness's
   environment reaches the commands that lane's model runs (see the repair round below).

   apply_codex_lane.py --omniroute-profile installs it the way the stack-worker profile is installed:

   • create-only and journaled;
   • read back with codex -p omniroute debug prompt-input;
   • removed by rollback only while it still holds the template.

   A base config.toml that still carries the gateway route is reported as a host step and never written: the
   [model_providers.omniroute] table, model_provider = "omniroute" or a cx/ model. The step says to delete them
   together, because a model_provider left without its table stops every launch without the profile.

2. Verified and safe PR-F items in adoption/templates/codex.config.template.toml, each with its source in a
   comment:

   • web_search = "live";
   • check_for_update_on_startup = false;
   • [agents] default_subagent_reasoning_effort = "max", plus the note that max_depth does not bound V2 models;
   • [features] shell_snapshot = false (H4);
   • the four dated [projects] trust entries removed.

3. Codex-template token gaps.

   • serena#3 and socraticode#2: the lane's writer sets the template's startup_timeout_sec (60 and 120 s) on
     registered servers, because codex mcp add has no timeout option.
   • jcodemunch-mcp#1 and Publish evidence-led convergence practice and retrieval comparisons #2: the recipe no longer offers codex mcp add, which writes user scope. For a checkout or
     worktree that opts in, it:
     • installs the server into the ecosystem prefix the template names;
     • copies only the rendered [mcp_servers.jcodemunch] tables there;
     • keeps that file untracked through info/exclude.
   • headroom#2: headroom's recipe gains a Codex registration line with all four offline variables.
   • socraticode#3 and ai-memory#1: INCLUDE_DOT_FILES and the approval-never refusal are documented where the
     servers are registered.

4. recipes/README.md Codex rows, only where these changes required them:

   • the new "Codex through OmniRoute" section;
   • the codex component row's update-check note;
   • the worker-lane list, and the jCodeMunch and headroom steps.

   A dated addendum in docs/decisions/2026-09-26-codex-worker-lane.md records the decisions, the evidence and the
   overturn conditions. One proven mistake is in the anti-pattern log of docs/harness-defaults.md.

Corrections to the inputs, found while verifying

• codex debug refuses --strict-config at 0.157.1. So the synthesis's PR-G2 check "codex --strict-config -p omniroute debug prompt-input" cannot run as written. The strict read goes through exec, which stops at the
  missing key before any request.
• --strict-config -p stack-worker fails with "invalid transport". Strict mode validates each file on its own,
  and the profile's server tables name no command. So PR-F's "always pass --strict-config" cannot apply to
  stack-worker lanes as designed.
• The verifier's "--strict-config rejects omniroute run codex --model" holds. The launcher's full flag set is
  refused. Only the lone key is merely warned about. The first draft of this branch claimed the opposite from a
  probe of the lone key; the GPT-6 review caught it, and it is now in the anti-pattern log.
• K7 (require a key) is superseded. The user's 2026-09-27 passwordless, keyless loopback decision, recorded by
  the OmniRoute lane, replaces it, so env_key_instructions also allows any non-empty value for a keyless loopback
  gateway (upstream guide L65-75).

SOTA sources

Upstream files were fetched with gh api at the refs below on 2026-09-27 and kept for re-checking. Each cited
file was then fetched a second time and compared byte for byte: 27 files, all identical.

• The first re-check covered 20 files.
• The independent verifier found six codex files with no second copy: config_layer_source.rs,
  strict_config.rs, spec_plan.rs, responses_lite.rs, endpoint/search.rs and models.json.
• The repair round fetched those six again, plus protocol/src/config_types.rs, which it newly cites. Their cited
  lines read the same as before.

The git documentation was fetched once, at the two refs named below.

• openai/codex rust-v0.157.1 (the pin in manifests/stack.json; the tag resolved to commit 36650394 on
  2026-09-27), under codex-rs/:

  • config/src/config_toml.rs: L208-209, L520-523, L719-724, L979-983, L992-1001;
  • config/src/config_layer_source.rs: L33-51;
  • config/src/loader/mod.rs: L131-133, L257-258, L286-334, L594-600, L625-645, L647-669, L1041-1084;
  • config/src/strict_config.rs: L97-110;
  • config/src/shell_environment_policy.rs: L28-35, L106-110, L135-136;
  • protocol/src/config_types.rs: L205-214 (inherit's kebab-case all, the default);
  • core/src/config/mod.rs: L1591-1605, L2659-2670, L2733-2746, L3050-3094, L3797;
  • core/src/agent/child_config.rs: L196-250;
  • core/src/session/multi_agents.rs: L77-111;
  • core/src/mcp_tool_call.rs: L1610-1614, L2436-2466;
  • core/src/tools/runtimes/mod.rs: L268-276;
  • core/src/tools/spec_plan.rs: L598-601;
  • core/tests/suite/responses_lite.rs: L328-370 (an unchanged upstream test, read, not run);
  • codex-mcp/src/rmcp_client.rs: L103, L342;
  • codex-api/src/endpoint/search.rs: L14-15;
  • features/src/lib.rs: L1007-1012, L1115-1120;
  • model-provider-info/src/lib.rs: L190-192, L601-603;
  • models-manager/models.json: L4-23;
  • git-utils/src/trust.rs: L9-16;
  • cli/src/debug_sandbox.rs: L258-259;
  • shell-command/src/shell_snapshot_exports.rs.

  Installed codex-cli 0.157.1 help was also read: codex mcp add --help has --env and no timeout option.

• diegosouzapw/OmniRoute:

  • v3.8.50 = 5458026c216f77a3da68ea49152dc33470cfe2cb: open-sse/executors/codex.ts L331-355;
  • release/v3.8.51 at a58000c7685f4091c7a6fd8ddf3ebce7d2ec67c3:
    • docs/guides/CODEX-CLI-CONFIGURATION.md L22-41, L26-41, L65-75, L150-161;
    • open-sse/executors/codex/reasoningSuffix.ts L1-31;
    • bin/cli/commands/launch-codex.mjs L173-194;
    • bin/cli/commands/run.mjs L162;
  • PR #14904 (head b94e2dba, open) and PR #13788 (head 6c799005, open, label deferred-v3.8.52), read
    2026-09-27;
  • latest release v3.8.50; release/v3.8.51 head a58000c7 on 2026-09-27.

• giancarloerra/SocratiCode v1.14.0: README.md L1579 (INCLUDE_DOT_FILES).

• git/git: the info entry of the repository-layout page, in two copies:

  • Documentation/gitrepository-layout.adoc at master 0f8e75abebff0877cae681a3d5ff31ac47f54220;
  • Documentation/gitrepository-layout.txt at v2.43.0, the installed git.

  Both say the directory is ignored when $GIT_COMMON_DIR is set, and $GIT_COMMON_DIR/info is used instead, as
  in a linked worktree. The recipe links git-scm.com's current page.

• astral-sh/uv 0.12.17 (installed): uv help tool dir documents $UV_TOOL_DIR and $UV_TOOL_BIN_DIR. The
  recipe mirrors adoption/bootstrap.md step 4's uv-tool layout.

• Inputs, used as evidence to verify rather than as authority:

  • the 2026-09-27 settings synthesis (K1-K5, K11, H4, H5, H7, PR-F, PR-G2) with its adversarial Codex verification;
  • the OmniRoute lane's facts for record ("Codex wiring");
  • the token-stack verdict gaps named above.

Evidence (classes kept separate)

• Local integration, real codex-cli 0.157.1. Scratch CODEX_HOMEs ran under bwrap --unshare-net with a
  private /tmp, with no sign-in, no gateway and no network. NAS_CODEX_INTEGRATION=1 python3 -m unittest tests.test_codex_worker_lane.CodexIntegrationTests ran 7 tests, all OK:

  • --strict-config -p omniroute exec stops at the missing key, printing the profile's instructions;
  • the env filter control: a fixture key reaches a command without the filter and not with it;
  • strict mode refuses the launcher's flag set, while the lone key is only warned about;
  • -p stack-worker fails under --strict-config and renders without it;
  • the recipe's jCodeMunch step registers the server only in the trusted checkout it was copied into;
  • the real app-server writes serena's allowance and rolls back byte for byte;
  • project-over-profile precedence.

  Ad hoc runs the same day:

  • a leftover base model_provider = "omniroute" without its table fails launches without the profile;
  • a legacy base exclude array plus this profile's filters loads (mixing is refused only within one layer).

• Synthetic fixtures:

  • fake-codex dry run, apply and rollback of the profile, the start-up allowances and the base-selector host step;
  • a render test that runs the recipe's own sed range, which fails against the first draft of the recipe.

• Source review: the files above. Unchanged upstream tests: read only, none run.

• Live provider execution: none for this change. The profile's live gateway acceptance belongs to the OmniRoute
  lane's record. The GPT-6 review below ran through the gateway; it is a review, not acceptance.

• Read-only host observation (2026-09-27, key names and these values only):

  • ~/.codex/config.toml already carries the four base keys and no dated trust entries, and has no gateway route
    left;
  • ~/.codex/omniroute.config.toml matches the template except for env_key_instructions;
  • serena's and socraticode's startup_timeout_sec are absent;
  • headroom has all four offline variables.

  Nothing on the host was changed; the mtimes of the four Codex files are unchanged.

Acceptance (at b7493ce8, after the repair round)

The same five passed at 81c32f17 before the repair round. The host's four Codex files kept their mtimes through
both rounds.

The 24 modules are the covering tests:

• test_codex_worker_lane, test_render_config and test_observability_tool_names;
• test_landscape_sweep_harness;
• the adoption and docs modules that read recipes/README.md, adoption/bootstrap.md, the handbook or
  docs/harness-defaults.md;
• the manifest and report modules.

Cross-family review (GPT-6, one round)

codex-omniroute exec --skip-git-repo-check -s read-only ran from the worktree with cx/gpt-6-astra at max through
the local OmniRoute gateway, from 09:53:01Z to 10:05:47Z. It reviewed head 56f44260, the first two-commit form of
this branch; its review.diff is that head's diff. Codex counted 180,664 tokens used. The Bash foreground cap
is 10 minutes and the brief allowed 30, so the harness held the process with run_in_background and this session
blocked on it before doing anything that depended on the result.

Verdict: DEFECTS FOUND, 4 findings, 4 fixed. Each was reproduced or checked against source before it was fixed:

1. High. recipes/README.md: the jCodeMunch step copied the whole project template, whose approval_policy
   and sandbox_mode outrank the user config (config_layer_source.rs L33-51). Fixed: only the jCodeMunch tables
   are copied, and a test runs the recipe's own sed.
2. Medium. apply_codex_lane.py: the host step missed a base model_provider = "omniroute". Reproduced
   "Model provider omniroute not found". Fixed: the step lists the table, the selector and a cx/ model to
   delete together, reads back without the profile too, and has a test with a control.
3. Medium. The launcher claim rested on the lone key. Reproduced: the launcher's full flag set is refused
   under --strict-config. Fixed in the recipe and the addendum, with an opt-in test of both vectors and an
   anti-pattern row.
4. Medium. The recipe's plain uv tool install did not populate ${ECO_ROOT}/bin/jcodemunch-mcp. Fixed: the
   bootstrap's prefix-aware install, with the Claude line on the same path.

Residuals: none unfixed from the review. No second round was run, as the brief required.

Follow-on fix (f4911c5b), found in the final self-review, not by GPT-6. The fix for finding 4 defined eco= only
in the install block. A host that pasted only the registration block would have registered /bin/jcodemunch-mcp
for Claude. Each block that uses $eco now defines it first, and the render test checks every such block (it fails
against cc54d6d1's recipe).

Repair round (independent verifier, one round)

The independent verifier reported two low findings on 81c32f17. Both were checked against source; both are fixed.
No second GPT-6 round was run.

1. Low. The sweep lane home is not "equal" to the profile. The profile's header (L7-8) and the recipe's
   Workers bullet said the landscape sweep's lane home and this profile are kept equal. Checked:

   • build_args.py stage_lane_home (L172-203) writes no env_key_instructions, no key filter and no
     web_search;
   • the test compares only the keys that home writes.

   Fixed in df30ed50. Both places, and the test's comment, now say what the test checks and what the home
   lacks. web_search = "live" reaches that lane from the stack-worker profile and the runner's -c flag. The
   exposure itself follows from three sources:

   • with no filter, Codex hands each command its whole environment: config_toml.rs L208-209 and
     core/src/config/mod.rs L3797 reach shell_environment_policy.rs L135-136;
   • codex_job.py L311-312 lets a real key win over the lane's placeholder;
   • the opt-in test_the_omniroute_filter_keeps_the_key_out_of_commands is the measured local control.

   So a real OMNIROUTE_API_KEY in the sweep harness's environment reaches the commands that lane's model runs.
   The recipe now says so. Until the sweep lane writes the filter, it tells operators to leave the variable unset
   for a keyless loopback gateway.

2. Low. The SOTA-sources sentence claimed a check that was only partly done. Six cited codex files had no second
   copy. Fixed: they were fetched again at rust-v0.157.1, with the newly cited config_types.rs. All seven are
   byte-identical to the first copies, and the sentence now gives the count. The git/git entry, previously
   unpinned, now names two refs.

Residual, not fixed here. The sweep lane home still has no [shell_environment_policy.filters] exclude for the
key.

• Why not here: the fix changes tools/sota-convergence/landscape-sweep/build_args.py. That file belongs to the
  landscape-sweep lane (Landscape-sweep GPT-6 lane through OmniRoute: lane-local Codex home with the token stack at max effort (stacked on #385) #387), not this unit. AGENTS.md asks for a hand-off to the session that owns an area
  instead of an edit.
• The fix: in stage_lane_home, a [shell_environment_policy.filters] table with "OMNIROUTE_API_KEY" = "exclude", the keyed form this profile uses.
• This branch's test asserts no absence, so that change will not break it.

Token tools used by this unit:

• ctx_execute to extract the input sections and read cited upstream line ranges without loading whole files;
• Bash under RTK for commands.

Serena, jCodeMunch and Headroom were not used: every read was a known file and line range, and each stayed small.
The repair round used Bash under RTK for known line ranges and byte comparisons, and a Monitor to wait on the test
run. Every output stayed small, so no context-mode call was needed.

Host follow-ups (not code)

• Gateway profile. The host's omniroute.config.toml differs from the template only by env_key_instructions,
  so apply_codex_lane.py --omniroute-profile refuses until that file is moved aside privately. Either move it and
  apply, or keep it; it is functionally the same.
• Start-up allowances (serena#3, socraticode#2). Absent on the host. The lane's dry run plans absent -> 60 and
  absent -> 120, and --apply with the printed hashes sets them. It refuses while codex processes run.
• jcodemunch-mcp#1. Run the recipe's step in each opted-in fresh worktree, then verify discovery and exact source
  retrieval there.
• context-mode#1. Choose whether the main checkout keeps its fixed-project override
  (apply_codex_lane.py --project-config).
• H4 remainder.
  • chmod 600 the existing ~/.codex/shell_snapshots/*.sh.
  • The operator, not an agent, checks them for exported secrets, deletes them and rotates any key found.
  • The Claude Read(~/.codex/shell_snapshots/**) deny belongs to the Claude-settings unit.
• H7 and U11. Remove the host's [projects."…/clone"] trust entry (its directory is gone), and decide on tmp.
• ai-memory#1. A restricted approval-never worker still cannot call ai-memory. Qualify a narrowly permitted recall
  integration or an upstream read-only annotation before claiming it.

Not done

• User decisions:
  • U4: the interactive effort, ultra or max;
  • U7: per-tool read approvals in interactive Codex;
  • U11: the host tmp trust entry.
• PR-F items outside this unit's four:
  • the stack-worker knobs mcp_optional_startup_grace_ms = 0, required = true and a pinned
    model_reasoning_summary (experiment class; they wait for a measured trial);
  • headless codex.lane.<name>.toml lane configs;
  • the bare-@path, prompt-input-size and project_doc_max_bytes repository check;
  • the skills-location and native-memories doc lines.
• PR-G2's review comments on Landscape-sweep GPT-6 lane through OmniRoute: lane-local Codex home with the token stack at max effort (stacked on #385) #387: Landscape-sweep GPT-6 lane through OmniRoute: lane-local Codex home with the token stack at max effort (stacked on #385) #387 merged before this branch.
• Other units' files: no OmniRoute decision record, receipt or evidence, and no Claude settings template; other
  units own them.
• The sweep lane's key filter in tools/sota-convergence/landscape-sweep/build_args.py: a residual for the
  landscape-sweep lane's owner (see the repair round).

🤖 Generated with Claude Code