orca

Mental Model

Orca is a substrate for orchestrators, not an orchestrator itself. The caller decides what work to delegate and how to judge it. Orca owns native session binding, durable state, process control, continuity checks, and a stable JSON boundary across agents.

Dispatch Surfaces

lane — internal worker (default)

A worker intended to report its result back to a coordinating agent or script. It remains durable so it can be inspected and resumed.

orca dispatch --agent codex --cwd . "Investigate the flaky test"

task — user-followable Codex thread

A deliberately named thread intended for direct follow-up in Codex clients that share the same CODEX_HOME. Task surface is Codex-only and requires a non-empty --label.

orca dispatch --agent codex --surface task \  --label "HAPPY-123 — Fix API" \  --cwd /path/to/existing/worktree \  "Implement HAPPY-123 and run its focused tests"

orca dispatch

Create a lane and drive one native agent turn until it completes, fails, is killed, times out, or blocks on a question.

Dispatch prints a handle line immediately after lane creation, then exactly one final envelope. Capture the handle when another process may need to inspect or kill the lane before the turn settles.

{"v":1,"kind":"handle","laneId":"lane_a3f81c02","agent":"codex"}{"v":1,"kind":"lane","ok":true,"status":"completed","lane":{"id":"lane_a3f81c02","agent":"codex","surface":"lane"},"delivery":"confirmed","nativeStatus":"completed","semanticOutcome":"unknown","result":{"text":"..."}}

orca inspect

Read current state and durable events, optionally following until a target state is reached.

orca inspect lane_a3f81c02orca inspect lane_a3f81c02 --since 7orca inspect lane_a3f81c02 --followorca inspect lane_a3f81c02 --wait-for blocked --timeout 600000

--since N returns events with a sequence greater than N. Terminal states also satisfy --wait-for blocked, so always read the returned status instead of assuming the lane actually blocked.

orca answer

Submit an answer to a blocked lane's pending question.

orca answer lane_a3f81c02 "Use the staging database"

Answering a lane that is not blocked returns invalid_state (exit 4). Only Codex currently supports question parking, and that model behavior remains best-effort.

orca resume

Start a follow-up turn on the same native session and fail loud if continuity cannot be verified.

orca resume lane_a3f81c02 "Now add tests for the edge cases"

Completed and parked blocked lanes can resume. Failed, killed, and lost lanes cannot. A blocked lane with a live question poller rejects resume to prevent two processes from driving one native session.

orca lanes

List known lane records newest-first in a kind:list envelope.

orca lanes

orca kill

Terminate a queued, running, or blocked lane using the persisted native process identity.

orca kill lane_a3f81c02

Killing an already-killed lane is idempotent. Killing a completed, failed, or lost lane returns invalid_state.

orca agents

Return the live adapter manifests used for evidence-based routing.

orca agents | jq '.agents[] | {agent, capabilities, caveats}'

Model lists and measured overhead can change. Read the manifest instead of hard-coding them.

orca contract

Return the versioned command contract, exit codes, notes, and JSON Schemas.

orca contractorca contract --schema envelopeorca contract --schema eventorca contract --schema manifest

Blocked Question Flow

# Terminal states also satisfy this wait; inspect status.orca inspect lane_a3f81c02 --wait-for blocked --timeout 600000orca answer lane_a3f81c02 "Postgres"orca resume lane_a3f81c02 "Continue with that answer"

blocked is a successful state: ok:true, exit 0. It means the turn stopped at an explicit input boundary, not that the adapter failed.

Envelope Semantics

Three independent axes prevent protocol delivery from being mistaken for task success:

{  "v": 1,  "kind": "lane",  "ok": true,  "status": "completed",  "lane": {    "id": "lane_a3f81c02",    "agent": "codex",    "surface": "task",    "agentSessionId": "019f..."  },  "delivery": "confirmed",  "nativeStatus": "completed",  "semanticOutcome": "unknown",  "result": { "text": "..." },  "timing": { "wallMs": 6557, "startupMs": 2050 }}

• A command never exits 0 with ok:false.
• usage and timing cover one dispatch or resume turn, not lane history.
• Continuity proves session identity, not semantic compliance. Read status and result.text.
• stderr is diagnostic and non-contractual; stdout carries the handle and envelope.

Exit Codes

Durable State

Lane state lives under $${ORCA_HOME:-~/.orca}/lanes/<laneId>/. Set ORCA_HOME to isolate tests and automation from personal history.

lane.json       # durable lane recordevents.ndjson   # append-only evidence streamanswer.txt      # transient blocked-answer handoff

Agent Skill

Give an agent a compact operator guide. It starts with live contract discovery and keeps routing, question, continuity, and task-surface caveats close to the commands.

---
name: orca
description: "Dispatch and manage Codex, Claude, or Cursor lanes through Orca's machine-readable contract."
---

# Orca

Orca is an observable agent-lane harness. It does not plan or route work for you.

## First use
orca contract
orca agents

Trust the live contract and manifests over remembered CLI behavior.

## Dispatch
# Internal worker lane
orca dispatch --agent codex --cwd /path/to/repo --timeout 600000 "<brief>"

# Named, user-followable Codex task
orca dispatch --agent codex --surface task --label "HAPPY-123 — Fix API" --cwd /path/to/worktree "<brief>"

## Manage
orca inspect <laneId> [--follow] [--since <seq>] [--wait-for blocked|done]
orca answer <laneId> "<answer>"
orca resume <laneId> --timeout 600000 "<follow-up>"
orca lanes
orca kill <laneId>

## Contract rules
- Every lane verb ends with exactly one JSON envelope on stdout.
- dispatch prints a handle line first.
- status blocked is successful (exit 0); inspect the envelope status.
- Read status and result.text; continuity alone does not prove task success.
- --surface task names a durable Codex thread but does not provision a Desktop worktree.
- Persistent lane threads can also appear in Codex Desktop; surface is not a visibility filter.