mirror of
https://github.com/stablyai/orca.git
synced 2026-09-28 00:02:41 +00:00
2afb9a385b
* fix(terminal): damp park-verdict churn that is too slow to burst
The cold-park verdict flip damper only engaged on a burst: 3 flips inside a 1s
window, a threshold derived from React's 50-commit nested-update bail. The
notice limit — 12 flips in 60s — was explicitly breadcrumb-only, on the
reasoning that churn that slow was never near React's bail and damping it would
spend a mounted pane's memory for no crash-safety gain.
The field disagrees about the cost, though not for the reason first recorded.
WHAT THE BUNDLE SHOWS
Bundle Nz4kzIG_NwLd8KObgjJDKA (v1.4.201, win32) carries 52 park-verdict churn
crumbs. They are two unrelated episodes across four launches, not one run:
L3 09-14 00:53 35 crumbs, 1 tab, 46.9 min, 34 window + 1 burst
L4 09-14 17:07 17 crumbs, 4 tabs, 8.9 min, 17 window + 0 burst
L3's 46.9 min counts a lone trailing burst; the window-triggering run itself is
35.2 min, with an 11.7 min quiet gap before that final burst.
Per-flip cadence is elapsedMs / (NOTICE_LIMIT - 1), not / NOTICE_LIMIT: the
window opens ON a flip, so the 12th sits 11 intervals later. L3 runs 3.19s /
4.63s / 5.44s per flip (min/median/max); L4 runs 3.19 / 3.20 / 5.01.
Across 321 field bundles, 24 carry this churn and all 24 burst at least once —
though those 24 are roughly 17 devices, and 23 of them are burst-only, so the
load-bearing fact is narrower than it sounds: this install is the ONLY one that
ever tripped the window rule, and that is what ran undamped.
WHAT IT COSTS, STATED ACCURATELY
Each flip remounts the pane. A remount does NOT reconnect a terminal: parking
deliberately keeps the PTY alive (terminal-parked-tab-watchers runs a pane-less
byte watcher), SSH restores from main's snapshot, and a remote runtime
re-subscribes a stream on a per-environment multiplexer that outlives the pane.
The cost is a remount each time, indefinitely.
The user who filed wrote "The connection closes, reconnects and again and again
and again all the time. Is a cycle." An earlier draft of this change took that
as the mechanism. It is not: the bundle carries no remote-terminal stream-stall
recovery crumbs, no daemon session churn inside either churn window, and one
pane-recovery remount two hours earlier. And the report was filed in L4, 12.3
minutes AFTER that launch's churn had already stopped. The churn is real and
worth damping on its own terms; the causal link to that sentence is not
established, and this change should not be read as proving it.
THE FIX
The notice limit now engages the same unpark pin the burst does, backing off ×2
per consecutive notice window to an 8-minute ceiling, clearing once a full
window closes below the limit.
Measured closed-loop — driving the pin back into the verdict the way
useTerminalParkVerdictPin does — over 47 simulated minutes, counting pane
remounts, which is the user-visible quantity:
per flip transitions before -> after ceiling reached
3193 ms 884 -> 96 (9.2x fewer) 8x
4627 ms 610 -> 96 (6.4x fewer) 8x
4800 ms 588 -> 96 (6.1x fewer) 8x
5000 ms 564 -> 126 (4.5x fewer) 8x
5442 ms 519 -> 156 (3.3x fewer) 8x
These count verdict TRANSITIONS; a mount/unmount cycle is two, so actual pane
mounts are half each figure. The ratios are unaffected. The harness applies the
pin in the same commit cascade as the flip that caused it, which is what the
hook does and what three rounds of review showed an open-loop harness cannot
see.
TRADE-OFFS AND LIMITS, NONE OF THEM HIDDEN
- This does not fix the driver. Whatever keeps re-proposing the park is still
unidentified; the pin masks the rendered verdict and the driver resumes when
each pin lapses. This caps the remount rate of an oscillation; it does not end
one.
- A pinned pane stays mounted and holds its memory, re-armed while churn
persists. One oscillating per-worktree flag flips every tab in that worktree
in the same pass, so all of them can pin at once. The merged verdict includes
the retention-budget force-park, so a churn-pinned pane can stay mounted
through memory reclamation that was trying to free it — and the reclaimer
records success either way, because its only anomaly breadcrumb fires on a
different condition.
The honest number is a duty cycle, not a ceiling. Measured per cadence:
89.7% of wall time pinned at 3193ms/flip, 84.3% at 4627, 83.9% at 4800,
77.8% at 5000, 69.1% at 5442, with a peak contiguous pin of ~480s. Before this
change none of these cadences pinned at all, so blocked reclamation goes from
roughly 0% to 69-90%. Repo-stated cost is ~2.5MB per mounted pane at the 5k
scrollback default and ~19MB at 50k. This is the strongest form of the
original "memory is not free" objection and the change does not answer it.
- Only the notice path backs off; a burst still takes a flat one-window pin.
The corpus supports leaving it: repeat bursts arrive a median 673s apart
(n=29, grouped by bundle/launch/tab; 356s if physical pairs are deduped), and
1 of those 29 inter-arrivals falls in the band that would mean re-firing the
instant a pin lapsed. That margin is thin — the next gap above the band is
75.3s, 0.3s outside it.
- One hard edge, geometric: reaching 12 flips takes 11 intervals, so churn
slower than 60s/11 = 5454.5ms per flip never reaches the limit at all. The
field's slowest observed episode runs 5441.8ms, 12.7ms inside it. Past roughly
4.7s per flip each window only barely makes the limit, so damping engages
later and the win shrinks from 9.2x to 3.3x — but the back-off reaches the
8-minute ceiling at every cadence measured.
- Crumb volume drops by roughly 6x, a loss of
telemetry sensitivity for the very corpus scan that found this. The surviving
'window' crumbs carry sustainedPinCount, which discriminates sustained churn
better than raw volume did; 'burst' crumbs do not carry it. The detection
method changes either way.
REVIEW: TWO ROUNDS, AND BOTH FOUND THE FIX ITSELF
Round 1 found the back-off never left 1x in production. While a tab is pinned
the hook subtracts it from the rendered verdict, so no flip is recorded and
windowStartMs never advances; by the time a pin lapsed, windowStartMs was always
older than a full window, so the quiet branch wiped sustainedPinCount on the
first pass after EVERY pin. Closed-loop, that shipped 3.6x the remounts
intended. The 24 tests then in the file passed either way, because the harness
was open-loop. A second lens found five wrong claims in the commit message,
including a per-flip divisor of 12 where the code uses 11 — which made the
stated safety margin 37x too generous — and a reconnect mechanism the source
contradicts.
Round 2 attacked round 1's fix and found two more:
- The back-off RATCHETED. The flip path cleared it on `flips < noticeLimit`,
and the notice path leaves `flips` at exactly noticeLimit, so a window
reopening after hours of silence did not clear it. Four isolated episodes
six hours apart reached the 8-minute ceiling — the precise behaviour the
code comment claimed was impossible.
- And it was INERT above ~4.7s per flip, because a lapsing pin knocks the next
window out of alignment so it closes at 11 of 12, which that same
`flips < noticeLimit` test read as the churn easing. At the field's slowest
observed cadence round 1's fix changed nothing at all: 519 -> 346 both with
and without it.
Both come from one wrong question. The reset now asks whether the tab has been
genuinely quiet — a full window with no flip and no live pin, tracked on an
explicit lastFlipMs — or whether the closing window held fewer than half the
notice limit. A window closing at 11 of 12 is neither.
Round 3 found the defect inside round 2's fix, and it was one line. Engaging the
pin IS a rendered verdict transition: the hook drops the tab from the parked
set, the effect re-runs on the changed dep, and that flip lands while the pin is
live — overwriting the future deadline with the current time. The back-off then
cleared one window after the pin STARTED rather than one window after it ended.
Round 3 also showed the residual slow-cadence weakness was this bug and not the
geometry the round-2 message blamed, and that reverting to round 2's threshold
still passed all 31 tests. `lastFlipMs` no longer moves backwards off a live
deadline, and a closed-loop test that records a flip inside a live pin now kills
both that clobber and round 2's threshold.
Round 4 found no defect inside round 3's fix and judged it mergeable. It did
find that the eased-flip clause was itself untested — four mutations of it,
including reverting to round 2's threshold, passed every test — and that the
test whose comment claimed to cover it was satisfied by the other disjunct. A
sparse-churn test (three flips per window, indefinitely: eased but never silent)
now separates the two and kills all four.
Also from the review rounds: two separate dead clauses in this function, one
added by each of the previous two rounds, are gone; the burst-interval median in
the shipped comment was one row off (673s, not 732s) and n is 29, not 30. That
median is grouping-fragile — 702.7s by (bundle,tab), 356.1s deduped — but the
facts it supports are not: 1 value in the 59-75s band under every grouping, and
the next gap above it is 75.3s.
Known and not fixed: a tab churning continuously at 6-10 flips per window sits
in the gap between both reset conditions and holds its back-off indefinitely, so
the next notice after it speeds up pins for the ceiling rather than one window.
Stated rather than fixed: because quiet is measured from the pin deadline, a tab
at the 8-minute ceiling needs roughly nine minutes of real silence before the
back-off clears, not one window. The record's doc says so.
* test(terminal): check churn breadcrumb values without assertions
* fix(terminal): let sustained churn pins yield to retention eviction
* test(terminal): preserve an existing burst pin during forced eviction
* test(terminal): verify sustained churn pin expiry and cleanup
---------
Co-authored-by: m4air <m4air@Mac.localdomain>
Co-authored-by: m4air <m4air@m4airs-Air.localdomain>
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
ZCode
OpenCode
MiMo Code
Amp
OpenClaude
Antigravity
Pi
oh-my-pi
Hermes Agent
Devin
Goose
Auggie
Autohand Code
Charm
Cline
Codebuff
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 or join TestFlight
- Android: Download APK 0.0.50 · 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 10.
-
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.