#36260 Action argument contract: the app exports each action's arguments, and a Linux test fails any CLI call site that names one the app does not take

Leo, 2026-11-05, after a Cloud chat failed because the CLI sent promptId and the app's cloudRelayChat only took prompt-id: "You guys keep running into these. These are weird issues that I feel like you should be able to just fix beforehand and check on beforehand."

This makes that class of drift (a CLI call site naming an app action argument the app does not take) fail CI before it merges.

What changes

• One source of truth. ActionSurfaceExport now writes each action's args (name, kind, required, enum values, target kind) into the checked-in plans/cmux-next/action-surfaces.json. It is regenerated here, and the existing exportIsFresh and PR autofix keep it current.

• Rust contract test (Linux). cli/tests/action_argument_contract.rs scans cmux-tui's sources for every place an app action is named by hand: CLI words (["cloud", "relay-chat", ..]), action_run_params("ID"), or "action": "ID". It fails on any --flag or args key the action does not take under its canonical name. Words that the CLI's own grammars take first (mux, agents, and chat_scope's sender flags) are skipped. A self-test plants the promptId drift in each call shape.

• Swift contract test. ActionArgumentContractTests checks four things: every argument is lowerCamelCase, no two arguments of one action fold to one name, the export carries every argument, and the old spellings still resolve.

• Canonical names. camelCase is the canonical spelling, because the CLI turns every --flag-name into flagName. The router folds case, - and _, so prompt-id/prompt_id keep working for one release.

• Drift fixed (found by the new checks):

  • history.open new_tab becomes newTab.
  • palette.installCLI cmux_next becomes cmuxNext.
  • The in-process tab.moveToNewSplit keep_focus becomes keepFocus.

  None of these could be reached from cmux. cloudRelayChat's promptId itself was fixed by #36193.

Changelog

Fixed: cmux history open --new-tab and cmux settings install-cli-in-path --cmux-next reach their app arguments.

Verification

• The fleet Mac regenerated the exports at de08d2f with 14 tests passing, the new suite included.
• cargo test -p cmux-tui --lib action_argument_contract passed on fleet Linux at this head: 3 tests.

Agent session: agent session

🤖 Generated with Claude Code

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

The app now exports each action's arguments into plans/cmux-next/action-surfaces.json as the single source of truth, so a CLI call site can't name an argument the app doesn't take — which previously broke cmux cloud start-chat when the CLI sent promptId while the app expected prompt-id. A Linux test scans cmux-tui sources for hand-written call sites and fails on any --flag or args key the action doesn't take under its canonical lowerCamelCase name.

• Canonical argument names are lowerCamelCase, the spelling the CLI's --flag-name produces; history.open's newTab, palette.installCLI's cmuxNext, and the in-process tab.moveToNewSplit's keepFocus are renamed.
• The router still folds case, -, and _, so old spellings like prompt-id and prompt_id keep resolving for a release.
• A Swift contract test, named so check-action-surfaces.sh runs it on every catalog change, keeps the export current and checks the router's folding.
• Three renamed arguments were unreachable from cmux; the promptId drift itself was already fixed.