[nwparker]

	Files	Added	Deleted	Net
Test	10	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​577	$\color{#cf222e}{\Huge{\mathbf{−}}}$​2	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​575
Prod	35	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​476	$\color{#cf222e}{\Huge{\mathbf{−}}}$​25	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​451

ELI5

On Windows, Orca can run your projects inside a WSL distro (the "WSL host", behind an internal switch). A distro has one Orca server per Linux login, so if you run two copies of Orca (say stable and dev), both use the same server. Until now, removing the WSL host in one copy shut that server down and closed every terminal on it, including the ones the other copy was using. Now Remove first asks whether another Orca is connected to that server. If one is, Remove only lets go of it from this copy and leaves everything running.

What Changed

Before: Remove on one Orca closed every terminal on the distro's server and shut it down, even while another Orca was using it.
After: Remove asks the server whether another Orca installation is connected right now.

• Yes: this Orca closes only its own connection and drops the host. The server and its terminals keep running, and a toast says "Removed from this Orca. The host keeps running for ."
• No: the old teardown runs, unchanged.
• The server can't answer: the teardown is refused, and the host stays listed as "removal pending". Nothing is ended on a guess.
• An older server without the check: today's teardown runs, plus a warning in the log.

The Remove confirmation now says terminals end "unless another Orca that's open on this computer is using it", in all 10 locales. The toast lists each name once, so several unnamed peers read "another Orca" a single time.

Mechanism:

• How a desktop identifies itself: after its long-lived control socket to a WSL host becomes ready (and again after every reconnect), the desktop calls host.declareClient({ clientInstanceId }). The id is a hash of its userData path, so stable and dev Orca differ and no path is revealed. The server tags exactly that socket and drops the tag when the socket closes.
• How Remove asks: host.peerDesktops({ clientInstanceId }) returns the other installations that have a declared socket open right now. The caller's own sockets never count, whether that's its control socket, a terminal multiplex socket or a one-shot call. Two desktops sharing one pairing token still count as two. Undeclared sockets, phones and browser sessions are ignored.
• "Open" means open now or closed within the last minute: both keep the server, which is the fail-safe direction.
• Reconnects: losing contact isn't proof an Orca left. When an installation's last declared socket closes (a bridge exit, an orcad restart, resume from sleep, reconnect backoff), the server keeps counting it as a peer for 60 seconds (on a monotonic clock), or until it declares again. Expired graces are swept on every close, so the list stays bounded.
• Names: peer names go through sanitizeDeviceLabel. The installation id is an unsalted hash of the userData path; a per-install random salt was considered and left out, since the id only distinguishes installations on one server. A startup-offer name like "CLI 10/28/2026" shows as "another Orca".
• Move undo: a Remove kept for another Orca is recorded (wsl-host-kept-for-peers.ts). Undo of a move onto that host then treats it as unreachable and refuses, instead of assuming its terminals and automations stopped. A later Remove that proves the server stopped clears the record. If the record can't be saved, the host stays listed as removal pending.
• Desktop side: stopWslHostServer runs the check before closing any terminal or decommissioning (src/main/wsl/wsl-host-peer-desktops.ts).

Why

Earlier versions of this PR tracked desktops through the server's device rows: last-seen times, per-desktop token forks, and releasing a desktop's own row. Each fix created more identity state (orphan forks, a released shared token, changed caller fingerprints). Asking which Orcas are connected right now needs no stored identity and mints no credentials. It runs as an ordinary RPC rather than as a field on the auth frame, because the server checks the encrypted token-auth frame for an exact set of fields, and an older server would refuse any extra one.

Mixed versions: both methods sit behind orcad.peer-desktops.v1. Against an older server, a desktop's declaration gets "method not found" and is ignored, and Remove uses today's teardown plus a warning. An older desktop never declares, so a newer desktop's Remove doesn't count it. That's the same as today. No auth frame, stream or opcode changed.

Known limits:

• An Orca that's closed while its terminals keep running in the daemon isn't protected.
• After a crash or update restart of the WSL host's server, an Orca that was connected counts again only once it re-declares. A Remove inside its reconnect backoff tears its sessions down. An idle exit only happens with no user processes, so a restart after one has nothing to lose.
• Two more cases get today's teardown: an older desktop, which never declares, and a desktop whose control socket has been down for more than the 60-second grace when Remove runs. Its sessions are torn down by the other Orca's Remove, the same as today.
• Idle release: every Orca's distro holder watches the same ~/.orca release file, and only one claims each request. That wastes resources but loses nothing.
• Account push: each Orca pushes its own selected Claude/Codex accounts to the shared server, and the last push wins.

Linked Issue

N/A (WSL host work, R39 on the flag-on checklist).

Visual Proof

N/A: copy-only changes (one info toast, one confirmation sentence) on a flow behind the internal WSL flag. Both are unit-tested.

Testing

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

• Integration, real RPC server (peer-desktops.integration.test.ts):

  • the capability is advertised;
  • one desktop with a declared control socket, an undeclared second socket and one-shot calls sees no peers;
  • two desktops sharing one startup token each see the other;
  • when one control socket closes, that Orca still counts during the 60-second reconnect grace (the grace running out is unit-tested with a clock);
  • a reconnect re-declares;
  • a name with a newline and bidi characters is sanitized;
  • a phone can't declare.

• Unit:

  • declared-desktop-clients.test.ts: one entry per installation, the caller excluded, sanitized and "CLI " names, non-desktop rows skipped;
  • wsl-host-peer-desktops.test.ts: the reader, including the older-server fallback and refusal on no answer;
  • wsl-host-client-declaration.test.ts: WSL only, quiet on an older server;
  • the shared-control connection calls onReady again after a reconnect;
  • stop-flow order, kept, refused and unsupported paths;
  • kept-for-peers record and undo refusal;
  • the renderer toast.

• CI routes the Remove-path files to wsl-host-fake-transport.spec.ts.

• Local runs:

  • pnpm tc, typecheck:ci, check:code-quality:changed, oxlint (anti-slop too), the RPC catalog and 3 of 4 localization checks pass;
  • verify:localization-catalogs fails on a stray dashboardPopout.terminal.closed key in ru.json that is already on main and untouched here;
  • 5,750 tests pass across rpc, runtime-rpc, wsl, managed-server, runtime-environments and the shared remote-runtime client;
  • the WSL e2e specs pass on a fresh build.

• Not run: a real two-Orca Windows setup. To check, with stable and dev Orca on one Windows account both using one distro's WSL host: open a terminal in dev, Remove the host in stable, and confirm dev's terminal keeps running and wsl --list --running still lists the distro.

AI Disclosure

Review

Touches the WSL host Remove path; two reviewers.

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

• Behind ORCA_INTERNAL_WSL_HOSTS: only a WSL host's Remove and control socket use these calls.
• The server methods need an authenticated desktop socket (phones get runtime_device_required), take only an installation id, and return only display names.
• No effect on SSH: the declaration is sent only for WSL hosts, and SSH Remove never decommissions.

Checklist

• This PR is small and focused
• 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 (typecheck, touched suites and WSL e2e locally; full lint and test left to CI per load rule)

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

• Last reviewed commit: c4aebc8

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The runtime adds RPC methods to declare client installations and list peer desktops. WSL hosts declare their installation IDs on shared-control connections, including after reconnects. Before stopping a WSL server, the removal flow checks for peers and keeps the server running when another desktop uses it. The flow records retained-host state, adjusts undo results for retained hosts, and reports shared-host outcomes in the renderer.

Priority: Normal

Merge Risk: Moderate · up to c4aeb

Removing a shared WSL host is now safer for other Orca installations on the same computer. However, if the retained-host record cannot be read, undo can treat a host that is still running for another Orca as stopped. Fix this fail-open behavior before merging.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 42.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: preserving a shared WSL host server during removal.
Description check		The description is comprehensive and covers the user impact, mechanism, rationale, testing, limitations, compatibility, and checklist. It marks the linked issue as N/A even though the template request…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description is comprehensive and covers the user impact, mechanism, rationale, testing, limitations, compatibility, and checklist. It marks the linked issue as N/A even though the template requests an actual issue link, and it leaves the full lint, test, and build checklist item unchecked with an explanation that CI will cover it.

Full details: Docstring Coverage

Explanation

Docstring coverage is 42.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 19 functions across 33 files. (11 skipped: 11 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

• Autofix · 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.}

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5f16abf9-b3e9-4d1a-bbcf-bd5547cface4

Commits

Reviewing files that changed from the base of the PR and between 68f0c79 and f1cb443.

Files ignored due to path filters: 1

• src/shared/rpc-contract/rpc-params-catalog.generated.ts is excluded by !**/*.generated.*

Files selected for processing: 16

• src/main/runtime/peer-desktops.integration.test.ts
• src/main/runtime/peer-desktops.test.ts
• src/main/runtime/peer-desktops.ts
• src/main/runtime/rpc/core.ts
• src/main/runtime/rpc/dispatcher-stream-options.ts
• src/main/runtime/rpc/methods/pairing.ts
• src/main/runtime/rpc/mobile-socket-wiring.ts
• src/main/runtime/runtime-rpc/runtime-rpc-mobile-devices.ts
• src/main/runtime/runtime-rpc/runtime-rpc-websocket-dispatch.ts
• src/main/wsl/wsl-host-peer-desktops.test.ts
• src/main/wsl/wsl-host-peer-desktops.ts
• src/main/wsl/wsl-host-server-stop.test.ts
• src/main/wsl/wsl-host-server-stop.ts
• src/shared/orcad-peer-desktops-contract.ts
• src/shared/orcad-runtime-capabilities.ts
• src/shared/wsl-host-types.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

[coderabbitai]

Major · Functional Correctness · Quick win

Supported by static analysis

Script executed:

#!/bin/bash
# Verify whether a token row can be shared by several installations, and how forkedFrom is set.
rg -nP -C4 '\bforkedFrom\b' --type=ts -g '!**/*.test.ts' src/main

Repository: stablyai/orca

Length of output: 6657

---

Script executed:

#!/bin/bash
set -e
printf '%s\n' '--- peer-desktops.ts ---'
nl -ba src/main/runtime/peer-desktops.ts
printf '%s\n' '--- device-key-fork.ts ---'
nl -ba src/main/runtime/device-key-fork.ts
printf '%s\n' '--- peer-desktops references and tests ---'
rg -n -F --glob '*.ts' -e 'listPeerDesktops' -e 'isConnected' src/main src | head -200
printf '%s\n' '--- DeviceEntry and connection-related definitions ---'
nl -ba src/main/runtime/device-entry.ts | sed -n '1,100p'

Repository: stablyai/orca

Length of output: 35642

---

Script executed:

#!/bin/bash
set -e
printf '%s\n' '--- peer RPC consumer ---'
rg -n -F --glob '*.ts' -e 'readWslHostPeerDesktops' -e 'stopWslHostServer' -e 'OrcadPeerDesktopsResult' src/main src/shared
printf '%s\n' '--- relevant runtime RPC and WSL excerpts ---'
for f in src/main/runtime/runtime-rpc/runtime-rpc-mobile-devices.ts src/main/runtime/runtime-rpc/runtime-rpc-websocket-dispatch.ts src/main/wsl/wsl-host-service.ts; do
  if [ -f "$f" ]; then
    echo "--- $f ---"
    nl -ba "$f" | sed -n '1,380p'
  fi
done

Repository: stablyai/orca

Length of output: 39953

---

Script executed:

#!/bin/bash
set -e
printf '%s\n' '--- src/main/wsl/wsl-host-peer-desktops.ts ---'
nl -ba src/main/wsl/wsl-host-peer-desktops.ts
printf '%s\n' '--- src/main/wsl/wsl-host-server-stop.ts ---'
nl -ba src/main/wsl/wsl-host-server-stop.ts

Repository: stablyai/orca

Length of output: 12013

---

Keep connected fork-lineage rows in the peer list.

forkedFrom identifies token lineage, not a unique installation. The source token row can remain active for another holder, and multiple device-key rows can be forked from the same token row. The current filters remove these rows before checking connection status. A connected peer can therefore be omitted, causing teardown to close its terminals and decommission the shared server.

Exclude a lineage row only while it is not connected. Add tests for connected source and child rows.

Suggested fix

--- "a/src/main/runtime/peer-desktops.ts"
+++ "b/src/main/runtime/peer-desktops.ts"
@@ -7,17 +7,20 @@
   callerDeviceId: string,
   isConnected: (deviceId: string) => boolean
 ): OrcadPeerDesktopsResult {
-  const caller = devices.find((device) => device.deviceId === callerDeviceId)
+  const caller = devices.find((device) => device.deviceId === callerDeviceId)
+  // Lineage means "same installation" only while that row is idle; a connected row is another holder.
+  const isOwnLineage = (device: DeviceEntry): boolean =>
+    !isConnected(device.deviceId) &&
+    (device.deviceId === caller?.forkedFrom || device.forkedFrom === callerDeviceId)
   return {
     peers: devices
       .filter(
         (device) =>
           device.scope === 'runtime' &&
           device.deviceId !== callerDeviceId &&
-          // Its own pre-migration token row is the same desktop, not another one.
-          device.deviceId !== caller?.forkedFrom &&
-          device.forkedFrom !== callerDeviceId &&
+          // Its own idle pre-migration token row is the same desktop, not another one.
+          !isOwnLineage(device) &&
           device.parentDeviceId === undefined &&
           !device.ephemeral &&
           device.lastSeenAt > 0
       )

[coderabbitai]

Actionable comments posted: 3

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: d5dc7479-77db-4be6-93a6-711cab2f7bf1

Commits

Reviewing files that changed from the base of the PR and between f1cb443 and f09e473.

Files ignored due to path filters: 1

• src/shared/rpc-contract/rpc-params-catalog.generated.ts is excluded by !**/*.generated.*

Files selected for processing: 24

• config/scripts/pr-e2e-route-contracts.test.mjs
• config/scripts/pr-e2e-source-routing.mjs
• src/main/runtime/peer-desktops.integration.test.ts
• src/main/runtime/peer-desktops.test.ts
• src/main/runtime/peer-desktops.ts
• src/main/runtime/rpc/core.ts
• src/main/runtime/rpc/methods/pairing.ts
• src/main/runtime/runtime-rpc/runtime-rpc-mobile-devices.ts
• src/main/runtime/runtime-rpc/runtime-rpc-websocket-dispatch.ts
• src/main/wsl/wsl-host-server-stop.test.ts
• src/main/wsl/wsl-host-server-stop.ts
• src/renderer/src/components/sidebar/HostRemoveDialog.tsx
• src/renderer/src/components/sidebar/wsl-host-removal.test.ts
• src/renderer/src/components/sidebar/wsl-host-removal.ts
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/fr.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/pt.json
• src/renderer/src/i18n/locales/ru.json
• src/renderer/src/i18n/locales/zh-Hant.json
• src/renderer/src/i18n/locales/zh.json
• src/shared/orcad-peer-desktops-contract.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

[coderabbitai]

Major · Stability & Availability · Heavy lift

Do not treat a shared bearer row as one desktop. If two Orca installations authenticate with the same legacy pairing credential, both use callerDeviceId. This filter removes their only row, so the WSL reader can report no peers and Remove can stop the other installation’s server and terminals. The registry supports multiple holders of a token row. Treat that identity as ambiguous for destructive teardown unless the server can distinguish its holders. (raw.githubusercontent.com)

[coderabbitai]

Major · Stability & Availability · Quick win

Keep connected sibling forks in the peer list. Two installations can fork separate device-key rows from one shared token row. Both forks inherit the same callerFingerprint, so this condition omits the other installation even when its socket is connected. Remove can then decommission its server. Exclude an older enrollment only when the row is not connected, and cover connected sibling forks in the tests. (raw.githubusercontent.com)

[coderabbitai]

Major · Security & Privacy · Heavy lift

Do not report a successful release when revocation fails. If releaseFromPeers() throws, this catch still returns stopped: true. If device removal returns { released: false }, the adapter at Lines 152–154 also treats the RPC as success. Removal then drops the local host record even though this desktop’s credential can remain valid on the server, and another desktop can continue counting its row. Check released and keep removal pending when revocation fails; close the bridge without ending the shared server’s terminals. (raw.githubusercontent.com)

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

Major · Fail closed when retained-host state cannot be read. · wsl-host-kept-for-peers.ts:15-35

src/main/wsl/wsl-host-kept-for-peers.ts:15-35
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Fail closed when retained-host state cannot be read.

readKeptList converts filesystem, JSON, and schema errors into an empty list. After a removal records that the server was kept for another Orca, this makes wasWslHostKeptForPeers return false. Both undo ports then report the removed host as stopped, so undo can resume local copies and automations while the retained WSL server still runs for the peer. Distinguish an absent record from an unreadable record and return unreachable when the state cannot be read.

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 777d2581-19d0-4a39-84bd-532643adb01a

Commits

Reviewing files that changed from the base of the PR and between ee522dc and c4aebc8.

Files ignored due to path filters: 1

• src/shared/rpc-contract/rpc-params-catalog.generated.ts is excluded by !**/*.generated.*

Files selected for processing: 13

• src/main/ipc/wsl-move-undo-wiring.test.ts
• src/main/ipc/wsl-move-undo-wiring.ts
• src/renderer/src/i18n/locales/de.json
• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/fr.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/pt.json
• src/renderer/src/i18n/locales/ru.json
• src/renderer/src/i18n/locales/tr.json
• src/renderer/src/i18n/locales/zh-Hant.json
• src/renderer/src/i18n/locales/zh.json

Files skipped from review as they are similar to previous changes: 8

• src/renderer/src/i18n/locales/en.json
• src/renderer/src/i18n/locales/pt.json
• src/renderer/src/i18n/locales/es.json
• src/renderer/src/i18n/locales/ko.json
• src/renderer/src/i18n/locales/fr.json
• src/renderer/src/i18n/locales/ja.json
• src/renderer/src/i18n/locales/zh.json
• src/renderer/src/i18n/locales/tr.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.