[Ark0N]

Claude Code has an experimental advisor tool (docs): the session's main model consults a second, stronger model at decision points, before committing to an approach, when an error keeps coming back, and before it declares a task done. Claude decides when to call it. A typical setup is a Sonnet main model with an Opus or Fable advisor, which costs less than running the stronger model the whole time.

Until now Codeman had no way to turn it on for a session. This PR adds it as a per-session setting with an App Settings default, and lets agents using the codeman skill give their workers one.

What changes

Sessions and API

• New advisorModel field on POST /api/sessions, POST /api/quick-start and POST /api/ralph-loop/start. Accepted values: fable, opus, sonnet, or a full model id in one of those families (claude-opus-5-5). Haiku is refused because it can call an advisor but can never act as one.
• Stored on the session and persisted to state.json, so respawns, boot restore and reboot restore all keep it.
• Remote and docker quick-starts refuse it with a 400, exactly as they already refuse effort (neither crosses ssh or into the container).

UI

• App Settings, Models, a new Advisor segment under Thinking effort: Default / Sonnet / Opus / Fable. Synced across devices as claudeAdvisorModel.
• Run, resuming a past conversation and the Ralph wizard all send it. Default sends nothing, so whatever the user picked with /advisor in Claude Code stays in charge.

Codeman skill

• spawn_worker and spawn_workers build the quick-start body themselves, so an agent could not give a worker an advisor without hand-rolling the call and losing the readiness checks. Setting CODEMAN_WORKER_ADVISOR=opus now adds it for every claude worker they start; other modes ignore it.
• A bad value fails the spawn with the server's own error. An older server silently drops the unknown field, so spawn_worker reads it back and warns on stderr instead of handing back a worker without the advisor it asked for.
• The preamble changed, so CODEMAN_PREAMBLE is bumped to 1.33.4 (stale cached copies get rewritten). SKILL.md's heredoc and the plugin mirror are synced.

Why --settings and not --advisor

Claude Code accepts the advisor both as a --advisor <model> flag and as an advisorModel settings key. They fail differently (measured on 2.1.289):

	claude --advisor haiku	claude --settings '{"advisorModel":"haiku"}'
result	Error: The model "haiku" cannot be used as an advisor., exit 1	starts normally

The flag also exits for a Fable advisor before the account's usage-credit consent, or a model outside an org's availableModels. In Codeman that would mean a dead pane on every spawn and respawn. The settings key degrades instead: Claude just doesn't attach an advisor it can't use. So the value rides the launch's one --settings JSON object, merged with ultracode and the plan-usage statusLine exporter (Claude Code reads only one --settings flag). A launch without an advisor produces a byte-identical command to before. Both launch paths are covered: the tmux template and the direct-PTY fallback.

It stays a soft default: /advisor switches it or turns it off inside the running session.

Testing

• New test/advisor-model.test.ts: the allowlist (including quote and injection attempts), the merged --settings object read back through a real shell, the resume variant, the direct-PTY args, the unchanged command without an advisor, persistence, and all four schemas. test/agent-skill.test.ts and test/plugin-manifest.test.ts pass with the bumped preamble.
• Full npm test gate: 441 files, 8531 tests passed. Typecheck, lint, format and the frontend checks are clean.
• End to end on an isolated instance (CODEMAN_INSTANCE, its own tmux socket and cases dir), with real Claude Code 2.1.289:
  • The settings segment saves, survives a reload, and Run creates a session with advisorModel: "opus".
  • The pane's claude process started with --settings {"advisorModel":"opus","statusLine":...}, and Claude's own /advisor picker in that pane showed Opus 5.5 ✔.
  • Killing that claude and restarting the server: boot restore found the dead pane, respawned it, and the new process still carried the advisor.
  • The real preamble.sh: CODEMAN_WORKER_ADVISOR=fable spawn_workers adv-a adv-b gave both workers fable, a worker spawned without the variable got none, and CODEMAN_WORKER_ADVISOR=haiku spawn_worker failed cleanly with the INVALID_INPUT message. The old-server warning was checked against a 1.33.3 server with a read-only GET.

Notes

• The advisor needs the Anthropic API (not Bedrock or Vertex) and uses extra tokens when Claude consults it. An advisor ranked below the session's main model is accepted but not attached by Claude Code, so on an Opus 5.5 session only Opus or Fable do anything.
• No changeset here; it goes in with the release.
• Found along the way, not fixed here: when two sessions are created in the same millisecond while statusline-exporter.sh needs rewriting (a fresh data dir, or after a release that changes it), both writers use the same temp name (pid.Date.now().tmp), one rename fails with ENOENT, and that session silently falls back from tmux to a direct PTY. Seen once during the spawn_workers run above; the fix is a random temp suffix like the skill writer in the same file already uses. Worth its own small PR.