feat(desktop): composer model/mode pills, and the three switches that never worked (R6)

[physercoe]

Closes the R6 wedge of docs/plans/desktop-companion-vision-parity.md. W4 now has only R5 left.

What the director gets

Two pills beside the context ring, in the composer's own row — these are questions asked while typing ("which model is about to answer this?"), not facts looked up in a details panel.

• An agent that advertises its choices (the ACP engines) gets a menu.
• claude, which advertises none, gets a text entry taking an alias or a full model name.
• A switch on the respawn route restarts the agent. The pill previews that and asks first (IAA) instead of doing it and letting you find out.
• A pill that cannot change anything is shown greyed with the reason, not hidden. Mobile's picker hides whenever nothing is advertised, which on a claude session means no model indicator at all — "cannot be changed" and "unknown" are different facts.

Building the consumer measured the producer

Three of the four (family, field) pairs the Companion drives could never have switched anything:

family	field	flag the table wants	reality
claude-code	model	--model	in every claude template's cmd — works
claude-code	mode	--permission-mode	real flag (2.1.220: acceptEdits|auto|bypassPermissions|manual|dontAsk|plan), in no template
codex	model	--model	codex app-server, the M2 argv, accepts none
codex	mode	--approval-policy	not a codex flag — 0.147.0: "unexpected argument … a similar argument exists: --approve-for-me"; the real one is -a, --ask-for-approval

respawn rewrites a flag that must already be in backend.cmd, so the last three answered a 422 reading "pick a fresh template that exposes it" — advice pointing at a template that cannot exist.

Root cause: one routing token answered for two independent capabilities. Families now declare runtime_switch_fields: {mode, model} alongside the route; the hub checks it before routing; GET /agent-families publishes it so the client hides a control rather than discovering the refusal from an error.

This is not the agents.kind defect fixed in df24415c — that gate matched no family at all. This one matched the right family and asked it a question the data could not express.

Two deliberate non-fixes

• Claude's mode pill is read-only on purpose. Shipping a template with --permission-mode is necessary but not sufficient: L3a measured that --permission-mode plan does not stop Bash under --print (claudewire.test.ts:56), so an M2 pill offering plan would name a boundary the engine does not enforce.
• Codex has a real path that is not respawn — thread/start.config takes a map of config overrides (measured in L4c), as does -c model=…. Driver work, filed as i18n: localize team / profile switcher menu (#236) #243. Flipping the registry bit lights the pill up with no UI change.

Verification

• 10 new state tests, both mutation-checked: same-event list capture (the pre-W7c bug mobile hit) and a route-only gate each fail them.
• The Go case set separates the mask from the route — every claude/codex row routes respawn, so a mask that mirrored the route would have passed; (claude-code, model)=true vs (claude-code, mode)=false is the separating input. Mutation-verified.
• go test ./internal/server ./internal/hostrunner ./internal/agentfamilies ✅ (the schema-coverage guard caught the undeclared field; schema updated)
• desktop frontend node --test: 886 pass, 0 fail · electron shell: 715 pass, 0 fail, 6 skipped
• tsc --noEmit ✅ · full vite build ✅ · token ratchet clean, no phantom tokens (five of my first-draft tokens did not exist)
• CI's whole lint set ✅ including lint-openapi.sh (openapi.yaml updated for the new field + the second gate)

Known gap — #242

A respawn mints a new agent id. SessionsPanel follows it (it keys the transcript on session:agent from the digest's current_agent_id, and this PR invalidates those caches). FocusRegion and ProjectBoard mount a fixed id and stay pointed at the terminated agent — the same exposure the pause/stop lifecycle actions already have. Filed rather than half-built here.

🤖 Generated with Claude Code