galaxy/specs/gh-11912/TECH.md

Queue terminal commands alongside prompts — Tech Spec

See specs/gh-11912/PRODUCT.md for user-visible behavior. This layers command support onto the v2 queued-prompts machinery from specs/REMOTE-1543/ and specs/APP-4562/.

Context

The queued-prompts queue is an app-wide singleton, QueuedQueryModel (app/src/ai/blocklist/queued_query.rs), keyed by AIConversationId. Each conversation has a ConversationQueueState { queue: Vec<QueuedQuery>, editing, queue_next_prompt_override, command_in_flight }. A QueuedQuery carries id, text, origin: QueuedQueryOrigin, and a kind enum that is either a prompt with attachments or a command without attachments (app/src/ai/blocklist/queued_query.rs:47). Draining is mediated by peek_autofire → AutofireAction → remove_fired_row so the send path can read a row's attachments before the row is removed (app/src/ai/blocklist/queued_query.rs:439, app/src/ai/blocklist/queued_query.rs:468).

Submit/queue flow:

• The enter handler tries queue gates before executing: maybe_queue_input_for_in_progress_conversation then maybe_queue_input_during_cloud_setup, then slash-command handling and the shell-execution fallback (app/src/terminal/input.rs:12871-12874, shell execution at app/src/terminal/input.rs:13096).
• Before #11912, shell mode made maybe_queue_input_for_in_progress_conversation return false, so a shell command fell through to try_execute_command and cancelled any in-progress conversation. The implemented gate now computes is_command from the input mode (app/src/terminal/input.rs:13552) and allows shell command rows under the QueuedPromptsV2 gate.
• try_execute_command (app/src/terminal/input.rs:6855) routes correctly per pane: for a shared-session viewer/executor (cloud-mode pane) it sends the command to the sharer via try_execute_command_on_behalf_of_shared_session_participant; otherwise it runs locally via try_execute_command_from_source.

Drain + submit:

• TerminalView::handle_finished_conversation (app/src/terminal/view.rs:4804) → drain_queued_prompts (app/src/terminal/view.rs:5301). The clean path peeks the head and, for AutofireAction::Submit, calls Input::submit_queued_prompt_for_active_pane (app/src/terminal/input.rs:13453, routes cloud-followup / shared-session-viewer / local). The non-clean path (Error|Cancelled) restores the head into the editor via pop_front.
• Local finish detection: handle_ai_controller_event, FinishedReceivingOutput arm (app/src/terminal/view.rs:5139). It already defers finishing while has_active_subagent() is true (app/src/terminal/view.rs:5149, app/src/ai/agent/conversation.rs:3079) — this is the LRC guard.
• Cloud finish detection: handle_ai_history_model_event, UpdatedConversationStatus arm (app/src/terminal/view.rs:6163), gated on QueuedPromptsV2 + is_ambient_agent_session, draining only on a transition to a terminal status.

Command completion signals (the new draining inputs) — local and shared-session are distinct and must both be handled:

• Local: ModelEvent::AfterBlockCompleted is handled in TerminalView (app/src/terminal/view.rs:12020); the completed block is block_type, and BlockType::User(UserBlockCompleted { serialized_block, was_part_of_agent_interaction, .. }) exposes success via serialized_block.exit_code.was_successful() (app/src/terminal/view.rs:12123). Agent-executed commands are BlockType::User with was_part_of_agent_interaction == true.
• Shared session / cloud: the sharer emits OrderedTerminalEventType::CommandExecutionFinished { next_block_id } from command_finished (app/src/terminal/model/terminal_model.rs:2829) on every command completion. The viewer event loop receives it and advances queued commands through TerminalView::on_queued_command_finished (app/src/terminal/shared_session/viewer/event_loop.rs:292). This is the authoritative remote-command-finished signal for a cloud/viewer pane — it does not depend on the indirect, byte-parse-driven block completion on the viewer. (The viewer already keys its own per-command cleanup of pending_command_execution_request off the synced block completion in Input::handle_block_completed_event, app/src/terminal/input.rs:14472.)

Panel: app/src/terminal/view/queued_prompts_panel.rs renders each row; the row render is where the ! prefix is added.

Feature flag: FeatureFlag::QueuedPromptsV2 (already wired).

Proposed changes

1. Model: a queued item is a prompt or a command (queued_query.rs)

Replace the flat attachments field with a kind enum so attachments are structurally impossible on a command:

pub enum QueuedQueryKind {
    /// An agent prompt; may carry image/file attachments captured from the input.
    Prompt { attachments: Vec<PendingAttachment> },
    /// A shell command run in the terminal / via the shared session. Cannot hold attachments.
    Command,
}

• QueuedQuery keeps the shared id, text, origin and gains kind: QueuedQueryKind. text stays shared (both kinds have a string); only attachments move into the Prompt variant, so a Command has nowhere to put them. Use Vec (not Option<Vec>): an empty vec already means "no attachments", so Option would add a redundant None-vs-empty state.
• Accessors: is_command() = matches!(self.kind, QueuedQueryKind::Command); attachments() returns the Prompt variant's slice or &[] for a Command. Constructors: keep new / new_with_attachments (build Prompt), add new_command(text) (builds Command). origin stays telemetry-only; firing branches on kind, not origin.
• Commands are normal mutable rows: is_locked() stays false for them, so reorder/edit/delete/pop_front behave exactly as for prompts.
• Extend the drain action: add AutofireAction::ExecuteCommand { query_id, command }. peek_autofire (app/src/ai/blocklist/queued_query.rs:439) returns ExecuteCommand for a Command head, and Submit / PopFromEditMode otherwise.
• Track the in-flight command on ConversationQueueState: add command_in_flight: bool with arm_command_in_flight, clear_command_in_flight, and has_command_in_flight(conversation_id) -> bool (app/src/ai/blocklist/queued_query.rs:314). Storing this on the singleton lets the Input gate read it and both TerminalView and the viewer event loop set/clear it. Clear it in drop_conversation so lifecycle cleanup (app/src/ai/blocklist/queued_query.rs:286) resets it.

2. Queue gate: allow shell submissions to queue (input.rs)

In maybe_queue_input_for_in_progress_conversation (app/src/terminal/input.rs:13541):

• Remove the !is_ai_input_enabled() early return. Compute let is_command = !self.ai_input_model.as_ref(ctx).is_ai_input_enabled(); up front.
• Extend the in-progress predicate so the queue stays active while a command runs (PRODUCT §14): queue when the conversation is in-progress/blocked or QueuedQueryModel::as_ref(ctx).has_command_in_flight(conversation_id).
• The is_queue_next_prompt_enabled / summarizing gate is unchanged: queuing is allowed when the auto-queue toggle is on, or when the conversation is summarizing under QueuedPromptsV2 (PRODUCT §2, §7).
• The /queue-argument unwrap only applies in AI mode (a shell command won't match commands::QUEUE); skip it for is_command.
• Append QueuedQuery::new_command(prompt) when is_command, else the existing prompt row. Do not take pending attachments for commands.

Because the enter handler already calls this gate before the shell-execution branch (app/src/terminal/input.rs:12871), a queued command never reaches try_execute_command, so the interrupt-the-agent path is bypassed. No change to maybe_queue_input_during_cloud_setup (queuing-while-running is the in-progress gate, not the setup gate).

3. Drain dispatch: execute commands (view.rs, input.rs)

In drain_queued_prompts (app/src/terminal/view.rs:5301), FinishReason::Complete arm, handle the new action:

• AutofireAction::ExecuteCommand { query_id, command }: call remove_fired_row (row disappears immediately, PRODUCT §10), then dispatch via Input::execute_queued_command(command, conversation_id, ctx). That helper uses a queued-command execution source (local QueuedCommand, or shared-session preserve_input) so terminal routing is reused without treating the current editor buffer as the submitted command. It arms command_in_flight only after dispatch starts. Do not peek/drain the next item here — the next item fires on block completion (§4). If dispatch returns false (cannot execute, e.g. precmd not yet received), restore command into the editor in shell mode if the editor is empty, matching the non-clean restore, so the queue never wedges.
• Submit arm unchanged. PopFromEditMode now carries is_command (set from first.is_command() in peek_autofire): when restoring a command's text into an empty input, force shell mode via Input::set_input_mode_terminal(true, ctx) and skip the attachment restore (commands have none), so an edited command that the clean drain pops into the input stays a command instead of being submitted as an agent prompt (PRODUCT §5).

The non-clean arm (Error|Cancelled) restores the head via pop_front + replace_buffer_content(query.text()); when query.is_command(), it also forces shell mode via set_input_mode_terminal(false, ctx) and skips the attachment restore, so a restored command stays a command (PRODUCT §17).

4. Command-finished trigger advances the queue (view.rs, viewer/event_loop.rs)

Add one shared entry point on TerminalView, on_queued_command_finished(&mut self, ctx): find the conversation owned by this terminal view whose queue has command_in_flight armed, call clear_command_in_flight(conv), then self.drain_queued_prompts(conv, FinishReason::Complete, ctx). Resolve the armed owner rather than the pane's currently active conversation so a conversation switch while the command runs does not wedge the original queue. Passing Complete regardless of exit status implements PRODUCT §12; going through drain_queued_prompts (not handle_finished_conversation) avoids re-running conversation-finished callbacks. Fire it from both command-finished sources so local and cloud panes are each covered by their authoritative signal:

• Local — in the ModelEvent::AfterBlockCompleted handler (app/src/terminal/view.rs:12020), after the existing pending_command_queue handling, when block_type is BlockType::User(b) with !b.was_part_of_agent_interaction, call self.on_queued_command_finished(ctx) (app/src/terminal/view.rs:12166).
• Shared session / cloud — handle OrderedTerminalEventType::CommandExecutionFinished in the viewer event loop (app/src/terminal/shared_session/viewer/event_loop.rs:292): self.terminal_view.upgrade(ctx) then view.update(.., |view, ctx| view.on_queued_command_finished(ctx)).
• Both are gated on the armed command_in_flight flag, and on_queued_command_finished clears it before draining, so it is naturally idempotent: if a viewer happens to observe both a synced AfterBlockCompleted and a CommandExecutionFinished, only the first advances the queue (the second sees no armed flag and no-ops). The armed-only gate also keeps agent-executed command blocks / LRC snapshots from advancing the queue — they complete while the flag is unarmed, since the agent is idle whenever a queued command is in flight (PRODUCT §16). The same armed flag suppresses editor freeze/clear behavior on queued command start and completion, preserving any draft the user is composing. When the next item is a prompt, submit_queued_prompt_for_active_pane routes it to the cloud-followup / local path as today.

5. LRC handling (no code change, documented)

For queued prompts that trigger an agent LRC, the existing has_active_subagent() guard in the FinishedReceivingOutput arm (app/src/terminal/view.rs:5149) already defers handle_finished_conversation until the subagent/LRC turn truly ends (PRODUCT §15); the cloud UpdatedConversationStatus path only drains on a terminal status, which the agent won't report mid-LRC. The new command-finished trigger (§4) cannot fire during an LRC because it is armed only while a queued command is in flight, i.e. when the agent is idle. No new code is required, but this reasoning is the reason the trigger is gated on the armed flag rather than on every User block completion.

6. Panel: blue ! prefix on command rows (queued_prompts_panel.rs)

In the row render, when query.is_command(), render a leading ! glyph before the preview text using the same blue color token the input uses for the shell-mode ! prefix (locate the shell-prefix color in the input/editor styling and reuse the token rather than hard-coding a color). All other affordances (drag handle, edit/delete buttons, collapse) are unchanged (PRODUCT §4, §5).

End-to-end flow (queue = [prompt A, command B, prompt C])

flowchart LR
  A["A submitted to agent"] --> Afin["agent turn finishes (FinishedReceivingOutput / UpdatedConversationStatus)"]
  Afin --> DB["drain_queued_prompts → ExecuteCommand B"]
  DB --> Bexec["Input::execute_queued_command → preserve-input command source; arm command_in_flight"]
  Bexec --> Bdone["command finished: AfterBlockCompleted (local) OR CommandExecutionFinished (cloud)"]
  Bdone --> DC["on_queued_command_finished: clear flag → drain → Submit C"]
  DC --> Cexec["submit_queued_prompt_for_active_pane (agent / cloud followup)"]

Testing and validation

Current automated coverage maps to PRODUCT.md invariants as follows; follow repo test conventions (*_tests.rs included via #[path]).

• §1 (flag) — app/src/terminal/input_tests.rs: shell_submission_is_not_queued_when_v2_disabled asserts shell submissions do not become command rows when QueuedPromptsV2 is off.
• §2, §7, §14 (gating) — app/src/terminal/input_tests.rs: shell_submission_queues_as_command_row_when_gated_under_v2 asserts shell submissions queue as Command rows while has_command_in_flight keeps the queue active even though the agent is idle.
• §3–§5 (model) — app/src/ai/blocklist/queued_query_tests.rs: command rows are structurally commands with empty attachments; peek_autofire yields ExecuteCommand for a command head; edited command heads pop with is_command; command rows are reorderable/editable/deletable; arm/clear/has_command_in_flight; conversation deletion clears in-flight state.
• §5, §17 (restore keeps command kind) — app/src/terminal/view/queued_prompts_tests.rs and app/src/terminal/input_tests.rs: clean drain of an edited command, non-clean drain of a command, and delete-row restore all put the command text back in shell mode.
• §9, §10, §14, §19 (dispatch and draft preservation) — app/src/terminal/input_tests.rs, app/src/terminal/shared_session/viewer/event_loop_tests.rs, and app/src/terminal/shared_session/viewer/terminal_manager_tests.rs: send-now command dispatch removes the row, arms in-flight state, and preserves drafts; queued command completion preserves local drafts; shared-session CommandExecutionStarted preserves drafts while a queued command is armed; CommandExecutionFinished clears in-flight state idempotently even after conversation switches; command request failure clears in-flight state.
• §18 (lifecycle) — app/src/ai/blocklist/queued_query_tests.rs: conversation deletion and terminal-view clearing drop queued state, including in-flight command state.
• Behavior covered by implementation review rather than current focused tests — app/src/terminal/view.rs: the clean drain command-head path removes the row, dispatches execute_queued_command, and does not drain the next item until completion; on_queued_command_finished passes FinishReason::Complete regardless of exit status; the local completion hook filters was_part_of_agent_interaction; FinishedReceivingOutput still uses the has_active_subagent() guard for LRC turns.
• Full ./script/format and cargo clippy (per WARP.md) before PR; run the focused queue test suites (queued_query, queued_prompts, input/view tests). Do not run the app to test.

Parallelization

Single workstream. The change threads one set of shared types (QueuedQueryKind, AutofireAction, command_in_flight) through the model, the input gate, the view drain, both command-finished triggers, and the panel render; every edit depends on the model change landing first, and the files (queued_query.rs, input.rs, view.rs, shared_session/viewer/event_loop.rs, queued_prompts_panel.rs) overlap heavily with the in-flight changes. Splitting across child agents would create merge churn on the same files without reducing wall-clock time, so it is implemented directly.

Risks and mitigations

• Queue wedges if a command never starts: only arm command_in_flight when try_execute_command returns true; on false, clear and restore text (§3).
• Double-drain: the command-finished trigger is armed only during command-in-flight (agent idle), and the conversation-finish paths won't re-fire (the conversation already reached a terminal status before the command ran).
• Spurious advance from agent command blocks: filtered by !was_part_of_agent_interaction (local) plus the armed flag, which is only set while the agent is idle (§4, §16).
• Viewer completion reliability: cloud panes advance on the explicit OrderedTerminalEventType::CommandExecutionFinished event rather than the indirect, byte-parse-driven block completion on the viewer. If both a synced AfterBlockCompleted and a CommandExecutionFinished reach a viewer, the armed-flag clear in on_queued_command_finished dedupes them; validated by the §19 cloud test.
• origin vs kind confusion: origin stays telemetry-only; all firing decisions branch on kind to avoid conflating source with type.