feat(orchestration): accept Muse model and effort for supervised workers

[nwparker]

ELI5

Orca orchestration can now start Muse Code workers on a chosen Muse model and reasoning effort, the same way it already could for Claude, Codex and Cursor. That lets a coordinator hand tasks to Muse Spark workers.

What Changed

• Before: orca orchestration worker-start --agent muse was already accepted and launched Muse's default model. Adding --model failed with "does not support launch-time model selection". For opencode, --model failed with the same generic error.
• After:
  • worker-start --agent muse --model muse-spark-1.3 --effort minimal launches muse --trust-workspace --model muse-spark-1.3 --reasoning-effort minimal.
  • --effort accepts minimal, low, medium, high, xhigh, max or ultra.
  • For opencode, --model is still refused, but the error now tells you to leave out --model and use the model from opencode's own config.
• How it works: a Muse session-option catalog (src/shared/agent-session-option-catalog-muse.ts) maps the worker's model and effort to Muse's launch flags, the same way Antigravity's does. It lists no models because Muse model ids depend on the account and Muse has no command that lists them, so no model picker appears in the UI.
• Docs: worker-start --help now lists the valid --agent ids and which agents accept --model. The orchestration skill guide and the docs site page are updated too.

Why

Issue #19823 asks for Muse Spark workers under Orca orchestration. Muse is now a first-class agent (#22216): Orca knows when it's ready and gets its working/waiting/done status from hooks, and workers settle through worker_done whatever the agent is. Once the host accepts the model and effort, the whole flow works.

opencode --model isn't enabled. The installed opencode 2.x terminal UI exits with Unrecognized flag: --model; only opencode run accepts -m. Passing it through would break every opencode 2 user. Picking an opencode model would have to go through its OPENCODE_CONFIG_CONTENT environment variable, and worker launch preferences can't set environment variables today, so that's left as a follow-up.

Linked Issue

Fixes #19823 for Muse. The issue's opencode + Muse Spark case can use --agent muse directly; opencode --model is left out for the reasons above.

Visual Proof

Before (main): worker-start --agent muse --model muse-spark-1.3 is rejected, so Muse workers always run the account default model:

Agent muse does not support launch-time model selection.

After: the same command launches Muse with the requested model and effort. The worker's footer reads muse-spark-1.3 · minimal, it created hello.txt and it sent worker_done, all in a fresh app:

Launch receipt:

"state": "ready", "stage": "input_accepted",
"launch": {
  "requested": {"agent": "muse", "model": "muse-spark-1.3", "effort": "minimal"},
  "effective": {"agent": "muse", "model": "muse-spark-1.3", "effort": "minimal"}
}

opencode now explains how to get a different model:

Agent opencode does not support launch-time model selection. Omit --model to run the model from its own config.

(That screenshot was taken with #22384 also applied. Without it, the very first worker in a freshly started app can hit a readiness timeout.)

Testing

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

• Manual test (macOS, Muse 1.3.0): I ran a dev build with a coordinator terminal and ran worker-start --task <id> --agent muse --model muse-spark-1.3 --effort minimal.

  • Muse's footer showed muse-spark-1.3 · minimal.
  • The task prompt arrived once Muse was ready.
  • Orca's status went working → done.
  • Muse ran orca orchestration send --type worker_done, and the task became completed.

• opencode: --agent opencode --model x returns the new message and leaves no task behind.

• Automated tests: they cover Muse model/effort pass-through, rejecting an invalid effort, refusing opencode --model, and the Muse launch command, which replaces any --model the user put in their own Muse arguments. The worker, shared, native-chat, CLI spec and skill-guide suites pass, as do tc:node, tc:cli and the changed-code quality gate.

• Found during testing, fixed separately: in a freshly started app, a worker created before any worktree had been opened got no replies to terminal queries, so Muse exited at startup. That's fixed in fix(runtime): answer startup terminal queries for background-created terminals #22384, because it affects every background-created terminal.

AI Disclosure

Anthropic Claude assisted with implementation, validation, and this pull request description.

Review

Follows the per-agent session-option catalog pattern that Antigravity workers use (#21705). The earlier community work for adding worker agents (#16228) was also reviewed.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Mixed versions: nothing sent between client and host changes. The host checks the model, so a host without this change answers --agent muse --model … with its existing "does not support launch-time model selection" error.
• Approval prompts: Muse ran with --yolo, which came from Orca's existing Muse permission setting. Without it, Muse's default approval prompt may stop the worker's worker_done shell command, as it would for any agent in approval mode.
• Not tested:
  • Muse workers on SSH hosts.
  • The release step. worker-release returns release_unknown for Muse workers. The logs show Muse exits about 3 s after its terminal closes, but the daemon kill request times out at 2 s (Request kill timed out after 2000ms) and nothing re-checks after the session exits. That timeout is general, not Muse-specific, and is tracked as a follow-up.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (typecheck and focused suites pass locally; CI covers the rest)

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: caea12b9-14ef-44fd-88be-02440f847170

📥 Commits

Reviewing files that changed from the base of the PR and between 4b263d9 and e7c8595.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: a1d06010-b6a9-4777-92a2-9c1d494de6bd

📥 Commits

Reviewing files that changed from the base of the PR and between b2762bf and 4b263d9.

📒 Files selected for processing (1)

• config/scripts/mobile-web-app-session-terminal-closure.test.mjs

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds and registers a Muse session-option catalog with model and reasoning-effort selections. Tests cover Muse preference handling and reject unsupported effort values and opencode model selection. The unsupported-model error now advises users to run the model from the agent's own configuration. Orchestration specifications and guides document Muse model selection and explain that other agents use their own configured model.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 4b263

Muse model and effort options map to the launch command, and invalid or effort-only requests are rejected. No material merge risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #19823 requires an opencode worker launch path or generic opaque model passthrough, plus valid-agent documentation. The PR documents opencode and adds a native muse catalog with model and …	Add an opencode worker launch path or support generic provider model IDs for opencode. Add automated tests for the supported opencode behavior.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the primary change: adding Muse model and effort support for supervised orchestration workers.
Description check	✅ Passed	The description follows the required template and explains the user-visible behavior, implementation, rationale, linked issue, visual proof, testing, limitations, and checklist status. It also documen…
Out of Scope Changes check	✅ Passed	The Muse option catalog, launch-preference tests, opencode guidance, worker help, orchestration guide, and mobile session-route closure update support issue #19823 or the new Muse launch behavior. No …

Full details: Linked Issues check

Explanation

Issue #19823 requires an opencode worker launch path or generic opaque model passthrough, plus valid-agent documentation. The PR documents opencode and adds a native muse catalog with model and effort pass-through. However, resolveWorkerLaunchPreferences still rejects --model for opencode and directs users to opencode configuration. The new tests verify this rejection. The PR therefore does not provide the requested opencode model support or an opencode-specific launch implementation.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

---

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.}

[pullfrog]

Important

src/shared/agent-session-option-catalog-muse.ts is a new module in the mobile session route's static import graph, so the pinned module count in config/scripts/mobile-web-app-session-terminal-closure.test.mjs is now one short. That job does not run on this PR (it is path-gated to mobile/** and specific config scripts), so it stays green here and fails later on main unless the pin is re-measured and bumped.

Reviewed changes

• Muse launch-preference catalog — new src/shared/agent-session-option-catalog-muse.ts maps --model and --reasoning-effort and is registered in CATALOGS, opting Muse into worker-start model/effort overrides with an empty model seed (no picker) and a shared effort ladder.
• opencode guidance — the refusal in worker-launch-preferences.ts now appends "Omit --model to run the model from its own config."
• Tests — Muse pass-through, invalid-effort rejection, opencode refusal, and the Muse launch command (including replacing a --model the user put in Muse's own arguments).
• Docs and CLI help — orchestration.mdx, the orchestration skill guide (and its generated bundled-skill-guides.ts), and the worker-start spec notes now list Antigravity and Muse.

⚠️ Mobile web app session-route module census is now off by one

The new catalog module is statically imported by agent-session-option-catalog.ts, which the mobile session route reaches through its native-chat and structured-session-options hooks. The closure therefore gains exactly one module, but the pin was not updated. Because the mobile_web_app job is gated on MOBILE_WEB_APP_PREFIXES (which has no src/shared/** entry), this PR never runs the census — the drift lands on main and fails the next time that job runs, exactly as the file's own comment records for #22299.

Technical details

# Mobile web app session-route module census is now off by one

## Affected sites
- `config/scripts/mobile-web-app-session-terminal-closure.test.mjs:416` — `SESSION_ROUTE_MODULES = 4214`; line 482 asserts `modules` has exactly that length.
- `src/shared/agent-session-option-catalog-muse.ts` (new) — statically imported by `src/shared/agent-session-option-catalog.ts:13`.
- `mobile/src/session/use-mobile-native-chat-session-options.ts:10` and `mobile/src/session/use-mobile-structured-agent-options.ts:3` — value-import `getAgentSessionOptionCatalog`, so the catalog and everything it imports are in the session route closure.

## Required outcome
- Re-measure the closure with all postinstall generators run first and bump `SESSION_ROUTE_MODULES` by the measured delta — expected `4214 -> 4215` (`local modules 1028 -> 1029`). The same +1 is what the file records for Antigravity at lines 297-303.

## Suggested approach (optional)
- The module only adds `hasFlag`/`removeAgentArgOption` imports that are already in the closure, so the delta is exactly one. Re-pin and add the convention's short explanatory paragraph. The suite is skipped without `mobile/node_modules/react-native-web`, so it must be run in the `mobile_web_app` job (or locally after `install-mobile-dependencies`).

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[nwparker]

Addressed review feedback:

• pullfrog (mobile session-route census): Valid. Installed mobile deps so the suite actually runs and measured it: the closure is 4215 (the new agent-session-option-catalog-muse.ts is the only joiner). Bumped SESSION_ROUTE_MODULES 4214 -> 4215 with a history note, and merged latest main. I re-ran the test on the merged head, and it passes.
• CodeRabbit linked-issue check (opencode --model pass-through): This is intentionally out of scope. opencode has no launch-time model catalog here, so worker-start still rejects --model for it. The error now tells users to omit --model so opencode uses its own configured model. A generic provider-model pass-through would need its own validation design.
• CodeRabbit docstring coverage: Not changing this. The repo's style is one-line comments only where they aren't obvious (AGENTS.md), and the touched function is already self-describing.

[pullfrog]

✅ No new issues found.

Reviewed changes

• Re-pinned the mobile session-route census — commit 4b263d9ad4 bumps SESSION_ROUTE_MODULES from 4214 to 4215 (local 1028 -> 1029) in config/scripts/mobile-web-app-session-terminal-closure.test.mjs, with the convention's explanatory paragraph, addressing the prior review's finding. The +1 is correct: agent-session-option-catalog-muse.ts only adds imports (agent-cli-flag-detection, agent-session-option-agent-args, agent-session-option-catalog-types) that other catalogs already place in the closure.

The only other commit in the range is a main merge (3734e39938), which introduced no net change to the branch-vs-base diff.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}