Queue & Approval

The queue and approval layer is where prompts wait, get reviewed, and become work. This page catalogs the surfaces and tools involved.

Prompt Queue

Found in the Pipeline panel; new prompts via New Prompt (Shift+N). A per-project SQLite-backed queue (~/.orbit/queue.db) where prompts wait, one at a time, until you approve them. Prompts carry complexity: or model: routing tags and claim a unique per-project number at insert.

MCP tools: orbit_queue_prompt, orbit_queue_list, orbit_cancel_prompt.

Approval gate & review

Found on the Pipeline approval cards and under Settings → Workflow / Model Tiers → Prompt Review. Nothing runs until approved. Each complexity tier can auto-review (Gemini Flash-Lite), show a manual reminder, or skip, with optional Deep Review (Opus) and a high-complexity review card before Approve. Orbit records an approval receipt for the exact queued work at the moment you approve it, and keeps held prompts visible for one-click Approve & run; a reviewer’s suggested complexity bump can be applied directly from the review card.

Pre-check warning chips

On each card awaiting approval, a synchronous heuristic pre-check tags risks with amber chips — large prompt, install commands, multi-part, wide file scope, mid-run input — without blocking approval.

Waiting-prompt dependencies & pre-approval

On Pipeline waiting cards. depends_on: holds a prompt as ⏸ waiting until its dependency ships — including a dependency in a different project, referenced as slug#number. Waiting cards can be pre-approved (green “Pre-approved ✓” with Undo) so they auto-run the moment the dependency clears. Dependency placement is durable: it survives queue-row pruning and restarts rather than being recomputed from a snapshot. Resolution always uses durable shipped evidence; if that evidence can’t be confirmed, the prompt fails safe into Waiting with a manual-review note in Needs You rather than guessing.

Pause-for-input (NEEDS_INPUT)

A running prompt can pause to ask a question; the card turns amber with the question and a response box. Answering starts a continuation run carrying the answer forward, and the original card is marked “Answered — continued as #N.” A parked question can also be dismissed without answering via Dismiss (orbit_cancel_prompt), which tears down the session and PID lock cleanly. Orbit distinguishes real agent questions from documentation examples.

Run Diary

The agent interaction sidebar for a running or completed prompt gives it an append-only diary and feedback channel — send direct human input to steer the active agent while it works.

For terminal or side-project work that never enters the queue, register a diary yourself: node scripts/register-diary.mjs --project <slug> --run-id <id>, or the MCP tool below. Orbit returns the run ID, the project-relative diary and feedback paths, and the complete instruction block to paste into that agent’s context. Registration uses the project’s configured diary.path; re-registering an existing run reports already-exists and leaves its files untouched.

MCP tool: orbit_register_diary.

Auto Validation

On the Completions tab / focus rail. After completion, a lightweight pass checks the commit diff for ghost ships or unrelated file changes and labels the prompt Validated (Auto), Ghost Ship, Wrong Files, or Auto Skipped, while preserving whatever verdict the run actually shipped with. Exact operator-authored verification commands run against the isolated worktree and their bounded evidence is kept with the completion; prose-only checks are labeled operator-needed rather than silently marked passed, and a mandatory verification step that got skipped is surfaced for review instead of changing the recorded verdict on its own.

Queue MCP status snapshots

orbit_queue_prompt returns a nullable status_snapshot (last completion, active rows, project code_status) so a client can queue and immediately see state in one call.

Stale-stash / pre-pull recovery

Before dequeue, Orbit scans git diff --check, runs a guarded pre-prompt pull/stash, and on conflict pauses the project queue with a banner naming the project and affected files until you re-scan. Surfaces on a Pipeline banner and under Settings → Queue & Sessions.