Brennan Benson 7518c94fbd Record a Claude terminal's process even when Orca saw Claude before its first hook (#36825)
* fix(agent-status): let Claude's own hook record its process when the pane's owner has none

An owner recorded without a process (Claude's trust prompt seen before any hook, or a hook that couldn't capture one) refused every later process the agent's own hooks proved, so live Claude terminals stayed unproven and the next Claude in the pane inherited the same owner. The agent's first non-exit hook that proves a process in the same session (or when the owner names none) now claims it; nested agents run another session and stay refused.

Tracked in STA-13222.

* fix(agent-status): a terminal observation doesn't name the pane owner's session

The trust prompt's row carries the pane's previous session (a forked resume's source, an earlier Claude), so the owner it recorded didn't match the session Claude then reported and its process was still refused.

Tracked in STA-13222.

* feat(agent-status): classify a hook's process against its pane from one process table

A hook process is the pane's root when no agent runs above it inside its
terminal session and it holds the foreground (or the foreground has no
agent); an agent above it makes it nested, a foreground agent makes a
background job competing, and anything missing or unreadable is unknown.
The reader validates PID and start identity with the existing probe before
reading the shared budgeted process table, and coalesces concurrent reads.

* fix(agent-status): only an agent's own evidence names a pane's owner; its root process acquires an unproven pane

Terminal, title and process-name reports and Orca's own restatements
(inferred settles, timer and poll republishes) now publish status but keep
the recorded association as it is, suspended and retired ones included, and
never create one. A genuine hook from an agent without process capture still
names its own session. An admitted exit is now an explicit result, so a
retired record carried on the next agent's terminal report never re-clears
it or refreshes the exit.

When a Claude hook carrying its process reaches a pane whose row has no
proven live owner (a trust prompt seen first, a launch seed's source session,
a hook owner that never sent its process, another agent's leftover record or
a retired one), the execution host classifies the sender before provider
folds run, in the shared hook preflight on both the desktop and the relay
(HTTP and spool). A root acquires agent, process and session together;
nested and competing background processes are refused; unknown evidence is
applied as a hook without a process and retried on the next hook. A late hook
from the retired process is refused before folds. Hooks matching a proven
owner never read the process table, and proven-owner rules are unchanged.

* test(agent-status): pin root acquisition gates, unreadable evidence and retired-process folds

Covers a mid-turn record left by another agent (the identity gate must not
refuse the proven root), an unreadable acquisition over a trust prompt (no
guessed process), and a late hook from the retired process being refused
before provider folds.

* test(agent-status): drop the terminal-first presence test the root acquisition contract now covers

* fix(agent-status): answer a hook's root read within the hook's own timeout

A busy Linux process table can take over a second; the hook's curl gives up
at 1.5s and spools its event. Each hook now waits at most 500ms, reads as
unknown past that, and the next hook joins the still-running read.

* fix(agent-status): prove a hook's process belongs to its pane's own job

The first rebuild judged a hook's process against the sender's own terminal, so a shell
wrapper named claude read as a nested agent (every hook refused), a Claude in another
terminal that inherited the pane key could take a Codex pane, a real nested `claude -p`
(run by Claude's Bash tool in a new session with no terminal) read as unknown, and a slow
whole-host process table made every blocking hook wait without ever healing.

Acquisition now needs proof that the process runs in the pane's own job on the host that
owns the pane: the pane's root comes from its PTY provider's inventory, the sender's
ancestry is walked across detached tool sessions up to that root, shell scripts and npx
layers count as launchers, the pane's terminal and foreground job decide root versus a
competing background or foreign terminal, and tmux panes are tied through the outer pane's
foreground client. Reads are targeted (the sender's lineage and the pane's terminal), one
500 ms answer deadline is shared per attempt, late results are kept, unproven evidence is
retried once per turn, and exits get fresh proof. The pane root's own exit retires the
same agent's unproven record once. Desktop, serve and orcad wire the resolver; the WSL
relay asks the desktop for the pane's guest root and keeps the legacy path when the desktop
or the pane's PTY predates it; a relayed process is pane-root proof only from a relay that
asked this session.

* feat(agent-status): name a WSL pane's guest root from the PTY that owns it

A WSL pane's PTY belongs to Windows, so the guest-side hook relay had no way to know which
guest shell is the pane's root: the Windows PID of wsl.exe means nothing inside the distro,
and an inherited pane key proves nothing.

The WSL bootstrap now prints a one-shot marker with its guest PID and Linux start identity
before it execs the login shell (same PID, every shell, never waiting on anything). The PTY
owner, the daemon session or the in-process provider, watches only the launch output for it
and keeps it as volatile metadata of that PTY incarnation in its inventory. The desktop
answers the relay's pane-root request from that inventory for the relay's own distro, and
marks that link as one whose relay proves pane roots. A PTY started before its owner
recorded roots answers legacy, so the relay keeps its existing path.

* test(agent-status): keep a Claude run under Hermes out of its scoped binding, then let the pane's Claude own it

* test(agent-status): mark the slow-host reader's fake-timer delay as no real wait

CI's flaky-test ratchet flagged the simulated read delay in the owner-presence deadline tests, which fake timers drive; the ignore names that, so the 800/2,000 ms contracts stay as they are.

* fix(agent-status): a pane's first unproven hook keeps main's process; only proof replaces it

Round 3 found four places where pane-root acquisition trusted something that is not proof:
- A WSL relay that merely asked for a pane root was trusted for every pane on its link, so after a relay restart a nested `claude -p` could take a pane on a legacy answer and its exit cleared the parent's row. The desktop now issues a binding only for a returned guest root, per pane and link generation, and accepts a relayed owner as proved only when it echoes that binding for the pane's current PTY.
- An untraceable launch (a spawning shim, screen, an unreadable ps, a missed answer deadline) into an empty pane recorded no process, so its exit no longer ended the row. As on main, that first hook now records its process, tagged as a fallback that a later proved root replaces (saved, so it survives a restart). A Claude in a tmux session the pane can't be shown to display gets its status, session and Done without a process.
- A slow host's late answer was dropped after 10 s and each turn waited again. The answer is kept, each process waits at most once, and a late answer now heals the pane, upgrades or withdraws a fallback, or retires the row on an exit that missed its answer, with no later hook and no replayed prompt.
- A suspended owner let any other process take the pane. Only the pane's own foreground job replaces it now; a nested or unverifiable sender is refused before it changes the prompt.

A hook that challenges the owner no longer erases the owner's proved exit unless it is admitted as the successor, and a pane inventory snapshot taken before a PTY spawned is re-read once instead of answering for it.

* perf(agent-status): cap a host's pane-root reads at four at a time

Each pane's first hook started its own ps reads, so a burst of panes (a restore, many agents starting together) spawned one process-table read per pane at once; on a loaded Linux or Mac host past ~70 panes that alone outran the hook's 500 ms answer. Every subprocess or /proc read the acquisition makes (the sender probe, per-PID and per-terminal ps, Linux start identity, tmux list-clients/display-message) now takes one of four shared slots, released on success, failure or abort, and an attempt past its work budget gives up its queued reads.

* perf(agent-status): share one pane-root request among a WSL pane's concurrent hooks

Hooks of one pane arriving together each asked the desktop for the pane's root; they now share the request in flight.

* fix(agent-status): read no tmux from agent-teams' synthetic TMUX; refuse a pane only shown elsewhere

Orca's agent-teams launch gives its Claudes a synthetic TMUX that names no tmux server, so their hooks sent a tmux hint and an untraceable first hook into an empty pane showed status without recording the process main records. One shared constant now names that synthetic socket for the launcher and the hint parser, which reads no hint from it.

A tmux session attached only in another app's terminal read like a detached one (status only). When no client runs in the pane and every client showing the hinted pane has a fully read lineage outside it, the hook is now refused as foreign; anything unverifiable stays status-only.

* fix(agent-status): a late root heals what its next hook would; a stopped fallback resumes as itself

A late answer only reached the pane if the row still had the association the read started against, so the status-only record a hinted first hook minted into an empty pane while its read was pending kept the root out until the next hook. A late root now acquires over any record a root outranks on the hook path (none, an unproven one, a fallback); a stopped or retired owner must still be the one the read started against, and an owed exit retires only the record that exit saw. The hand-off to the host follows whether a hook actually went on without the answer, not a second reading of the clock, since a hook's timer can fire before it.

A Ctrl-Z'd fallback owner's own hooks after fg were refused as a would-be replacement. Suspension now blocks only another process; the owner's own hook resumes it with its process, session and fallback tag, and a late upgrade of its own fallback keeps it suspended.

* test(agent-status): read a tmux pane shown only in another terminal through the real bridge reader

* fix(agent-status): point the moved local-PTY modules at the shared WSL root marker

main moved the local-PTY modules into src/main/providers/local-pty/; the merge carried this PR's two imports of the WSL guest root marker into them at the old depth, which broke the build.

* test(agent-status): type the pane-root reader test's process mocks

* test(agent-status): type the reader test's platform without an assertion

* perf(agent-status): give a spool drain one acquisition answer deadline

Startup replay ran each unproven pane's acquisition in series, so every pane
added up to 500 ms before the listener bound or live hooks were answered. The
drain now owns one deadline on desktop, serve and the WSL relay; every record's
attempt, joins included, is capped by it and hands a later answer to the host.

* fix(orcad): install the pane-root reader before startup replay

orcad started its hook server, and so replayed the spool, before installing
the pane-root reader; replayed hooks took the legacy path and recorded their
processes as proven owners. The reader is now in place before the server
starts, so replay reads the same evidence as live hooks.

* fix(agent-status): record a WSL guest root printed before its session subscribed

Output a PTY prints before its session subscribes is replayed while the
session is constructed. If that output held the guest-root marker, the
callback read the session before it existed and the WSL session failed to
start. The root is now held until construction finishes, then recorded.
2026-11-02 10:20:49 -08:00
2026-03-16 22:27:51 -07:00
2026-03-28 10:19:14 -07:00

Orca Orca

GitHub stars Total downloads across all releases License: MIT Join the Orca Discord Follow Orca on X Supported platforms: macOS, Windows, and Linux

中文 · 日本語 · 한국어 · Español · Français · Português · Türkçe · Русский

The AI Orchestrator for 100x builders.
Run Codex, ClaudeCode, OpenCode or Pi side-by-side — each in its own worktree, tracked in one place.

Download Orca

Orca desktop app running agents in parallel worktrees, with the Orca mobile companion app in the corner

Features

Mobile Companion

Monitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere.

iOS App Store · Android APK · Docs →

Orca desktop with the mobile companion app

Parallel Worktrees

Fan one prompt across five agents, each in its own isolated git worktree — compare the results and merge the winner.

Docs →

Parallel worktree orchestration

Terminal Splits

Ghostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts.

Docs →

Terminal splits

Design Mode

Click any UI element in a real Chromium window to send its HTML, CSS, and a cropped screenshot straight into your agent's prompt.

Docs →

Embedded browser and Design Mode

GitHub & Linear, Native

Browse PRs, issues, and project boards in-app — open a worktree from any task and review without a context switch.

Docs →

GitHub and Linear task workflows in Orca

SSH Worktrees

Run agents on a beefy remote box with full file editing, git, and terminals — auto-reconnect and port forwarding included.

Docs →

Remote worktrees over SSH

Annotate AI Diffs

Drop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Orca.

Docs →

Annotate AI-generated diffs

Drag Files to Agents

VS Code's editor with autosave everywhere — drag files or images straight into an agent prompt.

Docs →

Drag files and images into an agent prompt

Orca CLI

Agents drive Orca too — script every workflow with orca worktree create, snapshot, click, and fill.

Docs →

Script Orca from the CLI

Also in the box:

  • Quick open — Search across worktrees, files, agents, commands, and repo context without leaving your flow.
  • Account switcher & usage tracking — See Claude and Codex usage and rate-limit resets, and hot-swap accounts without re-logging in.
  • Rich repo previews — Preview Markdown, images, PDFs, and repo docs in the workspace.
  • Computer Use — Let agents operate desktop apps and visible UI when a workflow needs real interaction.
  • Notifications and unread state — Know when an agent finishes or needs attention, then mark threads unread to come back later.
  • And many, many more — we ship daily, so this list is perpetually behind. The changelog is the real feature list.

Supported Agents

Works with any CLI agent — if it runs in a terminal, it runs in Orca.

Claude Code logo Claude Code   Codex logo Codex   Grok logo Grok   Cursor logo Cursor   GitHub Copilot logo GitHub Copilot   Muse logo Muse   DeepSeek Harness logo DeepSeek Harness   ZCode logo ZCode   OpenCode logo OpenCode   MiMo Code logo MiMo Code   Amp logo Amp   OpenClaude logo OpenClaude   Antigravity logo Antigravity   Pi logo Pi   oh-my-pi logo oh-my-pi   Hermes Agent logo Hermes Agent   Devin logo Devin   Goose logo Goose   Auggie logo Auggie   Autohand Code logo Autohand Code   Charm logo Charm   Cline logo Cline   CodeBuddy logo CodeBuddy   Codebuff logo Codebuff   Freebuff logo Freebuff   Command Code logo Command Code   Continue logo Continue   Droid logo Droid   Kilocode logo Kilocode   Kimi logo Kimi   Kiro logo Kiro   Mistral Vibe logo Mistral Vibe   Qwen Code logo Qwen Code   Rovo Dev logo Rovo Dev   + any CLI agent


Install

Desktop — macOS, Windows, Linux

Or via a package manager:

# macOS (Homebrew)
# Always use the full name; bare `orca` is an unrelated Plotly cask.
brew install --cask stablyai/orca/orca
# Upgrade an existing install
brew upgrade --cask stablyai/orca/orca

# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin

Mobile Companion — iOS, Android

Pair with your desktop app to monitor and steer your agents from your phone.


Community & Support

  • Discord: Join the community on Discord.

  • Twitter / X: Follow @orca_build for updates and announcements.

  • WeChat: Scan to join the Orca community WeChat group.

    WeChat QR code for the Orca community
  • Feedback & Ideas: We ship fast. Missing something? Request a new feature.

  • Privacy: See the privacy & telemetry docs for what anonymous usage data Orca collects and how to opt out.

  • Show Support: Star this repo to follow along with our daily ships.


Developing

Want to contribute or run locally? See our CONTRIBUTING.md guide.

The relay that pairs the mobile app with a desktop host is also in this repository under cloud/, with a separate pnpm workspace and setup guide.

Orca contributors

GitHub star history chart for stablyai/orca

Signed Builds

Windows code signing sponsored/provided by SignPath.io, certificate by SignPath Foundation.

License

Orca is free and open source under the MIT License.

S
Description
Orca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
Readme MIT
2.8 GiB
Languages
TypeScript 95.4%
JavaScript 3.5%
Swift 0.3%
CSS 0.2%
Python 0.2%
Other 0.1%