[OrcaWin]

	Files	Added	Deleted	Net
Test	146	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​6780	$\color{#cf222e}{\Huge{\mathbf{−}}}$​505	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​6275
Prod	301	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​4956	$\color{#cf222e}{\Huge{\mathbf{−}}}$​1199	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​3757

ELI5

Phase 3.5 fixes the SSH and remote-server bugs that hurt the most people, at their root cause instead of one symptom at a time. We went through all 1,501 open issues and grouped them into 40 root-cause clusters rated P0 or P1. To keep this landable, the scope was cut to the 4 P0 clusters plus 9 high-reach "P0.5" clusters. The other clusters are parked for later phases. This PR lands the 14 fix PRs below. Twelve came from the triage. Two more (#26424 and #26433) fix problems the integrated real-host test found. Each was reviewed and merged on its own into the OrcaWin/phase35 integration branch, except the CI fix (#26335), which went straight to main.

What Changed

Each section gives the before and after as the user sees it, the mechanism that changed, and why that approach was picked.

1. One owner for a remote pane's reconnect (#26308)

• Before: after a network hiccup, a terminal on a remote machine could spin in "connecting" forever, lose what you typed, or reload itself over and over. Two parts of the app both thought they owned reconnecting, so they raced.
• After: the connection to the remote machine owns reconnecting, and the pane waits for it. If the host says the terminal is gone, the pane ends cleanly. Keys typed while the same terminal recovers are held and delivered once, in order. If the pane comes back on a different shell, they are dropped so they never run in the wrong shell.
• Mechanism: the remote pane lookup now answers resolved | absent | unavailable instead of null, and every attach path reaches a final state. The connection reports ownsRecovery(), and the pane-level remount paths step aside while it does. The held keys reuse the existing pre-connect input buffer.
• Why: each symptom came from one specific wrong exit path or from two owners of recovery. Fixing those paths directly was much smaller and safer than rewriting the transport's state flags. Only the host's own "not found" counts as the terminal ending; lost contact never does. Renderer-only, no wire change.

Fixes #21344
Fixes #25784
Fixes #20802
Fixes #21195
Fixes #20159
Fixes #20923
Fixes #18495

2. The orca command on an SSH host is a guest, not the owner (#26337)

• Before: the orca command inside an SSH terminal had the owner's full power over the local app. From a sandboxed VM it could read and type into your local terminals, drive your other SSH hosts' terminals, and click and type on your Mac with orca computer.
• After: by default it only sees and uses its own host's terminals, and a worker there can still report back to the coordinator that dispatched it. One per-host switch (Settings → SSH → host → Advanced) gives it more, but never desktop control, accounts, settings writes, skill installs, pairing, SSH connections, updates or network tunnels.
• Mechanism: every RPC method now declares a permission (workspace, desktop-control, accounts-admin, settings-write, skills-admin, pairing-admin or host-admin), and the field is required, so a new method without one fails the typecheck. One check in the RPC dispatcher compares it with the caller (owner, phone, paired client, or SSH bridge) on every transport. The SSH bridge no longer gets the owner token: each invocation gets a short-lived credential bound to that SSH target, revoked when the command exits. Paired clients get an explicit allowlist.
• Why: the root cause was not one method, it was that the bridge authenticated as the owner with no policy on that path. Per-method checks are easy to forget and cannot tell an SSH guest from the owner's own CLI. Nothing new crosses the wire.

Fixes #23835
Fixes #25259

3. Terminal daemon: clean launch environment, safe message handling, socket path that fits (#26306)

• Before: on Linux and SSH hosts, four things could quietly kill every terminal: Chromium's DBUS_SESSION_BUS_ADDRESS=disabled: leaked into the daemon and every shell; the daemon used a systemd scope that dies ~10 s after the last SSH login when lingering is off; one malformed client message crashed the whole daemon; and a long data folder made the socket path too long, so terminal persistence was silently off.
• After: the disabled: marker is dropped (a real address is kept). The scope is used only when lingering is on or Orca already runs inside the user manager; otherwise Orca logs daemon-scope-unavailable: linger off with the fix. A bad message closes only that one connection. A socket path that would overflow moves to a private, validated directory under /tmp.
• Mechanism: one env helper used by every env builder; a loginctl linger check; small type guards on the hello and request envelope plus a .catch on dispatch; getDaemonSocketPath relocates only on overflow and validates both directory levels before any connect.
• Why: each fix sits where the daemon is launched or talks to clients, so it covers every caller. Requiring linger outright would have removed restart protection from desktop users. Relocating only on overflow leaves every existing host on its current path. No wire change.

Fixes #25580
Fixes #21119
Fixes #24201
Fixes #17841
Fixes #17840

4. Remote scrollback survives reconnects (#26319)

• Before: in a terminal on an SSH host or paired server, scrolling up often found nothing. A desktop client got only the current screen, and every repaint from the server (reconnect, reopening a tab, dropped output) first erased the client's own history.
• After: desktop clients receive up to 1,000 rows of history when they subscribe, like phones already did. A repaint that carries no history repaints only the screen and keeps everything above it. A repaint that does carry history still replaces it, so nothing is duplicated.
• Mechanism: the host sends every subscriber through the existing row ladder (1000 → 0) and adds an optional scrollbackRows field to the snapshot-start frame. The client leaves out the clear-scrollback sequence when that field is missing or 0.
• Why: one new optional field, no new opcode, so mixed versions work in both directions. Sending full history on every overflow recovery would grow the frame that is trying to catch up, and would still erase anything older than 1,000 rows.

Fixes #14593
Fixes #20158
Fixes #6106

5. An SSH terminal no longer freezes after an abandoned catch-up (#26341)

• Before: if Orca gave up on replaying missed output for an SSH terminal halfway (for example when a worktree was revealed during a reattach), the terminal froze for good. The remote program sat blocked on write() until Orca restarted.
• After: the terminal keeps flowing; output already shown stays.
• Mechanism: SSH output is flow-controlled with credit. A canceled delivery left a bookkeeping entry that every later "drawn" receipt tripped over, so credit was never returned. The output ledger now ignores settle and transfer calls for a delivery that is already closed.
• Why: dropping the entries early would return credit for output not yet drawn. A no-op for a closed delivery keeps per-span accounting exact and covers every path that closes a delivery. Client-only, no wire change.

Fixes #24367

6. Removing a project only touches the host you picked (#26340)

• Before: the same project can exist on two machines with one ID. Removing one copy sometimes looked the project up by ID alone and removed the other machine's copy, killing its terminals and purging its workspaces.
• After: every removal names its host and matches that host's row exactly. If that host has no row, nothing is removed.
• Mechanism: the host is now required in the removal type, so the compiler rejects any caller without one; the callers it found (cloud-VM cleanup, group deletion, the sidebar) were fixed. The saved catalog refuses an ID-only removal when two hosts share the ID.
• Why: the root cause was the bare-ID fallback, not one caller. Making the host required closes the whole class instead of guarding callers one by one. No wire change.

Fixes #13071

7. orca serve loads SSH hosts, and Quit on a serve window only closes the window (#26348)

• Before: orca serve never loaded its SSH hosts, so paired clients saw an empty list and ssh.connect failed. Quitting a desktop window on a machine running orca serve stopped the whole server and dropped every paired client.
• After: a serve whose profile has SSH hosts runs on the host that loads them, and they work. Under serve, every Quit route (menu, Cmd-Q, tray, Dock, app switcher) closes the desktop windows only; signals, updates and shutdown still exit.
• Mechanism: the Electron serve registers the SSH layer before it starts listening. Serve host selection reads the profile read-only and picks the Electron host when it has SSH targets (failing closed to Electron if it cannot tell). A macOS before-quit guard cancels unmarked quits; every process quit Orca starts is marked. Serve now reclaims SIGINT/SIGTERM/SIGHUP from Electron's native handler.
• Why: porting the SSH stack to the headless server is a separate project (about 14 modules import Electron), so picking the host that already works fixes it today. Marking process quits is the only way to tell them apart from a user quit on macOS.

Fixes #15537
Fixes #25886

8. Agent session history works on headless server hosts (#26309)

• Before: on a host running the headless Orca server, the agent session history panel was always empty with "The session scanner is missing from this Orca install."
• After: it lists the host's Claude, Codex, Gemini, Cursor and OpenCode sessions.
• Mechanism: the server build now builds every helper process from one list, and the scanner is on it and in the shipped-artifact manifest, so a missing file fails at startup instead of at first use. The "where is the helper" lookup now decides by "is there an app archive", in one shared helper, instead of "is it packaged". The build smoke-tests the scanner.
• Why: running the scan inside the server would put large transcript parsing on the loop that serves terminals. Shipping the existing helper reuses its protocol unchanged.

Fixes #24105

9. ARM Linux servers stop dropping clients every 15 seconds (#26200)

• Before: on some 64-bit ARM Linux machines (Raspberry Pi 4, OrangePi 5), every connected desktop and phone dropped and reconnected at each 15-second heartbeat.
• After: connections stay up.
• Mechanism: a pnpm patch to ws@8.22.0 writes an empty frame as one write (the header) instead of the header plus a zero-byte write, which fails with EFAULT on those kernels under Electron and kills the socket. The bytes on the wire are identical.
• Why: fixing only Orca's own heartbeat would leave the library's automatic reply to older and third-party clients' empty pings broken. One fix at the single place that writes covers both.

Fixes #19876
Fixes #20673
Fixes #23398

10. The terminal tail stays cheap under redraw floods (#26316)

• Before: a full-screen agent that redraws many times a second over SSH (Pi's ask_user panel) could pin the main process at 100% CPU and freeze Orca, and a restart replayed the output and froze it again.
• After: updating the main process's short text copy of each terminal (used for previews, terminal read and agent-wait checks) costs about as much as the new output. The retained text is unchanged.
• Mechanism: rows stay flat strings written one run at a time with cached trimmed text; rows over the line cap are dropped in batches; the redraw window uses the cursor's net reach rather than the sum of every cursor-up.
• Why: making the model linear fixes every path that feeds it (SSH, local, restore). Clamping row width was rejected because it would change what terminal read returns. No wire change.

Fixes #11315

11. The SSH relay fallback runs Orca's own Node first, never a host npm install by default (#26303)

• Before: when Orca could not run its managed server on an SSH host, the relay fallback used the host's own Node.js and compiled terminal support there with npm. That needs a compiler, internet, a POSIX login shell and working npm, and many hosts have none, so users saw "relay cannot find node-pty" and failed connects on offline or non-admin hosts.
• After: the fallback first tries Orca's pinned Node with prebuilt add-ons (then a glibc 2.17 compat runtime, then a host Node 18+ with prebuilds, no npm). Wherever one runs, nothing is compiled on the host. If all three are refused, the connect does exactly what it did before, marked "unsupported configuration" on the host card. Plain SSH terminals plus SFTP are used only when that old path itself answers with a failure.
• Mechanism: the default relay runtime is now pinned-node. A step down happens only on an answer from the host; lost transport stays retryable. Refusals the user can fix (missing library, security software, Windows application control) are remembered for 24 hours. NixOS's stub loader is classified so the connect steps on to the host's Nix Node.
• Why: the rule is "no host does worse than before this PR". A table test checks it across 1,680 host combinations plus named review cases.

Fixes #20386
Fixes #22159
Fixes #23554
Fixes #24226

12. orca serve and orca open use the profile you chose (#26424)

• Before: ORCA_USER_DATA_PATH=<folder> orca serve checked that folder to decide how to serve, then started Electron on the default profile. A packaged Orca reads only --user-data-dir. If your own Orca was open, the new server hit its single-instance lock, asked it to show its window, and quit. orca open had the same split, and on macOS it brought your running app to the front.
• After: the chosen folder is the folder the server and app use. A serve that ends up on any other profile prints why and exits before it takes the instance lock, so it never contacts another Orca. On macOS, a non-default profile opens as a new instance; the default profile reopens exactly as before.
• Mechanism: the CLI resolves the profile once, as an absolute path, and passes it to the serve selector, to orcad, and to Electron as --user-data-dir (dev builds also get ORCA_DEV_USER_DATA_PATH). It also passes ORCA_SERVE_USER_DATA_PATH, which Electron compares with its settled profile before the lock, then removes so terminals don't inherit it.
• Why: pinning at launch fixes the actual split. The check before the lock is the safety net if a future launch path forgets to pin. Making Electron honor ORCA_USER_DATA_PATH on its own was rejected: Orca terminals pass that variable down, so a desktop app launched from one would take over another instance's profile.

Found by the Phase 3.5 integrated test (finding F4); there is no GitHub issue.

13. Open terminal tabs reattach after a managed server update (#26433)

• Before: after a managed server update that restarts it while terminals are open (for example orca environment update --environment <host> --force), every open terminal tab showed "Remote runtime disconnected — Automatic retries stopped" and dropped typed keys. Reconnect, switching tabs and SSH disconnect/connect did not help; only quitting Orca did. The terminals on the host were fine the whole time.
• After: open tabs show "Reconnecting to remote runtime" for a few seconds, then reattach to the same running terminals with their scrollback, and typed keys reach the shell.
• Mechanism: the update gives the server a new pairing. Each tab used to pin the pairing it opened with and treat "pairing changed" as fatal. Now a tab moves to the new pairing only when the saved environments prove it is the same machine (same SSH host registration and the same server host key). It treats the refusal as lost contact and retries within its normal limit. Streams still on the old pairing are closed as recoverable drops instead of silently refusing to send. If the same environment id now points at a different machine (new host key), its terminal streams end before the new pairing is published, and tabs never retry on it. The renderer also ignores a 0×0 size hold from a server that just restarted, which used to shrink the visible pane to one cell.
• Why: rotating the pairing is how a re-paired server is fenced, so terminal tabs now follow it the way other parts of the app already do, but only when it is proven to be the same machine. Lost contact never marks a terminal exited. Renderer-only, no wire change. This was not a Phase 3.5 regression: the pinning already existed in Phase 3.

Found by the Phase 3.5 integrated test (finding F2) and re-verified on a real host; there is no GitHub issue.

14. CI: apt off the Azure mirror (#26335)

• Before: E2E jobs failed intermittently installing build tools, because apt kept fetching from a flaky mirror. The redirect only edited the source lists, but current Ubuntu runner images read mirrors from /etc/apt/apt-mirrors.txt.
• After / mechanism: the step also rewrites that mirror list and retries the install once with --fix-missing.
• Why: it fixes where the mirror comes from, not just adds retries. This one merged straight into main, so it adds no diff here.

Elegance pass (merged)

After the fixes landed, a cleanup pass made 22 verified refactors across the Phase 3.5 areas, for −407 net lines. None changes behavior: each was checked against the existing tests and reviewed clean. All five PRs are merged into the integration branch:

PR	Area	Added	Deleted	Net
#26474	SSH relay runtime ladder	245	456	−211
#26471	RPC caller permissions	158	153	+5
#26470	Remote pane binding	115	180	−65
#26465	Terminal tail	31	68	−37
#26478	Serve, daemon and misc. Also deletes the id-only repos:remove IPC and Store.removeProject, now that every caller removes a project by host	280	379	−99

Why

Most of these bugs had been patched symptom by symptom before and kept coming back. Each fix here targets the shared cause behind a cluster of issues, keeps the client and host compatible across versions (only optional fields, no new stream opcodes), and follows the SSH rule that losing contact is never treated as proof that a process ended.

Review loop. Every fix PR was reviewed by both Opus and Astra, looking only for P0 and P1 problems, and every PR was clean at its final head before merging into the integration branch. Some took several rounds: #26303 took 8 rounds to reach the "never worse than before" rule across every host type, and #26316 took 4.

Known limits (from the PR bodies):

• Paired clients keep the standard admin set (workspace, settings-write, accounts-admin, skills-admin, host-admin) because the remote desktop UI calls into each. Narrowing it (for example skills.install or settings writes of agentDefaultEnv) needs a pairing-time grant UI, so Gate privileged RPCs the same way host-only account APIs are gated #18269 stays partly open. Paired clients lose orca computer until re-paired with --grant-desktop-control, and lose relay, pairing and push administration, which only phones use.
• SSH hosts on the relay route lose cross-host control until the user turns on the per-host switch.
• fix(ssh): relay fallback runs Orca's pinned Node by default, never a host npm install #26303 departs from the original decision. The decision said a refused third rung should go to plain SSH, never a host npm install. Review found host types where that is worse than before, so the host-npm path stays as a last resort, marked unsupported, and is never tried first. A cached runtime that passes its version check but whose relay fails after launch still fails the connect, so a second relay is never started beside one that may be running. The Windows warm-check PowerShell was not parse-checked locally.
• fix(serve): load SSH targets on a headless serve; a user Quit only closes serve-hosted windows #26348: on an explicit ORCA_SERVE_RUNTIME=orcad, SSH targets are still not loaded, and targets added from a paired client take effect after a serve restart. Routing Add Project / SSH management to the paired server ([Bug]: Paired Desktop cannot manage or use headless server SSH targets #8489) is still open.
• fix(terminal): remote snapshot replay keeps scrollback it cannot replace #26319: remote history beyond 1,000 rows ([Bug] Improve scrollback size #11560) and keeping parked remote scrollback across a client restart (Parked remote terminal scrollback is not persisted across a client restart #21295) are not covered.
• fix(daemon): clean launch env, validate client frames, fit the socket path #26306: the exact systemd-run refusal from [Bug]: orca serve under systemd: durable daemon scope launch fails (DBUS_SESSION_BUS_ADDRESS=disabled: reaches systemd-run --user), so restarts SIGKILL every PTY again (regression of #19408) #25580 was not reproduced (the variable is removed either way); a full packaged server deploy over SSH with a long home path was not run.
• fix(ssh): keep crediting a PTY after its recovery delivery is canceled #26341: the related stall when a hidden renderer stops parsing ([Bug]: SSH relay PTY backpressure has no stall bound while the owner client is alive but its renderer is not consuming #23392) is left out.
• fix(projects): remove a project only on the host the user picked #26340: GitLab tasks on a remote host ([Bug]: GitLab Tasks fail with "Access denied: unknown repository path" for repos on a remote host #14603) have a different cause and are not included.
• Found by the integrated test and parked: keys typed on a half-open link, before Orca notices the drop (51 s in the test), are lost without any message (F1; not a regression). Terminals on managed server hosts have no orca CLI on PATH, so fix(rpc): deny-by-default caller permissions and a scoped SSH bridge credential #26337's bridge applies only to relay-route hosts (F3).
• fix(remote-runtime): open terminal tabs reattach after a managed server update re-pairs the host #26433: a server that adopts a terminal from an older daemon still sends a 0×0 size hold; the client ignores it, and fixing it on the host side is a possible follow-up.
• fix(remote-runtime): stop arm64 Linux servers dropping clients every heartbeat (empty WebSocket write EFAULT) #26200 was not verified on a real 39-bit-address ARM kernel; the upstream ws report is a follow-up.
• fix(terminal): keep the main-process terminal tail linear under TUI redraw floods #26316 was not run on a real host (it needs a live Pi model account).

Linked Issue

All Fixes lines are listed under each section above.

Visual Proof

N/A. The only UI changes are one switch under SSH host → Advanced (#26337) and the "unsupported configuration" notice on the SSH host card (#26303). Everything else is connection, process and packaging behavior, covered per PR by tests and the real-host runs described in each PR.

Testing

Integrated real-host test (2026-10-08): 8 of 9 scenarios passed. It used packaged macOS arm64 builds of the integration branch at three heads, against fresh Debian arm64 SSH containers, on both the managed-server and relay routes. Apps ran hidden with an isolated home and profiles.

#	Scenario	Result
1	Fresh SSH host becomes a managed server host	Pass (12.6 s)
2	Three terminals through a killed connection and a 55 s network outage: no stuck panes, input typed after the drop is noticed delivered exactly once, full scrollback kept (#26308, #26319)	Pass
3	Full-history redraw flood (50 MB + 600 repaint frames) on the managed and relay routes (#26316, #26341)	Pass: no main or renderer stall over 250 ms. With #26316 the main-thread worst case fell from 82 ms to 5 ms, and the flood drained 3× faster
4	orca CLI inside an SSH terminal, opt-in off and on (#26337)	Pass on the relay route
5	Two hosts with a same-id project: removing one keeps the other (#26340)	Pass
6	Headless serve with saved SSH targets, paired client connects (#26348)	Pass
7	Agent session history on a managed server host (#26309)	Pass
8	Phase 3 smoke: SSH host card, Move to managed server, server update	Card and Move pass. Update failed (F2): open tabs stayed disconnected until restart. Fixed in #26433 and re-verified on a real host: after a forced update the pane reattached in about 5 s, and text typed 15 s and 45 s later ran on the host
9	Relay route on a host with no Node and no compiler (#26303)	Pass: ran on Orca's pinned Node, with zero npm, node-gyp or compiler calls

Other findings: F4 (orca serve started Electron on the default profile instead of the one it checked, and reached the user's running app) is fixed in #26424. F1 and F3 are parked; see Known limits.

Per-PR testing is in each linked PR. Each fix PR's new tests were confirmed to fail without its fix. The branch was synced with main in #26419 (all 66 CI checks green) and again in #26529, up to main at 8ae5264. Main's terminal redraw change (#26118) overlapped #26316: Phase 3.5's row model was kept, and main's new heap test drove one port (erase-to-end now copies a short kept prefix). pnpm tc, oxlint, check:code-quality:changed, audit:anti-slop and the affected suites pass.

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

AI Disclosure

Review

Both Opus and Astra reviewed every fix PR (P0/P1 only); all were clean at their final heads.

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Security: RPC calls are deny-by-default for every non-owner caller; the SSH guest credential lasts one command.
• Cross-platform: linger and scope logic is Linux-only; socket relocation covers Linux and macOS; Windows hosts get rung A of the relay ladder and otherwise keep the old path; the native-quit guard is macOS-only.
• Remote SSH and mixed versions: only optional fields cross the wire; older clients and hosts keep working.
• Mobile: unchanged behavior; phones benefit from the ARM heartbeat fix and stable remote panes.
• Performance: the terminal tail is linear; desktop subscribes send up to 512 KiB of history (the existing phone budget).

Checklist

• This PR is small and focused (it is the Phase 3.5 integration branch; each fix was reviewed as its own PR)
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

Merge after the integrated real-host test and full CI are green.

[coderabbitai]

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}