Skip to content

orca-backend.md

Latest commit

 

History

History
81 lines (60 loc) · 3.86 KB

orca-backend.md

File metadata and controls

81 lines (60 loc) · 3.86 KB
Raw

Orca runtime backend

Orca is an experimental macOS backend in which the Orca app owns both the task worktree and terminal endpoint. The crewmate harness remains the agent process launched inside that endpoint. Firstmate agents load firstmate-orca before operating or recovering this backend.

Setup

Pick Orca when you already use the Orca macOS app and want Orca-managed worktrees and terminals instead of Treehouse plus a session multiplexer. Orca is macOS-only, explicit-only, and does not support secondmate spawns.

Prerequisites:

  • /Applications/Orca.app installed, running, and ready.
  • The orca CLI, installed with brew install orca.
  • The universal harness and toolchain requirements in configuration.md.

Select Orca with local config/backend containing orca, FM_BACKEND=orca for one launch, or an explicit request to Firstmate. It is never auto-detected.

Before any spawn mutates repository state, Firstmate requires orca status --json to report reachable=true and state="ready". The first task for a project registers that repository with orca repo add --path when needed. No manual repository registration is required.

Open the Orca app to watch a task's terminal. Routine supervision uses the recorded endpoint through bin/fm-peek.sh <id> and FM_HOME=<home> bin/fm-send.sh <id> '<text>'. Enter and Ctrl-C are supported; Escape is not.

Task shape and metadata

Each task has one Orca-managed git worktree and one Orca terminal. fm-spawn.sh does not call Treehouse for Orca tasks. The normal isolation and unlanded-work refusal rules still apply.

backend=orca
window=fm-<id>
terminal=<orca terminal handle>
orca_worktree_id=<orca worktree id>
worktree=<absolute Orca worktree path>

window= remains the caller-facing Firstmate alias. terminal= and orca_worktree_id= are the backend authority used by operation and cleanup paths.

Current lifecycle and safety

Spawn registers the repository, creates an independent worktree, reuses only the verified result.terminal.handle returned by Orca or creates a terminal explicitly, installs harness hooks, records metadata, and launches the selected harness. Exact command flags and response parsing are owned by bin/backends/orca.sh and script help.

fm-peek.sh reads with orca terminal read. fm-send.sh types and verifies composer clearance, follows oldestCursor when Orca returns a limited page, and retries Enter without retyping when a slash popup first fills an argument placeholder. A bare shell row is unknown, not an empty agent composer. The watcher has no native Orca busy signal and uses the shared terminal-tail fallback.

Cleanup keeps all shared Firstmate safety checks. A scout still requires its report and completed decision inventory. A ship still refuses dirty or unlanded work. Before release, cleanup resolves the recorded Orca worktree id and verifies its path matches the recorded worktree path. A missing, unreadable, or mismatched identity preserves metadata and stops rather than deleting anything. After those checks, Firstmate closes the exact terminal and releases the exact worktree with Orca's worktree command. It never raw-deletes an Orca worktree.

Active limits

  • Orca is macOS-only and explicit-only.
  • The app must be running and report ready.
  • Secondmate spawns are unsupported.
  • Escape is unsupported.
  • Orca exposes no stable CLI version or protocol marker, so readiness is the compatibility gate rather than a version floor.
  • Only the verified terminal-handle and worktree result fields are accepted; speculative response shapes are rejected.

Regression entry points

tests/fm-backend-orca.test.sh
tests/fm-backend.test.sh
tests/fm-bootstrap.test.sh

verification/runtime-backends.md records the real readiness and response-shape smoke.