# Orca Multi-Agent Workspace & CLI

> Orchestrate parallel AI coding agents across isolated Git worktrees, coordinator-worker task DAGs, inline diff annotations, embedded browser captures, and remote SSH or mobile runtimes.

- **Topic:** [Agent Engineering](https://twelve-pages.com/topics/agent-engineering)
- **Web Edition:** https://twelve-pages.com/guides/agent-engineering/orca-multi-agent-workspace-and-cli
- **Printable 12-Page PDF:** https://twelve-pages.com/guides/agent-engineering/orca-multi-agent-workspace-and-cli/Orca_Multi_Agent_Workspace_and_CLI_Complete_How_To_Guide.pdf (2.3 MB)
- **Version:** v1.0 (Updated 2026-11)
- **Reading Time:** 12 minutes (12 pages)
- **Authorship:** AI-authored under human editorial direction & print QA (https://twelve-pages.com/editorial)
- **Tags:** Isolated Git Worktrees · Parallel CLI Fleet · Task DAG Orchestration · Inline Diff Annotations · Browser & Computer Use · SSH & Mobile Pairing

## Core Takeaways

- **Zero-Collision Worktrees:** Every agent gets its own real Git worktree and branch, letting Claude Code, Codex, OpenCode, and Gemini CLI edit concurrently without conflicts.
- **Supervised DAGs & Handoffs:** Transfer standalone tasks in a single command or run coordinator-worker dependency graphs with durable mailboxes and explicit decision gates.
- **Unified Review & Remote Ops:** Annotate agent diffs line by line, pipe Design Mode DOM captures into prompts, drive background desktop apps, and steer builds from mobile.

## 1. The Orca Mental Model: Worktrees, Fleet & Runtime

Traditional editors assume one human typing in one branch at a time. Orca is an open-source Agent Development Environment (ADE) designed as a mission control room for parallel coding agents you already own.

### Quick Navigation

#### W Isolated Worktree Unit

Orca binds each task to a dedicated Git checkout (`repoId::path`) or native folder context, storing lineage, linked issues, terminals, and browser tabs together.

#### A Bring-Your-Own Agent

Orca bundles zero proprietary models. It wraps your local Claude Code, Codex, OpenCode, Gemini CLI, Cursor, OMP, or Pi binaries using your own subscriptions.

#### R Durable Host Runtime

A background runtime (desktop app or headless `orcad` server) keeps PTY sessions, task mailboxes, and browser pages alive across restarts and SSH links.

### System Architecture: Caller -> Orca Runtime -> Parallel Worktrees & Surfaces

#### Why Worktree Isolation Beats Shared Directories

Running two coding agents inside the same directory quickly corrupts build caches, staging areas, and test state. Because Orca provisions a dedicated Git worktree and branch per task, each agent compiles, runs unit tests, and hosts its own preview server without blocking or overwriting peer sessions.

## 2. Executable Resolution & Orchestration Mode Matrix

Because Orca runs across macOS, Linux, WSL, and source dev checkouts, choosing the right CLI executable once at session start prevents hitting the wrong runtime or triggering OS screen readers.

#### 1 Four-Step CLI Resolution Order

1. **WSL Sessions:** If `ORCA_CLI_COMMAND` is set, use its exact value (Orca injects this automatically).
2. **Dev Checkouts:** When `ORCA_DEV_REPO_ROOT` is exposed, use `orca-dev` instead of production binaries.
3. **Linux Outside Orca:** Always run `orca-ide`. Bare `orca` resolves to the GNOME screen reader (`/usr/bin/orca`).
4. **Standard Terminals & macOS:** Use `orca` (typically `/usr/local/bin/orca`).

#### 2 Safe Discovery & Strict Target Rules

Always pass `--json` for agent automation and load the version-matched skill guide before issuing mutations. If your selected executable fails, stop and report the exact error rather than falling back to another build.

Keep `ORCA_PAIRING_CODE` or `--environment` explicit when targeting remote runtimes.

```
<code># 1. Load version-matched instructions and inspect live runtime readiness (read-only)
orca skills get orca-cli
orca status --json
orca repo list --json
orca worktree ps --limit 20 --json</code>
```

### Choosing the Right Coordination Pattern

| Workflow Pattern | Primary Command | Ownership & Lifecycle | Best Used When |
| --- | --- | --- | --- |
| **Full Handoff** | `worktree create --no-parent --agent` | Transfers task to a new agent and stops; returns worktree ID & launch handle. | Delegating standalone tasks where you do not expect a report back. |
| **Existing-Checkout Launch** | `agent launch --worktree <sel>` | Opens chat or terminal per user Chat \| CLI setting in an existing branch. | Adding a second opinion or fresh session inside an active branch. |
| **Supervised Worker** | `orchestration worker-start --spec` | Binds a Task and Dispatch ID; wakes coordinator with `worker_done` mail. | Reviewers, builders, or parallel slices whose results must return to you. |
| **Task DAG & Gates** | `run-create` + `task-create --deps` | Orders dependent tasks and blocks steps behind human or coordinator gates. | Multi-stage pipelines (build -> test -> security review -> merge). |
| **Claude Native Teams** | `orca claude-teams` | Spawns Claude Code Agent Teams teammates as native Orca split panes. | Interactive Claude Code team sessions sharing one terminal tab group. |
| **Scheduled Automation** | `automations create --precheck` | Runs prompts on cron/RRULE schedules after a shell precheck passes. | Morning PR triage, nightly CI audits, or recurring inbox digests. |

#### Bring Your Own CLI & Subscription Transparency

Orca never proxies API traffic or charges token markups. Whether you launch `claude`, `codex`, `opencode`, `gemini`, `cursor`, `omp`, or `pi`, each agent authenticates directly with your local credentials or managed Orca account profile.

## 3. Annotated Workspace: The Orca Command Center

Orca unifies worktree lineage, WebGL terminal panes, task mailboxes, line-level diff annotations, and an embedded Chromium preview inside one keyboard-driven desktop window.

Orca ADE • acme/checkout-api • Runtime: Local + SSH (gpu-runner)

Account: Work-Claude • Mobile Paired

WORKTREES & LINEAGE

• main-coord [active]

PR #512 • STA-335 • Run #r9

&boxur; feat/stripe-v4 •

claude • in-review • +142/-18

"tests green; awaiting diff review"

&boxur; fix/webhook-sig

codex • running • SSH

&boxur; ui/checkout-btn

gemini • browser attached

SOURCE & PORTS

3 files changed • Draft PR ready

Ports: `:3000` (next), `:8787` (api)

TERMINAL SPLIT (claude • gpt-codex)

~/orca/checkout-api/feat-stripe-v4 $

> Implemented idempotent Stripe v4 hook

&radic; pnpm test tests/webhook.spec.ts (24/24)

[agent hook] Waiting for diff review

TASK DAG & MAILBOX (Run #r9)

[DONE] t1: Build webhook verifier (claude)

[GATE] t2: Confirm key rotation policy?

[WAIT] t3: Run staging E2E (deps: t1, t2)

Ask #m4 from dispatch:d_82 -> Reply ready

ANNOTATED DIFF REVIEW (src/stripe.ts)

- const sig = req.headers['stripe-sig'];

+ const sig = verifyHmac(rawBody, secret);

**Note L42:** Reject timestamps older than 300s -> *[Send to Agent]*

EMBEDDED BROWSER & DESIGN MODE

http://localhost:3000/checkout • ref `@e14`

Selected: `button.pay-cta` (padding: 8px 14px)

Captured DOM + Computed CSS + Cropped PNG -> Prompt

### Workspace Control Legend

**Worktree & Lineage Tree:** Shows parent/child worktrees, agent status dots, unread attention indicators, linked PR/Linear chips, and checkpoint comments.

**WebGL Terminal Splits:** High-speed split terminals per worktree with live agent lifecycle hooks and persistent scrollback across restarts.

**Task DAG & Mailbox:** Displays dependency-ordered tasks, active worker questions, and blocking human/coordinator decision gates.

**Inline Diff Annotations:** Lets you comment on exact changed lines and batch-deliver targeted revision notes straight back to the owning agent.

**Embedded Browser & Design Mode:** Worktree-scoped Chromium tab with `@eN` accessibility refs and one-click HTML/CSS + screenshot prompt injection.

**Source Control & Ports:** Tracks changed files, drafts PRs, and lists dev server ports bound to that workspace via `orca ports`.

**Account & Mobile Bridge:** Switches isolated agent account profiles (`orca account select`) and exposes remote/mobile pairing telemetry.

#### Keyboard-First Fleet Navigation & Unread Signals

Each sidebar card displays a live status badge (`todo`, `in-progress`, `in-review`, `completed`), an unread attention dot when an agent finishes or hits a gate, and a one-line comment written via `orca worktree set --comment`. You can jump between parallel worktrees, split terminals, or diff tabs without lifting your hands off the keyboard.

## 4. Parallel Git Worktrees, Lineage & Full Handoffs

Every Orca worktree pairs a real Git checkout on disk with tracked runtime metadata, ensuring parallel agents never trample each other's branches, caches, or dev servers.

*[Illustration: Luminous cyan Git worktree branches dividing symmetrically into four isolated agent workspace bays]*

**Figure 5.1 • Isolated Worktree Topology:** A single repository root branches cleanly into independent Git worktrees, keeping file edits, terminals, and browser sessions quarantined per agent.

#### 1 Two-Part Worktree IDs & Lineage

Every Git worktree has a unique address formatted as `<repoId>::<worktreePath>`, alongside human selectors like `active`, `name:api`, `branch:feat/auth`, or `folder:<id>` for multi-repo folder workspaces.

Keep lineage and Git base distinct: `--no-parent` keeps an unrelated handoff independent, while omitting `--base-branch` starts cleanly from the repo default base.

#### 2 Full Handoffs & Idempotent Retries

A full handoff spins up an agent in a new worktree (or targets an existing one with `agent launch`) and stops once `prompt.outcome` reads `journaled` or `handed-to-terminal`.

If a launch reply drops mid-flight, re-run the exact command with `--retry-launch <operationId>` so Orca replays the accepted request instead of spawning a duplicate agent.

```
<code># Independent top-level handoff to Codex with linked issue and status comment
orca worktree create --name auth-audit --no-parent --agent codex --model gpt-6-astra --effort high \
  --reference https://linear.app/acme/issue/ENG-412 --prompt "Audit JWT rotation and write tests." --json

# Child worktree inheriting parent lineage + setting card status & unread badge for human review
orca worktree create --name stripe-fix --parent-worktree active --agent claude --setup run --json
orca worktree set --worktree active --comment "repro confirmed; patch ready" --workspace-status in-review --unread --json</code>
```

## 5. Coordinator Loops, Task DAGs & Decision Gates

When an agent must delegate work to specialized peers and collect verified deliverables back, Orca Orchestration replaces brittle terminal scraping with structured Runs, dependency tasks, and durable mailboxes.

### Prompt & Config Anatomy: Supervised Task & Worker Dispatch

orca orchestration run-create --objective "Migrate payment gateway to v4"

orca orchestration task-create --spec-file ./specs/verify-pr.md --deps '["task_build_1"]'

orca orchestration worker-start --worktree new-child --agent codex --model gpt-6-astra --effort high \

--task task_verify_2 --keep-open --setup run --json

```
<code># Coordinator loop: start ready work, add a blocking decision gate, and steer live workers
orca orchestration task-list --ready --brief --json
orca orchestration gate-create --task task_deploy_3 --question "Ship migration to staging?" --options '["Approve","Hold"]' --json
orca orchestration send --to dispatch:disp_881 --subject "Edge case" --body "Also verify expired webhook signatures." --json
# Dispatched worker asks coordinator a question, then ends its turn to wake on reply:
orca orchestration ask --question "Use strict 300s replay window or 600s?" --options "300s,600s" --json</code>
```

#### 1 Event-Driven Wakeups

Start every independent worker, then end your turn. Orca wakes the coordinator automatically when a worker emits `ask`, `escalation`, or `worker_done`.

#### 2 Gates & Steering Mail

Answer worker questions with `orchestration reply --id <msg>`, unblock gates via `gate-resolve`, or redirect a finished worker via `send --to dispatch:<id>`.

#### 3 Circuit Breaker & Fencing

Retry failed starts with `--retry-of` (capped at 3 attempts before circuit-breaking). Use `worker-stop` for verified cancellation or `worker-abandon` to fence cleanly.

#### Critical Rule: Never Poll the Orchestration Mailbox

Running `orca orchestration check` inside a polling script or loop consumes unread messages immediately, hiding them from Orca's wakeup dispatcher so your coordinator never wakes. Let Orca deliver mail automatically, and pass `--spec-file` whenever specs contain quotes or special syntax.

#### W Dispatched Worker Contract

Workers launched via `worker-start` receive a Task ID and Dispatch ID preamble. To ask for clarification, run `orca orchestration ask` and end your turn. When finished, report evidence via `orca orchestration send --type worker_done --outcome succeeded`.

#### C Coordinator Cleanup & Continuity

Inspect settled outputs using `worker-read --source auto`, preserve interactive chats with `worker-keep-open`, or archive and release temporary terminals cleanly using `worker-release --dispatch <id>` once the Task settles.

## 6. Diff Annotations, Embedded Browser & Computer Use

Reviewing AI code should feel faster than writing it by hand. Orca connects line-by-line code annotations, worktree-scoped browser automation, and background desktop GUI control directly back to your agents.

*[Illustration: Translucent layered code diff glass panels channeling emerald and cyan highlight beams into an orchestration prism and mobile slate]*

**Figure 7.1 • Closed-Loop Review & Visual Context:** Inline diff notes and Design Mode DOM/screenshot captures flow cleanly back into active agent sessions across desktop and mobile.

#### 1 Inline Diff Review & File Tabs

Open changed files cleanly without stealing user focus via `orca file open-changed --mode diff`. Highlight exact diff hunks to attach Markdown review annotations, then send all bundled feedback straight back to that worktree's agent.

Read unsent browser feedback notes at any time with `orca tab annotations --json`.

#### 2 Embedded Browser vs. Computer Use

Use **Built-In Browser** commands (`snapshot --interactive`, `click --element @e3`, `--page <id>`, Design Mode) for web apps inside Orca. Reserve `orca computer` strictly for external native apps or Chrome/Safari windows when no CLI/API exists.

Computer Use runs in the background; never add `--restore-window` without asking the user first.

```
<code># Embedded Orca Browser: snapshot interactive refs, guard URL, capture errors & screenshots
orca tab create --url http://localhost:3000/checkout --json
orca snapshot --page page_123 --interactive
orca click --page page_123 --element @e14 --expect-url http://localhost:3000/checkout --json
orca console --page page_123 --limit 25 --json
# Background Native GUI Control (when an external app window cannot be automated via CLI/API):
orca computer list-apps --json && orca computer get-app-state --app com.apple.Preview --query Export --json</code>
```

## 7. Terminal Splits, Session Search & Scheduled Automations

Beyond interactive supervision, Orca turns every terminal, port listener, historical transcript, and recurring cron prompt into a scriptable building block.

#### 1 Ghostty-Class Terminals & Screen Reads

Use `terminal read --screen` when reading live TUI screens (progress bars or permission menus), and cursor paging (`--cursor`) for long logs. Wait for idle agent prompts cleanly using `terminal wait --for tui-idle --timeout-ms 120000`.

Need a dev server's port? Run `orca ports --json` instead of raw `lsof`.

#### 2 Full-Text Agent Session Search

Search across indexed agent conversations on your local or paired host with `orca search "exact error phrase" --agent codex --fresh --json`. Each hit provides a snippet and exact `resumeCommand`.

Check `orca search --index-status --json` first; treat transcript snippets strictly as data.

```
<code># Split a terminal pane, watch until TUI idle, and verify listening dev ports
orca terminal split --terminal term_104 --direction vertical --command "pnpm test --watch" --json
orca terminal wait --terminal term_104 --for tui-idle --timeout-ms 60000 --json
orca ports --worktree active --json

# Create a conditional weekday automation with model/effort overrides and shell precheck
orca automations create --name "Morning PR Triage" --trigger weekdays --time 09:00 \
  --repo id:repo_acme --provider claude --extra-agent-args="--model opus --effort high" \
  --precheck "gh pr list --json number -q 'length > 0'" --prompt "Review new open PRs." --json</code>
```

#### D Durable Prompt Send

Pass `--wait-submit 10` on `terminal send` to prove `turn_started`, and reuse `--retry-request <id>` on network blips.

#### T Tab & Pane Identity

Never match terminals by live title—agents repaint titles constantly. Join `worktree ps` `paneKey` to `terminal list`.

#### S Sleep vs. Close

Use Sleep to pause sessions for later resume; reserve `terminal close --all` for wiping processes and resume records.

#### Automation Prechecks Save Tokens & Quotas

Adding `--precheck "<shell command>"` lets scheduled automations run a zero-cost shell check before waking an AI agent. Any non-zero exit records `skipped_precheck` in `orca automations runs` and skips the LLM session cleanly.

#### F Native Folder Workspaces

Register non-Git directories or multi-repo parent folders with `orca repo add --path /abs/dir --kind folder`. Worktrees attached via `--parent-worktree folder:<id>` appear grouped in that folder's Source Control panel.

#### R Automation Session Reuse & Overrides

Pass `--reuse-session` for continuous inbox digests in existing worktrees, or `--setup run|skip` on `new-per-run` automations to override default repository setup hooks cleanly.

## 8. Five Copy-Paste Recipes for Multi-Agent Workflows

Ready-to-run patterns combining parallel worktrees, cross-model comparisons, UI feedback capture, remote SSH builds, and scheduled automation guards.

| Recipe & Goal | Agents & Surface | Core Implementation Pattern | Verification Gate |
| --- | --- | --- | --- |
| **1. Cross-Model Spec Race** Compare 3 agents on one hard fix | Claude Code + Codex + Gemini CLI | `worktree create --no-parent` x3 on same base branch; compare side-by-side diffs. | Run test suite in each worktree; merge best clean diff and archive runners-up. |
| **2. Coordinator-Verifier DAG** Author & independent reviewer | Coordinator + `worker-start` | `run-create` -> builder `new-child` -> `task-create --deps` verifier -> `gate-create`. | Block merge until verifier emits `worker_done --outcome succeeded`. |
| **3. Design Mode UI Repair** Fix broken CSS & console errors | Embedded Browser + Active Chat | Discover port via `orca ports`, inspect with `snapshot`, click in Design Mode to inject CSS. | Re-run `console --limit 20` and capture verification `screenshot`. |
| **4. Overnight SSH Offload** Keep builds alive while offline | Paired SSH Host + Mobile App | `worker-start --on gpu-box --worktree new-top-level --repo id:app` | Approve any `ask` prompt from Orca Mobile; inspect diff back at desk. |
| **5. Precheck CI Sweeper** Auto-triage failing workflows | `automations create` + CLI | Hourly schedule gated by `--precheck "gh run list --status failure -L 1"`. | Verify `skipped_precheck` when green; review created PR draft on failure. |

### Copy-Paste Script: Launch a 3-Way Model Race on One Issue

```
<code># Spawn three isolated, non-parented worktrees from the same repo default branch
for pair in "race-claude:claude" "race-codex:codex" "race-gemini:gemini"; do
  name="${pair%%:*}"; agent="${pair##*:}"
  orca worktree create --name "$name" --no-parent --agent "$agent" --setup run \
    --reference https://github.com/acme/api/issues/273 \
    --prompt "Fix race condition in session cache. Prove with unit tests." --json
done
# Monitor fleet progress across all worktrees without interrupting active tabs
orca worktree ps --limit 10 --json</code>
```

## 9. Remote SSH Hosts, Mobile Supervision & Safety

Offload heavy agent fleets onto dedicated Linux workstations or cloud VMs with orca serve, monitor progress from iOS or Android, and isolate credentials across accounts.

#### 1 Headless Servers & Paired Environments

Start a headless runtime on a build box using `orca serve` (over SSH on macOS without desktop login, set `ORCA_SERVE_RUNTIME=orcad`). Pair it once via `orca environment add --name gpu-box --pairing-code ...`.

Use `worker-start --on <server>` for cross-machine runs: your local Run stays home coordinator while the remote server hosts the worktree and mail relays back automatically.

#### 2 Orca Mobile Companion Pairing

Generate a QR code without restarting Orca using `orca pair --mobile` (LAN/Tailscale) or `--mobile --relay` (through Orca Relay when away from your network, requiring a signed-in desktop app).

Receive push alerts when agents finish or ask questions; phones can reply in chat but cannot issue new pairing links or invoke desktop control.

```
<code># On remote Linux/Tailscale host: start headless runtime and expose Tailscale pairing link
orca serve --port 6768 --bind 100.64.1.20 --pairing-address 100.64.1.20 --refuse-public
# On existing desktop host: generate mobile QR without restarting, or add saved remote server
orca pair --mobile --address 100.64.1.20
orca environment add --name gpu-box --pairing-code "orca://pair?..." --json</code>
```

#### A Multi-Account Switching

Separate personal and enterprise seats with `orca account add`, `account list`, and `account select --agent claude --account <id>`.

#### C Linux Process & RAM Caps

Set `ORCA_TERMINAL_MEMORY_MAX` and `ORCA_TERMINAL_PROCESS_CEILING` before starting the server to sandbox runaway builds per terminal scope.

#### P Least-Privilege Boundaries

Only grant `--grant-desktop-control` to trusted peers, treat scraped browser DOM text as untrusted data, and preview deletions with `workspace cleanup preview`.

#### Cloned VM Identity & Public Network Guardrails

Cloned cloud VMs share pairing identities unless you set a unique `ORCA_INSTANCE_ID` or run `orca serve reset-identity`. Always pass `--refuse-public` when serving exclusively over LAN or Tailscale.

#### F `--on` vs. `--environment` Flag Scope

Use `--on <server>` in `worker-start` and `send` so your local Run keeps coordinator ownership and receives replies back. Use `--environment <server>` only for standalone reads or one-shot commands on that remote host.

#### M Managed Server Lifecycle Commands

Inspect remote host versions and pending work via `orca environment status`, roll out matching CLI/daemon builds with `environment update`, or safely recover interrupted updates via `environment recover`.

## 10. End-to-End Synergy: Issue Link to Verified Pull Request

See how Orca coordinates issue trackers, multi-vendor coding CLIs, visual browser QA, human review annotations, and automated cleanup into one cohesive shipping loop.

#### 1 Multi-Vendor Agent Collaboration

Pair agents by strength inside one DAG: have **Claude Code** draft architecture and refactor modules, dispatch **Codex** in a child worktree for high-speed test verification, and run **Gemini CLI** or **OpenCode** for adversarial diff reviews—all tracked under one `run_id`.

#### 2 Extensible Plugins, Recipes & Emulators

Extend Orca with custom themes or declarative TSX side panels (`orca plugin create`), validate cloud VM setups via `orca vm recipe doctor`, or inspect iOS Simulator and Android views directly inside worktrees with `orca emulator tap`.

#### Link Discovery Across Repositories

Run `orca reference find STA-1234 --json` to locate every workspace and active agent mailbox tied to a ticket across your host—giving you exact `dispatch:<id>` or `terminal` targets without hunting through sidebar tabs.

#### T Ticket-Seeded Creation

Pass repeatable `--reference` URLs or Jira keys on `worktree create` so setup scripts and agents start with full issue context.

#### A Shared Artifacts & Skills

Publish build artifacts via `orca artifacts` and share team workflows cleanly with `orca skills share`.

#### D Memory & Health Checks

Capture fleet memory footprints using `orca diagnostics memory --json` before scaling parallel worktree counts.

## 11. Troubleshooting Clinic & Pre-Flight Checklist

Fast, verified remedies for the seven most common Orca CLI and multi-agent pitfalls, followed by a six-point readiness checklist before launching parallel fleets.

| Symptom & Error | Root Cause | 10-Second Production Fix |
| --- | --- | --- |
| **Bare `orca` starts speech on Linux** | Outside an Orca terminal, `/usr/bin/orca` is GNOME screen reader. | Run `orca-ide` on Linux hosts (or `orca-dev` inside dev checkouts; check `ORCA_CLI_COMMAND`). |
| **`runtime_unavailable` or `runtime_access_denied`** | App restarting briefly, or agent sandbox blocking socket access. | Wait a few seconds and retry on transient unavailability; escalate sandbox permissions. Never call `orca open` to retry. |
| **`agent_prompt_blocked` on `terminal send`** | Target agent CLI is waiting at a trust or permission prompt menu. | Inspect with `terminal read --screen`, then send `--text` and `--enter` as two separate commands. |
| **`terminal_handle_stale` after restart** | Runtime-issued handle expired across an Orca app or daemon restart. | Re-run `orca terminal list --json` and continue solely on the new replacement handle; never dual-send. |
| **`browser_stale_ref` or `browser_dialog_open`** | DOM re-rendered after navigation or an open JS alert blocks input. | Clear dialogs with `orca dialog accept/dismiss`, re-run `snapshot --page <id>`, and act on fresh `@eN` refs. |
| **Worker silent or `escalation` stop** | Agent exited early without calling `worker_done`, or circuit broke at 3 retries. | Inspect `worker-show` and `worker-read --source auto`; steer with `send` or reopen task explicitly. |
| **Setup hook or dev port mismatch** | Repo recipe misconfigured or dev server picked a fallback port. | Run `orca vm recipe doctor` to validate recipes and query `orca ports --json` instead of guessing ports. |

### 6-Point Orca Multi-Agent Pre-Flight Checklist

**&square; 1. CLI Executable Verified:** Confirm your session resolved `ORCA_CLI_COMMAND`, `orca-dev`, `orca-ide`, or `orca` and passes `status --json`.

**&square; 2. Accounts & CLIs Ready:** Run `orca account list` and `orca vm env doctor` so every worker CLI has valid credentials.

**&square; 3. Handoff vs. Orchestration Chosen:** Use `worktree create --no-parent` for fire-and-forget handoffs; use `worker-start` when results must return.

**&square; 4. Event-Driven Discipline:** Never poll `orchestration check` in scripts; start parallel workers and end your turn to wake on mail.

**&square; 5. Browser vs. Desktop Split:** Scope web QA to Orca's embedded browser (`--page`) and keep `orca computer` strictly background unless approved.

**&square; 6. Clean Teardown Planned:** Release finished workers with `worker-release`, preview rules via `workspace cleanup preview`, and prune merged worktrees.

---

## Edition Note & Attribution

This 12-page handbook, its topic structure, and its illustrations were generated with AI under human editorial direction and print-layout QA. Verify commands, pricing tiers, and security settings against official vendor documentation before production use.

- AI & Editorial Disclosure: https://twelve-pages.com/editorial
- Terms & Licensing: https://twelve-pages.com/terms
- Privacy & Cookie Notice: https://twelve-pages.com/privacy
