mirror of
https://github.com/stablyai/orca.git
synced 2026-10-09 08:02:35 +00:00
Jinwoo Hong
bfcbcfd59c
* refactor(terminal): move the topology revision and leaf-lookup helpers into terminal-topology
advanceTerminalTopologyRevision, findTerminalTabIdForLeaf and
hasHostAuthoritativeTerminalMembership move verbatim from the renderer-save
membership rebase into persistence/terminal-topology, the home of the commit
boundary. Importers are repointed; no behavior change.
* test(terminal): test-only guard for topology writes outside the commit boundary
The three session sinks now publish through one commitWorkspaceSessionPartition
helper, which hands the prior and published partition to the topology write
guard. Production never arms the guard, so each sink pays one global lookup.
The unit suite arms it in report mode: a sink write that changes class-(a)
topology (membership, root, bindings, titles, incarnations, sleeping records,
remote session ids, tombstones, default-applied, revision) outside a commit
scope is attributed to its writer's file by stack, and fails the test unless
the writer is on the unrouted-writers allowlist that later routing PRs shrink.
Renderer saves and test seeding are exempt. Deep-freeze is available but stays
off suite-wide until the in-place writers return new sessions.
* refactor(terminal): add the topology commit module with bindLeaf, closeLeaf and closeTab
terminal-topology-commit.ts is the boundary for class-(a) terminal topology.
bindLeaf forwards to persistPtyBinding, whose write now runs in a commit
scope; the spawn commits and the relay reattach bind through it. closeLeaf and
closeTab wrap the existing close mutation in a commit scope and one
persistence.terminal-topology span (kind, outcome, refusal reason; no ids),
and the runtime close goes through them. Session output is unchanged: tests
compare it byte for byte with the old writers for local, ssh: and folder
workspaces.
* chore(terminal): drop an unused lint suppression from the topology write guard
* fix(terminal): attribute topology guard writers relative to the repo root
The guard read a frame's file through its last /src/ segment, so a test under
tests/ (folder-upgrade-identity-persistence.unit.test.ts) had no source frame
and failed as an unknown writer. Frames are now taken relative to the repo
root the setup passes in, tests/ counts as test seeding, Windows backslashes
are normalized before the node_modules skip, and nested src/ paths keep their
full path. The two runtime funnel files skip only their funnel function, so
another writer in them still shows. The R9 allowlist key names the file whose
frame actually writes. The class-(a) diff and the attribution move into their
own files; the stack limit is restored in a finally.
* refactor(terminal): drop bindLeaf until binding reaches a sink; add the boundary ratchet
bindLeaf and the commit scope inside persistPtyBinding changed nothing: the
binding write never reaches a session sink, and a scope inside the Store method
would have admitted every direct caller once it did. Both return in B1-4; the
spawn commits and the relay reattach call persistPtyBinding directly again.
The runtime close now calls one closeLeafOrTab entry, so its callbacks keep
their contextual types. A census test is the primary enforcement: only
persistence/terminal-topology and the callers it lists may call
persistPtyBinding, the session setters or the three sinks, and every
unrouted-writer allowlist entry must name an existing file.
* fix(test): resolve the topology guard's repo root without the global URL
Under happy-dom the global URL is not Node's, so fileURLToPath(new URL(...))
threw in the setup file and failed every happy-dom test file.
* feat(terminal): moveLeaf commits a pane detach in main before its new tab mounts
Ported from fix/terminal-topology-stage-a (1bafc87, 3941bd4, 2ea2070, 3e79f31,
a9d428e minus the bridge comment) and exposed as the commit module's moveLeaf,
which runs inside the topology commit scope and span and publishes every
rewritten partition through the session sink, so the test-only write guard sees
it. Store.moveTerminalLeafToNewTab only hands it the store's state.
Detach-to-new-tab now asks main first: the leaf and its binding move into the
new tab in every owner partition (local and ssh:), with the incarnation,
sleeping session, remote session id, UI marks and SSH lease, and the topology
revision bumps. pty:moveLeafToNewTab then aliases the agent-status pane key and
re-keys orchestration worker resources; the renderer's repeat transfer is
skipped. A refused or failed move toasts and the pane stays; a move the
renderer cannot apply is undone (STA-9259).
Stage A review-2 fixes:
- SF1: an undo whose source tab has closed retires the moved tab instead of
refusing, so no ghost tab comes back on restart.
- SF2: an undo restores the split direction, ratio and position, the source
tab's PTY id and its SSH remote session id, from origins main kept for the
move; it never adds a second copy of a leaf the source holds again.
- N1: layouts of tabs that no longer exist do not refuse a move.
- N2: an undo into a tab that gained a pane is refused as target_changed,
not a silent not_held.
- N3: a repeat drop of a pane whose move is still committing is a no-op.
Note: the move bumps the topology revision, so a revision-0 repo enters
rebased membership on its first detach.
* fix(terminal): tighten moveLeaf undo and move across disagreeing SSH copies
- An undo ignores a target layout whose tab row is gone, as the move does.
- A retired undo leaves UI marks and SSH leases on the moved pane key instead
of re-keying them to the closed source tab.
- When an SSH respawn bound one partition before the other caught up, the move
follows the renderer's live PTY id and drops the stale copy's incarnation
instead of refusing with a toast.
- A test pins the late-spawn graft the renderer's in-flight guard exists for.
* fix(terminal): a pane move the renderer cannot finish never leaves main holding it
- A pane whose PTY spawn is still in flight is not dragged out (no toast):
the late spawn result would bind it to the source tab and graft the leaf
back beside its moved copy. The IPC transport reports a pending connect.
- A thrown or timed-out commit (10 s bound) sends an undo, since the write may
have landed; undo answers not_held when nothing moved. The in-flight entry
clears with it, so a stalled main cannot wedge the pane's drag.
- A throw while opening the new tab after the pane left its source undoes the
move too.
- No "stays where it was" toast when the undo found the source tab closed or
the source pane is gone; a failed undo says the pane may open in a new tab
after a restart instead.
* fix(terminal): drop a half-opened move tab so the window agrees with main's undo
If opening the moved pane's tab throws after createTab ran, the renderer now
closes that tab without killing its PTY or telling main (main never had it),
and restores the source layout, while main undoes the move.
* refactor(terminal): drop the runtime topology write guard; the boundary ratchet enforces
The AST boundary ratchet is the enforcement for B1. The stack-attributed
runtime guard, its class-(a) diff, the unrouted-writer allowlist, the vitest
setup and the freeze option are removed; it saw two writers in the whole unit
suite and its real value starts only once binding reaches a sink (B1-4).
Also: one closeLeafOrTab wraps the close in the span (no per-kind copies or
narrowed types), the span has one finish like persistence.pty-binding, the
sink helper is publishWorkspaceSessionPartition (it publishes; the commit
boundary is the module), the ratchet drops the private publishSession row and
checks that every listed caller file exists, and the close comparison keeps
its two meaningful cases with span cases chosen by name.
* refactor(terminal): roll a pane move forward instead of undoing it
Once main commits a pane move, the renderer only rolls forward:
- A repeat of a committed move answers moved and writes nothing, so a thrown
commit (outcome unknown) is retried, up to three attempts; the IPC skips
the agent-status transfer it already made.
- The renderer applies the move by leaf id. If the user closed the pane or
its tab meanwhile, it closes main's new tab through the ordinary
session:close-terminal-surface path; if a sibling closed and the pane is
the source's last, the source tab closes without killing the PTY.
- One toast, for a move main refused or never answered.
Deleted: the undo planner, origin ledger, undo flag, retired and
target_changed results, the commit timeout, the half-opened-tab cleanup and
the second toast.
Also: one request validation (distinct tabs, stable leaf id, tab ids a pane
key can carry, built through makePaneKey); a two-line PTY check where the
live PTY id wins; the move and close share one span wrapper; the moved tab's
layout always takes the live PTY id (a stale saved id was kept before);
fallbackPtyId is now livePtyId; tests are organized by behavior.
* refactor(terminal): trim the B1-1 commit module and ratchet to what they enforce
- Point the acknowledged-tab-retirement audit fixture at the moved
advanceTerminalTopologyRevision; its old import no longer resolved.
- Drop publishWorkspaceSessionPartition: it was the removed guard's
interception point, so the three session sinks return to origin/main.
- One traced(kind, mutate) wrapper in the commit file replaces the span
factory; closeLeafOrTab is one call.
- The ratchet walks src/main with the shared scanSourceTree, drops the
loading-store-internal rows and the redundant file-exists test; exact-set
equality already fails on a missing file.
- The commit test is a pure unit test of the span outcomes: no Store
harness, electron mock or self-comparing close.
* fix(terminal): keep a moved last pane alive and trim moveLeaf to one attempt
A sibling closed while main committed the move persists the source layout
down to the moved leaf, so the renderer took that for "pane gone" and
closed main's new tab while the pane was live: after a restart it was held
nowhere. The renderer now reads the store layout: when the moved leaf is the
only one left it opens the new tab with that layout, syncs PTY ownership,
and closes the source tab without killing the PTY. Main's new tab is closed
only when main moved the pane and it is gone here.
Also:
- One commit attempt; the repeat answer, the retry loop and the IPC alias
guard never ran in production (a write with an unknown outcome faults the
writer, so every retry rethrows before it reaches the move).
- traced takes a typed refusalOf; one write-and-restore helper and a shared
partition assign replace the duplicated local/remote and rollback checks.
- The planner's holders carry their source tab and layout, so the partition
move cannot fail; pane-keyed UI marks are re-keyed in one loop; the request
validator calls makePaneKey directly.
- applyMove looks the pane up once and takes one PTY id (main's when it moved
the pane); the move-commit file is inlined; duplicated renderer tests are
removed and the commit-path tests live together.
* refactor(terminal): census the runtime session controller's write and drop stage ids from comments
The controller's setter was named set, which the boundary census could not
list without matching every Map.set, so a new OrcaRuntime mixin could write
sessions through it unseen. Rename it setForWorktree and census it.
Comments now describe state instead of citing plan stage ids.
* refactor(terminal): census writer references and trace refusals by callback
- traced() takes refusalOf instead of assuming an Error refusal, and only
mutate() sits in the try, so a span outcome of threw means the write threw.
- The boundary ratchet counts references, not just direct calls: non-null
calls, bracket keys, aliases, destructures, .call/.bind and parenthesized
callees all count; declared names and type positions do not.
- Census terminalSurfaceCloseMutation (boundary-only) and the partition sinks
setLocalWorkspaceSession / setHostWorkspaceSession.
* test(terminal): count writer uses in extends clauses and instantiations, skip type-only imports and local declarations
The census skipped ExpressionWithTypeArguments as a type, which also holds
`extends f(x)` and `x<T>` value expressions. Type-only import/export
specifiers and declared names (variables, parameters, accessors, enum
members) no longer count as uses. The audit fixture is listed in the table
instead of a separate exemption.
* test(terminal): count quoted and assignment-pattern destructures of layout writers
* test(terminal): count every mention of a layout writer except its definition
Telling definitions from uses per syntax kind kept missing nested and
for-of destructures. Exempt only the writer's own function or class-member
definition; any other mention (including object-literal keys) counts, so the
census errs toward a loud false alarm rather than a silent miss. Quoted names
count only in member-name position.
* test(terminal): count every string literal naming a layout writer
Member-name positions missed wrapped keys like store[('name')] and
store['name' as const]. Counting every string literal outside types is
shorter and errs toward a loud false alarm.
* test(terminal): exempt only class members and functions as writer definitions
Object-literal methods and accessors were exempt while equivalent arrow
properties counted; all object-literal keys now count alike.
* test(terminal): parse files with unicode escapes in the writer census
A name spelled with a \u escape never appears verbatim, so the text
prefilter skipped it.
* test(terminal): parse any file with an escape in the writer census
\x, identity and line-continuation escapes also decode to a writer name
without it appearing verbatim.
* test(agent-hooks): stub isPaneAuthorityTransferredTo on the hook server fake
* refactor(terminal): one move path for every client and an idempotent status transfer
The pane manager decides whether the dragged pane is the last one, and a
refused detach closes main's new tab like a vanished pane. Paired web
clients answer the move as not held, so every client takes the same
moved / not_held / refused branch. Repeating an agent-status transfer that
is already in place is now a no-op where it happens, replacing the IPC
special case.
* fix(lint): bring structured-agent-session-host back under max-lines
(cherry picked from commit 1a5f687244)
Orca
中文 · 日本語 · 한국어 · Español · Français · Português
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 CompanionMonitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere. |
 |
Parallel WorktreesFan one prompt across five agents, each in its own isolated git worktree — compare the results and merge the winner. |
 |
Terminal SplitsGhostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts. |
 |
Design ModeClick any UI element in a real Chromium window to send its HTML, CSS, and a cropped screenshot straight into your agent's prompt. |
 |
GitHub & Linear, NativeBrowse PRs, issues, and project boards in-app — open a worktree from any task and review without a context switch. |
 |
SSH WorktreesRun agents on a beefy remote box with full file editing, git, and terminals — auto-reconnect and port forwarding included. |
 |
Annotate AI DiffsDrop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Orca. |
 |
Drag Files to AgentsVS Code's editor with autosave everywhere — drag files or images straight into an agent prompt. |
 |
Orca CLIAgents drive Orca too — script every workflow with |
 |
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
- Running
orca serveon a headless Linux server? See the headless Linux server guide.
Or via a package manager:
# macOS (Homebrew)
brew install --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 0.0.52 · 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 11.
-
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 sponored/provided by SignPath.io, certificate by SignPath Foundation.
License
Orca is free and open source under the MIT License.