Cycle agent terminals from keyboard and Stream Deck — next/previous in the Codev sidebar Agents order

[amrmelsayed]

Gap

Keyboard navigation across agent terminals is asymmetric. The architect terminal has a direct binding (codev.openArchitectTerminal, Cmd+K A), but builders only have the quick-pick (codev.openBuilderTerminal) with no default keybinding — reaching a specific builder is palette → type → pick every time. VS Code's native Ctrl+Tab MRU switcher helps only for recently-visited terminals, interleaves them with file tabs, and has no stable order. And from the Stream Deck there is no way to move between agent terminals at all.

In a workspace with several architects and several builders, "go to the next agent" is a constant motion with no single keystroke or key press.

Proposed

Two commands:

• codev.focusNextAgentTerminal
• codev.focusPreviousAgentTerminal

Ordering rule — mirror the sidebar, exactly. The cycle order is the current rendered order of the Codev sidebar's Agents section, flattened top-to-bottom, wrap-around. The Agents view is the visual cue the user already has; navigation that matches it is predictable by construction. This means the order is grouping-aware: when the user cycles the view's grouping (Group by Architect / Group by Stage / by Area), the cycle order follows the new rendering. Implementation note: derive the roster from the same data/order the Agents tree provider renders — one source of truth, not a parallel ordering that can drift (see the shared-function lesson from #818 in lessons-learned).

Semantics:

• Cycling opens the terminal tab if it isn't open (same as clicking the sidebar row), so the roster is every live agent in the view, not just open tabs.
• Non-agent editor tabs are never part of the cycle; the dev PTY tab (Codev: <name> (dev)) is not an agent and stays out.
• No-op with a status-bar hint when the workspace has zero or one agent terminals.
• The contextual bottom panel (vscode: contextual bottom panel that adapts to active editor (mode resolver + Attention fallback) #1049) already follows terminal focus, so cycling terminals cycles the panel's context for free.

Stream Deck integration

Expose the same motion on the deck, through the established relay path (deck action → Tower → command-relay → the two commands above) — the plugin presses commands, no new protocol surface:

• Dial rotation is the natural mapping (rotate = next/previous agent, matching the sidebar top-to-bottom; press could open/focus the current target if a selection-preview treatment is chosen). The review dial's vocabulary (vscode: review-flag gestures must prompt for comment prose (native inline thread, Submit/Cancel) — remove the promptless deck default #1552: open | submit | noop) is untouched — this is a separate dial or a deck-profile page decision.
• Key-pair fallback (next/prev keys) if a dial isn't available in the active profile.
• The deck face should show which agent is current (builder id / architect name), reusing the existing face-rendering patterns in apps/streamdeck/src/face.ts.
• Ordering must come from the same sidebar-order source the VS Code commands use — the deck must never invent a second ordering.

Decision points for the implementer

1. Default VS Code keybindings: pick a chord pair consistent with the existing Cmd+K family or the Ctrl+Alt bracket pair used by diff navigation — verify candidates are unbound in VS Code defaults (both cmd+k x and cmd+k cmd+x variants) before shipping. Palette-only (user binds their own) is the fallback if no clean chord survives verification.
2. Deck surface: dedicated dial vs key pair vs profile-page placement — decide against the current deck profile layout (Stream Deck: size the Row-1 builder window from placed keys — a builder can be selected while shown on none #1465-era sizing constraints).

Relation

• codev.openBuilderTerminal (quick-pick) remains the right tool for targeted jumps; this is the sequential motion.
• Agents-view grouping commands (codev.agentsCycleGroupFromArea / codev.agentsCycleGroupFromArchitect) define the orders this feature mirrors.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).