mirror of https://github.com/stablyai/orca.git synced 2026-11-01 01:27:35 +00:00

T

Neil 756d623955 perf(terminal): bound the in-process macOS process table's blocking calls and ps fallbacks (#31783 ) (#36282 )

* fix(terminal): bound the in-process macOS process table's blocking calls and ps fallbacks (#31783)

Follow-up to #35987 from its post-merge reviews.

- cwd and executable path: node-pty's readProcessCwd/readProcessPath now run
PROC_PIDVNODEPATHINFO and proc_pidpath on a libuv worker (the synchronous
exports are gone, so an older pty.node falls back to ps/lsof). JS caps them at
two outstanding lookups and 250ms; a wedged mount or a full cap answers from
lsof -b, which never stats, so a dead NFS/SMB/FUSE mount cannot freeze the
daemon's event loop or take the whole pool.
- Unreadable argv prints "(comm)", as ps does, instead of a proc_pidpath lookup
under Orca's credentials on the table worker.
- The table exports each row's euid. Argv recovery runs setuid ps only for
another user's processes, never for our own mid-exec or exiting ones (or
SIDL/exiting rows), which ps cannot read either: a pane looping short
commands forked ps on ~15% of full reads, now none.
- Recovery is coalesced per process across concurrent readers and a failed
recovery waits 5s before costing another ps. The cache keys on comm and start
time.
- Full-table and shell-foreground captures, which feed strict evidence with
the capture's age, take only argv ps read after their request; display
readers keep the 30s cache.
- While the reader is down (stalled-pool breaker open, or a rejecting addon,
which now backs off 1s..30s), runPsInProcess runs /bin/ps itself through one
shared budget: identical invocations share a run, a burst of 4 forks then one
a second, and a run spawned before a request never answers it. Descendant
teardown and foreground-group signalling keep their own full-timeout ps
(callerRunsPs). 13 pollers at 750ms: 1,040 ps/min before, 63 after.

No daemon protocol bump: the wire format is unchanged, and each daemon loads
JS and pty.node from the same runtime copy.

* fix(terminal): make the libproc reader survive worker teardown, fail closed and share one fair fork budget (#31783)

Review follow-ups to the previous commit.

- Native: every libproc AsyncWorker derives from OrcaPromiseWorker, which skips
JS completion once an env cleanup hook marks the env closing and swallows a
Napi::Error thrown mid-teardown. Terminating a worker_thread with cwd or table
reads in flight aborted the process; 200 terminates each now survive.
- (comm) in a terminal's foreground group (argv neither reader recovered, e.g.
a root `su`) judges 'unknown', never 'agent', so the launch line is not typed
into it.
- Fresh argv only for getFreshSnapshot captures; the 500ms TTL readers keep the
30s cache. Argv recovery runs through its own fork budget (2, then one per
2s). Root `su` pane, 13 pollers at 750ms: TTL 79 -> 2 ps/min, fresh 158 -> 31.
- The fork budget serves invocations in FIFO turns, grouping each one's waiters
onto one run. 13 streams: served 80,42,1,1,2,0x8 -> 10-12 each.
- Forced subprocess captures (a held naming pass) go through the fallback
budget: 5 readers, 400 direct ps/min -> 63, 395 of 400 captures served.
- A failed recovery is retried 5s after ps gave up, not after it started.
- Tests pin Orca's euid instead of reading the runner's and assuming root is 0.
- process-cwd keeps one lsof per pid until it exits, so a dead mount no longer
leaks one per poll; shell readiness reads the exe path through runProcess,
which gives up on an lsof that ignores SIGTERM.
- A #35987 pty.node (table reader, no async path reads) keeps the in-process
table; cwd/path use lsof, with a one-time warning.
- captureProcessTable moves to process-table-ps-capture.ts.

* fix(terminal): make withheld argv unverifiable and reuse recovered argv for at most 2s (#31783)

Round-2 review follow-ups.

- Worker teardown: drop OrcaPromiseWorker and its env flag (Node drains the
pool before cleanup hooks, so it never fired). node-pty's mac pty target now
builds with NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS, which covers both the
call-in and completion paths. The smoke test now calls the reads from a
timer while terminating: the previous build aborted 2 of 3 runs, this one
survives 3/3 x 100. pty.cc is back to the first follow-up's exact content.
- A foreground process whose argv ps withheld (`(comm)`: another user's,
exiting, or a recovery the budget skipped) makes the batch resolver, and so
host-stamped evidence, `argv_unreadable`/unverifiable rather than live with no
agent; agent-foreground resolution reports it unavailable.
- judgeTerminalForeground fails closed only for an unreadable shell (`(bash)`
from a root `su`), not our own exiting `(git)`.
- Recovered argv is reused for at most 2s per identity (pid, start, comm) for
every reader (the next commit ages evidence by it), and
fresh reads no longer queue behind the recovery budget. Root `su` pane, 13
fresh pollers: p50 2,989ms -> 53ms, 31 -> 26 ps/min (TTL reader 1 -> 26).
- The fork budgets serve interactive and fresh readers before display polls
(cheap and TTL snapshot captures), FIFO within each. 20 display streams plus
a 3s launch-paste read every 5s: 0/12 -> 12/12 served, polls 4-7 each.
- On a selected terminal, the foreground group's argv is recovered even with no
process of ours left (`exec su`); the root login is not.
- Budgeted captures keep the 32 MiB output ceiling.

* fix(terminal): age strict evidence by its oldest recovered argv (#31783)

Round-3 review follow-ups.

- Recovered argv carried no read time, so a capture reusing it (cached, or a
recovery still in flight) stamped its own capture time over argv up to 2s
older, and the remote write guard could take a same-comm re-exec for the
agent. Rows now carry when ps read their recovered argv; runPsInProcess
reports the oldest through onArgvReadAt, and the snapshot reader stamps
capturedAtMs at that input, so capturedAgeMs is the age of the oldest input
and consumers' own freshness checks (the write guard's 500ms) decide. A
recovery begun more than 2s before a reader asked no longer answers it, and
an older recovery finishing late cannot replace a newer one.
- resolveSpawnFileForegroundFromRows reports a withheld `(node)` foreground
unavailable.
- One budget queue entry per invocation: an interactive request promotes a
queued poll's, a poll joins an interactive one.
- parseShellForegroundRows gets its JSDoc back.

* fix(terminal): keep a cached name from authorizing a refused write; integer, under-2s argv ages (#31783)

Round-4 review follow-ups.

- When the relay's evidence declines a write (stale, unverifiable, another
agent), its foreground name may still prove the shell but no longer proves
the agent: that name can be the tracker's 1s display cache, e.g. `claude`
cached just before Claude exited to a root shell under su. Relays that send
no evidence keep the name as before.
- Snapshot ages round up to whole milliseconds; the wire rejects fractions
from the monotonic-to-wall conversion.
- Recovered argv is reused for at most 1.5s, so reuse plus the 500ms snapshot
cache stays under the 2s freshness gate; reuse ages from when that ps
spawned, not from the wait for its fork token, and only an answer is
remembered (a timed-out or withheld run proves nothing). Fork budget
unchanged. Root su pane, 13 pollers: 30 ps/min; fresh p50 51ms; strict
evidence age p50 752ms, max 1,508ms.

* fix(terminal): keep the relay's agent name behind structurally unverifiable evidence (#31783)

The previous commit refused the name fallback whenever the relay sent any
evidence, so `unverifiable` evidence for structural reasons also blocked
writes: npm Codex (node codex.js spawning native codex) and Gemini (relaunching
itself) put two agent rows in the foreground group (ambiguous_foreground_group),
and remote tmux reads multiplexer_boundary. On SSH POSIX hosts that dropped
launch prompts and failed worker briefs, conversation send/cancel and
automations with agent_not_in_foreground.

The name now cannot authorize only when the evidence saw the group (`live`:
stale, or no agent in it, as in the cached-`claude`-over-root-shell repro) or
withheld a foreground argv (`argv_unreadable`, possibly a root `su` shell).
Other unverifiable reasons keep the name fallback, as before this branch.

* fix(terminal): let a relay name complete only fresh agent-positive evidence (#31783)

The SSH name fallback still let a stale or cached name authorize a write under
any unverifiable reason but argv_unreadable: ps EAGAIN (process_table_unreadable)
after the tracker cached `claude` over a root bash, anchor_missing,
tty_boundary (`sudo -i` with use_pty, a root shell on a new pty), or a 1.5s-old
ambiguous capture.

- The name now completes evidence only when it is fresh (within the guard's
500ms bound), its reason is one that saw an agent row
(ambiguous_foreground_group, multiplexer_boundary,
candidate_start_time_missing), and the name is the launched agent. Every other
reason, including ones this build does not know, reads unknown. Relays that
send no evidence keep the name, for mixed versions.
- The relay's evidence names one agent that holds two rows of the group (npm
Codex: node codex.js spawning native codex; Gemini relaunching itself), so a
new relay proves them live even when its name is `node`. Two different agents
stay ambiguous. No wire change.

* fix(terminal): judge a relay name by the host's capture age; keep old relays' npm Codex (#31783)

- Name completion compared the capture's start with the read's start, so a
slow response made old evidence look fresh: a capture 1,500ms old arriving
after 1,100ms passed. It now uses the host-reported capturedAgeMs against
the 500ms bound, which latency cannot shrink. Live evidence keeps its
capture-start rule.
- Relays before same-agent dedupe report npm Codex (node wrapper plus native
binary) as ambiguous_foreground_group and name it `node`. For that reason
only, `node` now completes the evidence when the launched agent is
npm-installed per the node entrypoint tables; other agents and reasons stay
fail-closed.

* fix(terminal): bound relay-name completion by twice the snapshot TTL (#31783)

The 500ms bound refused ~9.5% of tmux name completions on a host with 13
pollers (cached snapshot up to one 500ms TTL old plus ~30ms capture, max
528ms), and a refusal drops the launch prompt or throws with no retry. The
bound is now 2 x PROCESS_TABLE_SNAPSHOT_MAX_STALENESS_MS (1s), still on the
host-reported age: 0 of 767 reads exceed it, the delayed 1,500ms repro still
refuses, and the cached-name hazard (the tracker's ~1s display cache) is no
wider.

* fix(terminal): complete relay evidence with a name read now, not the display cache (#31783)

With the 1s bound, a capture at 0-528ms, `codex` cached at 100ms, Codex
exiting at 101ms and the guard at 999ms still let the cached name authorize a
write over the bash that replaced it.

- Name completion (structural reasons, host age within 2x the snapshot TTL)
now asks confirmForegroundProcess, which reads the foreground now (a fresh
scan, or node-pty's raw process name) rather than the tracker's 1s display
cache; a null answer reads unknown. No new wire surface: the local daemon answers
confirmForegroundProcess, paired runtimes evaluate guards locally, and the
production controller returns null (read as unknown, failing safe) when a
provider lacks it. Controllers without the method, and relays sending no
evidence, keep the cached name as the legacy path.
- Live evidence also accepts a host-reported age within 2x the TTL, so a real
agent behind a 500-528ms cached snapshot on a fast link is no longer
refused; a capture begun after the read was asked still counts, and
5,000ms-old evidence still refuses.

* fix(terminal): confirm live evidence older than one snapshot TTL with a fresh read (#31783)

Accepting live evidence up to 2x the TTL reopened the window the previous
commit closed for name completion: a capture at 0-528ms, the agent exiting at
~529ms, and at 999ms `live claude` still read as agent over a bash.

Live evidence begun no more than one TTL before the read was asked (so any
host age within one TTL, however long ps took) still answers alone. Between
that and 2x the TTL, confirmForegroundProcess reads the foreground now: the
launched agent proves it, a shell reads shell, anything else unknown.
Controllers without that read fall through and refuse, as before.

Reachability: the remote (host.remote) write-guard path has no production
caller since the SSH provider's removal (#27499); the registry dispatches only
local providers and paired runtimes evaluate guards locally. This is defence
in depth for any future remote provider.

2026-10-30 01:05:34 -07:00

.claude

feat(agents): TypeScript 7 code intelligence for coding agents, load-aware tsrs checkers (#33408 )

2026-10-24 23:47:10 -07:00

.github

ci(windows): install Electron once before the Windows boundary tests (#36248 )

2026-10-29 22:14:00 -07:00

.husky

fix(win32): resolve EPERM on userData writes, batch-file spawn failures, and native dep rebuild (#1152 )

2026-04-26 22:29:58 -07:00

Casks

[comment audit] Complete repository-wide comment cleanup (#33249 )

2026-10-25 04:05:46 -07:00

cloud

perf(relay): pause drained settled-credential reaps for 5 minutes (STA-7899) (#36144 )

2026-10-29 21:02:20 -07:00

config

perf(terminal): bound the in-process macOS process table's blocking calls and ps fallbacks (#31783 ) (#36282 )

2026-10-30 01:05:34 -07:00

docs

Allow conflict-safe private storage from plugin panels (#36273 )

2026-10-30 01:02:21 -07:00

examples/plugins

plugins: derive the publisher from where a plugin comes from, like a Go module path (#36281 )

2026-10-30 00:45:00 -07:00

mobile

Keep cancelled async questions hidden and show new ones (#35870 )

2026-10-30 00:36:11 -07:00

native

fix(computer): preserve Unicode in Windows typing (#36244 )

2026-10-30 05:13:17 +00:00

resources

plugins: Plugin Alpha (#35470 )

2026-10-28 20:58:25 -07:00

skill-guides

fix(browser): let agents and users answer page alert, confirm and prompt dialogs on their page (#36268 )

2026-10-30 07:39:38 +00:00

skill-stubs

fix(orchestration): route dispatched workers to the skill and stop heartbeat loops before worker_done (#34404 )

2026-10-27 05:12:22 -07:00

skills

Show Orca publishing guidance only when the host has it on (STA-12225) (#34547 )

2026-10-27 18:20:40 -04:00

src

perf(terminal): bound the in-process macOS process table's blocking calls and ps fallbacks (#31783 ) (#36282 )

2026-10-30 01:05:34 -07:00

tests

fix(browser): agent fill, select, upload and type change the page or fail with a reason (#36263 )

2026-10-30 06:48:58 +00:00

.gitattributes

[comment audit] Finish launcher and configuration comment review (#33513 )

2026-10-25 04:20:32 -07:00

.gitignore

docs: restore AGENTS.md reference docs under docs/agents-md-refs (#34322 )

2026-10-27 01:07:06 -07:00

.mcp.json

feat(devex): component fixtures with headless screenshots for fast UI checks (#33406 )

2026-10-25 00:23:32 -07:00

.oxfmtrc.json

plugins: Plugin Alpha (#35470 )

2026-10-28 20:58:25 -07:00

.oxlintrc.json

perf(ssh): load ssh2 on first use instead of at startup (#35911 )

2026-10-29 04:28:00 -07:00

AGENTS.md

docs: prefer focused validation in agent instructions (#36264 )

2026-10-29 23:35:35 -07:00

components.json

Shadcn

2026-03-16 22:27:51 -07:00

electron.vite.config.ts

perf(build): bundle the startup YAML dependency (#35225 )

2026-10-28 13:36:11 -07:00

LICENSE

Add MIT license

2026-03-28 10:19:14 -07:00

opencode.json

feat(agents): TypeScript 7 code intelligence for coding agents, load-aware tsrs checkers (#33408 )

2026-10-24 23:47:10 -07:00

orca.yaml

Revert waiting for setup before agent startup (#17418 )

2026-08-30 09:33:09 -07:00

package.json

fix(editor): match Unicode heading anchors across rich and preview modes (#35077 )

2026-10-29 17:14:52 -07:00

pnpm-lock.yaml

perf(terminal): bound the in-process macOS process table's blocking calls and ps fallbacks (#31783 ) (#36282 )

2026-10-30 01:05:34 -07:00

pnpm-workspace.yaml

Keep zoomed PDF detail text sharp (#36173 )

2026-10-29 21:27:45 -07:00

README.md

docs: update WeChat community QR code (#35803 )

2026-10-29 00:33:29 -07:00

tsconfig.json

refactor(relay): delete the SSH relay server, its build assets and tests (#27215 )

2026-10-10 22:36:42 -07:00

vite.web.config.ts

[comment audit] Complete repository-wide comment cleanup (#33249 )

2026-10-25 04:05:46 -07:00

README.md

Orca

_{中文 · 日本語 · 한국어 · 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

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 →
Parallel Worktrees Fan one prompt across five agents, each in its own isolated git worktree — compare the results and merge the winner. Docs →
Terminal Splits Ghostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts. Docs →
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 →
GitHub & Linear, Native Browse PRs, issues, and project boards in-app — open a worktree from any task and review without a context switch. Docs →
SSH Worktrees Run agents on a beefy remote box with full file editing, git, and terminals — auto-reconnect and port forwarding included. Docs →
Annotate AI Diffs Drop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Orca. Docs →
Drag Files to Agents VS Code's editor with autosave everywhere — drag files or images straight into an agent prompt. Docs →
Orca CLI Agents drive Orca too — script every workflow with `orca worktree create`, `snapshot`, `click`, and `fill`. Docs →

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

Install

Desktop — macOS, Windows, Linux

Download from onOrca.dev
Or grab a build directly: macOS Apple Silicon · macOS Intel · Windows (.exe) · Linux AppImage · All builds

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.

iOS: Download on the App Store
Android: Download APK · Install guide

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.
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.

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.

README.md

Orca

Download Orca

Features

Mobile Companion

Parallel Worktrees

Terminal Splits

Design Mode

GitHub & Linear, Native

SSH Worktrees

Annotate AI Diffs

Drag Files to Agents

Orca CLI

Supported Agents

Install

Desktop — macOS, Windows, Linux

Mobile Companion — iOS, Android

Community & Support

Developing

Signed Builds

License