Voice command "next" — switch to the agent that wants you, without touching the screen

[serge-ivo]

The ask

Speaking to one agent, say a command word — "next" — and be moved to the next agent that wants
me, without touching the screen. Hands-free means hands-free; today switching agents requires
stopping, looking, and clicking.

Why it belongs in the voice layer that already exists

The vocabulary is a small closed set in packages/sdk/src/voice/convo.ts:106:

export type VoiceCommand = "repeat" | "mute" | "unmute" | "exit";

Each has a per-language phrase table (REPEAT_BY_LANG, MUTE_BY_LANG, UNMUTE_BY_LANG,
EXIT_BY_LANG), per-instance overrides (VoiceCommandWords, Settings → Voice), a
commandsEnabled toggle, and matchVoiceCommand / splitTrailingCommand already handle
whole-utterance vs trailing-command matching in any script.

So "next" is a fifth entry in that table plus a handler — not new machinery. It should get the
same treatment as the others: a NEXT_BY_LANG table, a custom-word override, and the existing
"only fires as a whole utterance, or trailing after a real message" rule so "what's next?" is
never hijacked.

Which agent is "next"

The ordering the request describes, in priority:

1. Wants your input. The platform already models this — needs_human is a first-class board
   status (lib/agent-capabilities.ts:118, rendered as the amber "Needs you" column in
   BoardTab.tsx:20). Also: a finished loop run whose result you have not seen, and an ask-and-hold
   needs_input handoff.
2. Last engaged before the current one — a back-and-forth between two agents should feel like
   toggling, not cycling the whole roster.
3. Next in queue — remaining instances in a stable order, so repeated "next" walks the set
   without repeating.

/v1/dashboard already aggregates cross-instance state and is the natural place to resolve this in
one call, rather than the client polling every instance.

Behaviour worth pinning down

• Say who you switched to, out loud. In hands-free the user is not looking; a silent switch
  means the next thing they say goes to an agent they did not know they were talking to. This is
  the one requirement that makes the feature safe.
• Nothing waiting → say so and stay put, rather than cycling to an arbitrary agent.
• The current agent's turn should finish or be cleanly abandoned before switching — not left
  half-spoken (see the mid-dictation loss class, Voice transcription lost when agent message arrives mid-dictation #175).
• Respect commandsEnabled; a user who has turned voice commands off should not have "next"
  silently steer them.

Verification

• "next" in hands-free moves to a needs_human agent and announces which one.
• With two agents in conversation, "next" alternates rather than cycling all four.
• With nothing waiting, it says so and does not move.
• "What's next for this repo?" is treated as a message, never as the command.

[serge-ivo]

Self-critique: the ordering is over-specified

I proposed a three-tier rule — needs-input, then last-engaged-before-current, then queue order. That
is three stacked heuristics, which is the same shape I criticised elsewhere today (a technicality
level guessed from whether an agent has repos; tmux asserted in prose). Worth not repeating it in
a new feature.

Tier 2 is the weak one. "Last engaged before current" only helps a two-agent ping-pong; with
four subordinates it makes "next" unpredictable — the same word does different things depending on
history the user cannot see. A command whose behaviour you have to model in your head is worse than
one that is boring.

Suggested simpler rule: agents with something waiting for you, most-recently-waiting first. If
nothing is waiting, say so and stay put. That is one rule, explainable in a sentence, and it
degrades honestly.

If ping-pong turns out to matter in use, it is a separate word ("back") rather than a hidden
second meaning for "next".