fix: reject incompatible Codex effort before spawn

[EtanHey]

Summary

• restrict spawn_agent to the cross-version Codex effort set accepted by live launcher functions
• reject incompatible effort before worktree, branch, or surface creation
• document why the schema is intentionally a safe subset of newer launcher source

Verification

• bun run typecheck
• bun run build
• bun run test — 107 files passed; 2,492 tests passed; 1 skipped
• real dist/index.js MCP probe rejected effort:"low" with the four-value enum and created no worktree or branch
• coderabbit review --agent — 0 findings across 4 changed files

Refs #379 (remaining fixes tracked in #381)

— cmuxlayerCodex (worker) · codex/gpt-5.6-sol

---

Note

Medium Risk
Changes agent dispatch validation and advertised effort options; callers using low or max will fail spawn, but incompatible values are blocked before worktree/surface creation.

Overview
Codex effort for spawn_agent is narrowed to medium, high, xhigh, ultra so the MCP schema and resolveSpawnEffort match what the installed repoGolem launcher (~/.config/ralphtools/golem-dispatch.zsh) accepts in practice. Values such as low and max that may exist in a newer golems checkout are rejected at validation with a clearer error before any worktree, branch, or surface is created.

The spawn_agent effort field description is updated to list only those four values and to document the live launcher default (XHIGH when omitted), replacing stale references to a six-value ladder and an older default.

Drift/parity tests now read the installed dispatch script (not the golems repo path), parse the Codex effort ladder from _golem_parse_codex_flags, and assert CODEX_EFFORT_VALUES equals that ladder. Server tests cover schema acceptance/rejection and a preflight failure path that ensures incompatible effort does not trigger worktree or surface setup.

^{Reviewed by Cursor Bugbot for commit 6c41c43. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Reject incompatible Codex effort values before worktree or surface creation

• Removes "low" and "max" from CODEX_EFFORT_VALUES in model-policy.ts, leaving the accepted ladder as medium, high, xhigh, ultra to match the installed launcher at ~/.config/ralphtools/golem-dispatch.zsh.
• Updates the resolveSpawnEffort error message format from Accepted values: ... to (expected: ...) and updates the spawn_agent zod schema description to reflect the new ladder.
• Adds a preflight rejection test that confirms spawn_agent with cli=codex and effort=low returns a structured error with no worktree or surface side effects.
• Behavioral Change: effort=low and effort=max are now rejected before any spawn occurs; previously max was accepted.

^{Macroscope summarized 6c41c43.}

Summary by CodeRabbit

• Bug Fixes

  • Restricted Codex effort options to the supported values: medium, high, xhigh, and ultra.
  • Unsupported effort values are now rejected before any work begins, with clearer error messaging.
  • Added validation to prevent setup changes when an invalid effort is provided.

• Tests

  • Expanded coverage for supported and rejected effort values across launcher compatibility scenarios.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_fe21e775-1245-4c51-aad3-d43bb9f0c90c)

[coderabbitai]

📝 Walkthrough

Walkthrough

The Codex effort contract now supports only medium, high, xhigh, and ultra. Server schema text, validation errors, parity checks, schema tests, and launcher preflight tests were updated accordingly.

Changes

Codex effort alignment

Layer / File(s)	Summary
Effort contract and schema src/model-policy.ts, src/server.ts	The exported Codex effort values and spawn_agent schema now exclude low and max. Invalid-effort errors use “expected” values.
Effort validation coverage tests/model-policy-drift.test.ts, tests/server-agent-tools.test.ts	Tests verify the supported subset, reject unsupported values, and confirm launcher-incompatible efforts fail before worktree or surface creation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• EtanHey/cmuxlayer#351: Modified the same Codex effort values, schema, and tests.
• EtanHey/cmuxlayer#359: Modified the Codex effort ladder and related parity tests.

Poem

A rabbit checks the effort list,
“low” and “max” now cease to exist.
Medium to ultra, neat and bright,
Preflight stops the wrong launch right.
No orphaned worktree hops tonight! 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes narrow the effort enum and validate unsupported values before creating worktrees, branches, or surfaces as required by issue #379.
Out of Scope Changes check	✅ Passed	All code and test changes directly support the effort validation and pre-spawn resource safety requirements in issue #379.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes rejecting incompatible Codex effort values before spawning an agent.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/379-effort-validation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: af1e3d1441

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve low and max for compatible launchers

Restricting the shared enum unconditionally removes low and max even when the installed launcher supports them; the preceding contract explicitly allowed these values, and max is used for pinned lanes. Thus upgrading cmuxlayer breaks valid callers and prevents them from selecting supported effort levels merely because a different environment might retain an older function. Keep the stable tool inputs and perform the compatibility check against the actual launcher before resource creation instead.

AGENTS.md reference: AGENTS.md:L44-L47

Useful? React with 👍 / 👎.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e453b23b-520c-43fc-b84b-95128e7dad6f)