Publish self-contained, platform-specific relay runtimes through the same GitHub Release used by the Orca desktop app. Orca downloads and verifies the matching runtime locally, transfers it over the existing SSH connection, and launches it from an immutable remote cache.
Make the verified runtime the primary path, keep the existing embedded relay plus remote Node/npm installer as an automatic fallback only for classified availability and compatibility failures, and remove or narrow that fallback only after the complete declared support matrix has passed and soaked. Build and sign relay artifacts before desktop packaging so every app embeds the exact signed tuple-to-content manifest needed for offline remote-cache reuse.
The desktop owns release access, signature verification, caching, and extraction. SSH authentication/connection and relay RPC transport stay unchanged. Bootstrap artifact transfer is materially redesigned, independently gated, and still travels only through the authenticated SSH connection.
Relay build precedes desktop builds and emits the signed manifest plus exact archives.
Embedded manifest resolves identity offline; downloaded bytes are verified and extracted atomically.
Bounded streaming over SFTP or system SSH; remote tar is an optional fast path.
Match the embedded content ID, verify transferred files once, record proof, then launch.
Every required cell in the declared two-layer, risk-based matrix has evidence. It does not mean every possible client × SSH server combination. A tuple without real-environment proof stays on the legacy path and is not enabled by default.
The protocol, SSH authentication/connection, relay RPC transport, immutable install directories, locks, reconnect logic, and garbage collection stay in place. Packaging and bootstrap artifact transfer are the moving parts.
node-pty and @parcel/watcher.sh/byte-stream/file-operation
baseline; Windows targets require a declared PowerShell/.NET baseline.
Each phase has an independently testable output. Early phases add evidence and artifacts without changing the default SSH connection path.
Finish the narrow #8450 change so Node and npm are selected as one coherent toolchain. Keep it separate from runtime distribution so affected users receive a small, reviewable fix first.
Specify archive layout, manifest schema, platform/libc selection, Node version, protocol identity, dependency versions, licenses, file modes, support baselines, and exact POSIX/Windows bootstrap primitives. Hash the full runtime contents rather than only relay JavaScript.
Assemble pinned Node, relay entries, patched node-pty, the exact
@parcel/watcher package, and required JavaScript dependencies on
matching CI environments. Run executable smoke probes before archiving.
Use target-native relay build jobs plus native signing jobs. A fail-closed aggregate job waits for every signed macOS/Windows byte, computes final hashes, signs the canonical manifest, and makes its immutable output a prerequisite of every desktop packaging job. Upload those exact archives, manifest, and signature to the existing draft GitHub Release. Extend the required-assets gate to verify presence, size, signature, manifest coverage, byte identity, and read-back before publication; timeout, signing failure, exhausted retry, or manual-approval failure leaves a recoverable draft and blocks every consumer.
Resolve the remote tuple and content ID from the embedded signed manifest, use its
exact build tag and direct release URL, download through Electron networking,
verify before extraction, and atomically populate a content-addressed cache.
Coordinate cache ownership across app processes and preserve
ORCA_RELAY_PATH for development.
Replace whole-tree buffering and serial-only assumptions with bounded file
streaming: capability-probed tar may accelerate POSIX system SSH, but no-tar file
streaming is required and uses the SSH channel as a byte-preserving stdin stream
into exclusive per-file staging with only the declared shell/file primitives;
Windows uses a bounded binary PowerShell/.NET path and must not materialize the
runtime as one JSON/base64 buffer; SFTP uses bounded concurrency. After locally
verifying signed metadata and archive/tree hashes, transfer through authenticated
SSH, restore every declared executable bit, then execute the transferred bundled
Node to hash the entire staging tree. Verify the full tree, run bundled
Node/native-module and minimal PTY/watcher probes, write a structured
.install-complete containing schema, mode, and digest, atomically
publish the immutable install, and only then launch. Preserve current locks,
reconnect, and garbage collection.
Add auto, bundled, and legacy modes. The
public Beta is a per-SSH-target bundled-auto choice that maps to
auto; absent or unknown configuration maps to legacy,
and forced bundled remains an engineering/support diagnostic. Record
privacy-safe stage and fallback reason codes in diagnostics, without hostnames,
usernames, or paths. Give every stage a budget and shared AbortSignal. Before
fallback, cancel and await all download, extraction, upload, and probe work.
Bundled and legacy installs use distinct identities, locks, and sentinels so late
work cannot mutate the other mode. Only availability/compatibility failures may
enter proven legacy behavior in auto; signature, hash,
archive-safety, or native-signature failures fail closed without automatic mode
switching.
Publish assets before consuming them, then ship the per-target Beta through RC and stable while every target remains on legacy unless explicitly opted in. Any default-on RC or stable promotion requires a separate reviewed decision. Enable only tuples with complete live evidence; keep the fallback through at least two stable cycles.
Bundling Node with its native modules removes ABI ambiguity. Linux libc remains a separate compatibility boundary and must be detected before artifact selection.
linux-x64-glibcDecision-gated candidate
linux-arm64-glibcDecision-gated candidate
linux-x64-muslLegacy-only; Orca build required
linux-arm64-muslLegacy-only; Orca build required
darwin-x64Decision-gated candidate
darwin-arm64Decision-gated candidate
win32-x64Decision-gated candidate
win32-arm64Decision-gated candidate
Current source recognizes Linux, macOS, and Windows remotes on x64 and arm64 and uses coherent remote Node/npm plus the remote native-install path. Linux legacy identity does not distinguish glibc from musl. The bundled selector introduces that distinction and starts with musl disabled. A source-declared family or passing unit test is not a fallback claim: this project currently has live legacy evidence only for Ubuntu 24.04 arm64 over built-in SSH2/SFTP, so every other fallback cell remains open.
Milestone 1 starts with no declared bundled tuples and decides which candidates become enabled. Once enabled, a tuple blocks release if its asset or live proof is missing. Candidates awaiting a trustworthy Node runtime source or real hardware remain supported only if their legacy E2E still proves current behavior. Otherwise they stay ineligible for rollout rather than being silently claimed as supported.
The first contract pins unchanged official Node v24.18.0 LTS binaries. Linux glibc
candidates require kernel 4.18, glibc 2.28, and libstdc++ 6.0.25 with
GLIBCXX_3.4.25; macOS candidates require 13.5. Initial Windows x64
candidates require Windows 10 22H2 build 19045 or Server 2022 build 20348, and arm64
requires Windows 11 24H2 build 26100. The immutable manifest's single monotonic
minimumBuild is therefore 19045 for x64 (which also admits Server 2022
build 20348 and newer builds) and 26100 for arm64. Windows bootstrap additionally
requires OpenSSH for Windows 8.1p1, Windows PowerShell 5.1, and .NET Framework 4.8.
Node's detached checksum signature is verified against a build-input-pinned official release keyring before extraction. Musl has no accepted official binary for this package, so musl remains legacy-only until Orca owns and proves a target-native source build. Rosetta-translated shells remain legacy until the x64 artifact passes a live Rosetta SSH cell. These are selector eligibility constraints, not tuple enablement; every candidate still needs the complete two-layer evidence.
Windows target-native native-module builds use three immutable inputs authenticated by
that same signed checksum document: the tuple's official Node ZIP, the exact-version
headers.tar.gz, and the tuple's win-*/node.lib. The Windows
ZIP does not contain build headers or the import library. Stage only the required
executable, license, headers, and import library into the local build root; disable
implicit node-gyp downloads so no unrecorded build input can enter.
node.lib, neither of which is shipped in
the Windows runtime ZIP.
relay.js and crash-isolated relay-watcher.js.node-pty@1.1.0 built for the bundled runtime.conpty.dll
and OpenConsole.exe) for the tuple architecture. Hash both files into
the tree identity, classify them as native runtime inputs for signing/trust, and
run PTY smoke with the production useConptyDll: true behavior rather
than silently exercising system ConPTY.
@parcel/watcher@2.5.6 with exactly one native optional package.
tweetnacl dependency. Tuple and file arrays are sorted,
identity fields are portable ASCII, numbers are safe integers, and signatures
remain outside the signed projection.
relay-runtime-manifest-signing GitHub Environment with required
reviewers. Only the aggregate signing job receives it; runtime publication stays
blocked until that environment and its access audit exist.
latest lookup;
emergency refresh and key response use the normal desktop update path.
/releases/download/<exact-tag>/<asset>,
never a mutable latest URL.
.node, dylib, and
spawn-helper with the existing Developer ID identity, and send every
unsigned Windows .exe, DLL, and .node through the
existing SignPath inner-binary flow.
getconf GNU_LIBC_VERSION, then parse marked
ldd --version output and musl loader paths.
auto deterministically selects legacy.
nohup and selects legacy.
sh with builtin
command/printf, byte-preserving stdin-to-file via
cat, and required
mkdir/rm/mv/chmod/test/nohup
semantics. It excludes Node, Python, Perl, tar, base64, checksum tools, and
compilers.
FileStream loop writes raw stdin under an exclusive
FileMode.CreateNew staging lock; it rejects early EOF and excess
bytes and uses same-volume publish.
MaxSessions=1; transferred bundled Node later hashes the complete
tree.
The local verified cache is capped at 2 GiB. Archives are rejected above 100 MiB
compressed, 350 MiB expanded, 5,000 entries, or 250 MiB for one file. Incremental
transfer/extraction memory is capped at 64 MiB on the desktop and 32 MiB remotely;
buffers stay at or below 1 MiB. SFTP starts at four files/channels and never exceeds
eight open files, dropping to one for MaxSessions=1.
Cold bootstrap is capped at 30 minutes with named sub-budgets, and cancellation must join within 10 seconds. Warm p95 may be at most 100 ms or 10% slower than paired legacy, whichever allowance is larger. Cold p95 may not exceed the smaller of 30 minutes or 115% of measured bytes/throughput time plus five minutes. Offline failures classify within 20 seconds and eligible legacy starts within 10 seconds after classification and join. Native GitHub jobs compare at least ten paired samples under the same network shaping; inconclusive hosted variance requires a dedicated runner rather than a weaker threshold.
Availability and compatibility failures may use a separately proven legacy path.
Signature, hash, archive-safety, extracted-tree, and native-signature failures fail
closed in auto; they never trigger an automatic mode switch.
| Condition | Action | User impact |
|---|---|---|
| Previously validated runtime with matching structured sentinel and warm-path structural checks | Trust initial-install proof under the immutable-directory assumption and launch without a full-tree rehash | No download, transfer, or npm work |
| Verified local cache hit | Upload and validate | Remote may remain fully offline |
| Client offline or asset absent, with no verified local cache |
Use proven legacy in per-target Beta auto; forced bundled fails at
the exact availability stage
|
No GitHub request is ever delegated to the SSH host |
| Bundled availability failure and legacy prerequisites also fail | Report both stage codes with retry, update, and disable-Beta guidance; preserve the original bundled error | No false fallback-success claim or hidden retry loop |
| Detected local or remote cache corruption | Quarantine it and reinstall only from freshly verified bundled bytes; if recovery cannot complete, fail closed without automatic legacy | No corrupted cache is launched or hidden by fallback |
| GitHub timeout, 404, 429, or 5xx | Use legacy path in auto mode |
Existing behavior remains available |
| Unsupported tuple or pre-execution compatibility probe proves the runtime cannot execute | Use legacy path and record reason | Current behavior is retained only where the legacy E2E passes |
| Signature, hash, archive-safety, extracted/transferred-tree, bundled-Node integrity, or native-signature failure | Fail closed, delete or quarantine rejected bytes, and do not start automatic legacy | Security failure is explicit and requires a trusted update or operator-selected recovery |
Forced bundled mode fails |
Fail with the exact stage and recovery guidance | No hidden change of requested mode |
Integrity failures, including detected cache mutation, stop before this transition and cannot automatically select legacy. Hostile control of the authenticated remote account is outside the integrity threat model; the remote proof establishes initial transfer/finalization correctness. Warm launches assume Orca's completed directory remains immutable; the sentinel is not ongoing proof against later filesystem mutation. Detected warm-cache mutation fails closed. This does not protect against a remote user who can replace both runtime and sentinel.
sha256sum or shasum; execute the
transferred bundled Node to hash every staged file and compare the complete
manifest.
Local verification plus authenticated transfer and exclusive staging is the pre-execution integrity boundary. Executing bundled Node is intentionally the first staged binary execution and verifies transfer correctness before completion. A hostile authenticated remote account remains outside scope because it can replace both the runtime and its proof.
Mock tests protect decision logic. Release promotion additionally requires the real archive, real native binaries, a real SSH daemon, and the exact packaged desktop path.
| Surface | Required cases | Oracle |
|---|---|---|
| Build | Every declared tuple; minimum OS baseline; exact Node and native dependency versions; SBOM and provenance | Archive runs on target, contents match manifest, native signatures pass, no unexpected platform package remains |
| Platform selection | glibc/musl and version probes, BusyBox, Alpine, containers, old glibc, Rosetta, noisy and conflicting output | One compatible tuple is selected, or unknown deterministically selects tested legacy behavior |
| Remote environment | No Node/npm/Python/compiler/tar/hash tools; blocked egress; missing required primitives; BusyBox; NVM below shell guard; read-only/noexec home; quota and inode exhaustion | Declared POSIX or Windows primitive baselines connect without undeclared tools; missing primitives and filesystem constraints classify compatibly and never improvise an untrusted command path |
| Download and cache | Redirect and header scoping, proxy, deleted asset, cold/warm/offline cache, multiple app processes, eviction, permissions, cancellation, timeout, 404/429/5xx, disk full, corruption | One verified cache entry or clean availability fallback; corruption is quarantined and recovered only from freshly verified bytes or fails closed |
| Archive security | Bad signature/hash/native signature, wrong tuple, traversal path, absolute path, symlink escape, oversized expansion | Manifest/archive failures are rejected before transfer; native trust is verified on target-native build/read-back and again by target-policy probes before finalization; every integrity failure fails closed |
| SSH deployment |
Full-size runtime over SFTP and POSIX/Windows system SSH; tar/no-tar; no remote
hash tools; corrupted upload; bundled-Node corruption/failure; bounded memory
and concurrency; MaxSessions=1; interrupted upload; stale lock
|
Bundled Node hashes the full staged tree before sentinel write; corruption/failure leaves no complete install, memory stays in budget, and the ordering is asserted |
| PTY and watcher | Spawn, input, resize, exit, shell environment, create/rename/modify/delete events, watcher crash | Exact PTY bytes and watcher events; relay PID and existing PTY survive watcher replacement |
| Relay API conformance | PTY, Git, filesystem and streaming RPCs, preflight, agent hooks, port scan, aborts, and protocol handshake | The packaged runtime matches existing relay request, response, streaming, cancellation, and error contracts |
| Lifecycle and fallback | Reconnect, PTY reattach, restart, concurrent clients, upgrade, downgrade, interrupted upgrade, GC, timeout-to-legacy, forced rollback | No lost session, protocol drift, late mutation, background process, cross-mode lock/sentinel use, or deletion of a live version |
| Performance | Cold and warm paths over 1/10/100 Mbps links and 50–200 ms latency | Warm path has no meaningful regression; cold p95 does not exceed agreed legacy baseline |
Evidence has two layers. Every enabled remote tuple must pass both built-in SFTP and
system SSH, including Windows remote/system SSH and MaxSessions=1. Every
supported client OS/architecture must separately prove resolver/cache plus both
transfer families against representative POSIX and Windows remotes. Each required cell
has an evidence ID; untested client × remote combinations are not claimed.
GitHub Actions is the primary orchestration and evidence surface for PR, nightly, release, and promotion gates. A GitHub-hosted runner may fill a required cell only when it provides real hardware or native virtualization for the declared OS/architecture and exercises a real OpenSSH daemon, the full-size packaged runtime, and the production transport named by that cell. Same-host and native-container targets qualify only when they preserve the declared remote, SSH, primitive, egress, and isolation conditions; mocks, reduced fixtures, cross-builds, and QEMU-only runs do not qualify as live evidence.
Cross-family client-to-remote cells use workflow-provisioned ephemeral native SSH targets or an approved self-hosted target pool; the remote need not itself be GitHub-hosted. Each job records the runner label and image, native architecture, remote image or snapshot identity, teardown result, commands, metrics, and artifacts. A tuple stays on proven legacy behavior when no qualifying native runner or reachable representative remote is available. Numeric regression comparisons use a repeatable runner class or a dedicated runner when hosted-runner variance would make the agreed threshold inconclusive.
Qualifying jobs pin explicit native labels: ubuntu-24.04 and
ubuntu-24.04-arm, macos-15-intel and macos-15,
plus windows-2022 and windows-11-arm. GitHub refreshes these
images weekly, so each job logs the resolved image version; *-latest and
third-party runner labels do not qualify a tuple merely because another repository
workflow uses them. Hosted capacity is unreserved, and no approved self-hosted SSH
target pool or cross-family endpoint is assumed.
The largest risks are compatibility boundaries and release coupling, not the GitHub download itself.
Build against the oldest supported glibc and libstdc++ baseline; run on that exact baseline before promotion.
Do not invent a binary source. Document provenance and updates, or retain legacy mode for musl until Orca can build it.
Build from Orca’s lockfile and patch set; assert the patched diagnostic exports and real PTY behavior in every artifact.
Keep releases draft until all relay assets pass read-back verification; publication depends on the completeness job.
Cache by content, prefetch last-known target tuples after updates, preserve progress stages, and keep a bounded fallback.
Probe bundled Node before finalizing. Auto mode falls back to the remote runtime path with a precise diagnostic reason.
Verify a signed canonical manifest and archive SHA-256 before extraction; never execute or transfer rejected bytes.
Record stage-specific reason codes and require zero unexplained fallback across the RC promotion window.
Own a supported-version/EOL policy, SBOM and provenance, update cadence, and CVE response SLA. Every refresh ships a new desktop build and embedded manifest; installed old clients remain pinned.
Specify canonical bytes, protected-environment access, key IDs, dual-key rotation, revocation response through a desktop update, and exact-tag anti-rollback. Do not add mutable freshness lookup.
Test quarantined bytes on clean macOS 13.5 x64/arm64 snapshots with Gatekeeper and strict codesign. Test Server 2022 x64 and Windows 11 24H2 arm64 with current Defender intelligence, then Windows 11 24H2 x64 with the release WDAC policy in audit and enforced modes. Record snapshot, policy, and security-intelligence IDs; any denial blocks release rather than weakening the endpoint control.
Use bounded streaming and cancellation per transport; prohibit whole-tree JSON/base64 buffering and require a no-tar path before default-on.
Abort and join every bundled stage before legacy starts; separate mode identities and reject callbacks from stale generations.
Use marked no-Node probes and conservative version checks. Unknown, conflicting, or unsupported results choose proven legacy behavior.
Artifact availability lands before production consumption. Every later stage remains reversible from the same app build.
Build and publish runtimes, run read-back E2E, leave production on legacy.
Ship a Beta-tagged option on SSH target add/edit surfaces; every existing and new target remains on legacy unless explicitly opted in.
Gather privacy-safe real-host evidence while the packaged and persisted default remains legacy.
Change a tuple to default-on only through a separate reviewed decision after CI, native-runner, Beta-usage, support, and rollback gates pass.
Store an extensible runtime mode per SSH target rather than a global boolean. Missing,
malformed, imported, existing, and newly created target configuration defaults to
legacy. The Beta option selects bundled-preferred
auto behavior only for that target and only on its next connection or an
explicit reconnect; it never hot-swaps a live PTY, watcher, or relay generation.
Classified availability and compatibility failures may enter proven legacy automatically. Integrity and security failures still fail closed, but the local error surface provides an explicit action to disable Beta for that target and reconnect through legacy. Shipping this option does not authorize changing the default or removing legacy behavior.
These are release criteria, not aspirations. Missing bundled evidence keeps the affected tuple on legacy only when its legacy E2E passes; otherwise Orca must not claim that tuple as supported.
If a required live runner, trusted runtime source, compatibility baseline, or rollback proof is unavailable, do not declare the tuple bundled-by-default. Continue serving it through the tested legacy path.
Links are relative so this document remains useful from a local checkout.