Skip to content

fix(serve): validate in-process serve options before startup - #17683

Merged
nwparker merged 5 commits into
nwparker/linux-orcad-restart-safetyfrom
nwparker/linux-serve-flag-validation
Sep 2, 2026
Merged

nwparker merged 5 commits into
nwparker/linux-orcad-restart-safetyfrom
nwparker/linux-serve-flag-validation

Conversation

@nwparker

@nwparker nwparker commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​301 $\color{#cf222e}{\Huge{\mathbf{−}}}$​8 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​293
Prod 8 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​298 $\color{#cf222e}{\Huge{\mathbf{−}}}$​129 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​169

ELI5

There are two ways to start an Orca server, and they used to disagree about what a valid command looks like.

The normal way is orca serve ..., which checks your options first. But a packaged Orca can also be started directly as <binary> serve ..., and that path skipped the checks. Anything it did not understand, it quietly ignored.

The part that matters: --no-pairing is how you say "do not let phones pair with this server." If you typed --no-pairng — one letter missing — the direct path silently dropped it and started the server with pairing still switched on. No error, no warning; it looked like it had worked. That is the opposite of what you asked for, on the one option where being wrong actually matters.

You could also give it two options that contradict each other (--no-pairing and --mobile-pairing), and it would just pick one and carry on.

Now both paths use the same rulebook. A typo that is one small edit away from a real pairing flag is rejected by name, contradictory combinations are rejected, and the server refuses to start rather than starting in a state you did not ask for.

The tradeoff, stated plainly: commands that used to start are now rejected. That is the point — but it means a startup command with an old typo in it stops working after this upgrade instead of silently misbehaving. See User-facing regressions at the bottom for the one case that bites in practice.

What changed

  • Extracts serve-option parsing from src/main/index.ts into a small startup module.
  • Shares the existing cross-flag validation with the CLI (--no-pairing versus --mobile-pairing, and recipe JSON requirements).
  • Preserves CLI semantics for repeated flags, mixed aliases, --flag=value, --, and values that begin with --.
  • Detects near-miss pairing flags such as --no-pairng without closing Electron's open-ended Chromium switch set.
  • Keeps the direct serve path in-process so its signal and lifecycle ownership is unchanged.
  • Moves the edit-distance implementation into the shared module used by command and serve-flag suggestions.

Why

Issue #13006 identified a validation gap introduced when CLI-form serve launches became reachable directly from the packaged binary. A typo such as --no-pairng previously left pairing enabled while appearing accepted, and contradictory pairing/recipe options bypassed the CLI guards. This follow-up closes that gap without changing valid launches or the existing --json presence contract.

Linked issue

Fixes #13006
Refs #13133

Visual proof

N/A — command-line startup and validation only; no rendered UI changes.

Testing

  • 6 focused files / 109 tests passed
  • pnpm tc:node
  • Changed-code quality, reliability gates, max-lines/runtime-Electron ratchets, formatting, lint, and git diff --check pass on the rebased stack
  • Full rebased stack local evidence: 56 changed test files, 785 tests passed, and 4 platform-gated skips

The existing PR #13133 is intentionally left untouched; this branch is a separately stacked follow-up on #17320.

  • I manually tested these changes locally
  • Automated tests added/updated

Review

This is a follow-up after the seven-PR Linux packaging stack:

  1. fix(linux): give the CLI one entrypoint by extracting the AppImage once #15081 — one stable AppImage CLI entrypoint
  2. fix(linux): stop CLI commands from falling through to Chromium startup #15083 — unified launch redirect
  3. fix(linux): report a missing display instead of dying in uv_close #15084 — missing-display diagnosis
  4. test(linux): add a packaged-artifact contract for the CLI launch paths #15085 — packaged-artifact launch contract
  5. fix(linux): require static AppImage runtimes #17319 — static AppImage runtime validation
  6. fix(linux): move deb/rpm update installation outside Orca #17318 — manual deb/rpm package installation handoff
  7. docs(linux): document orcad update restart safety #17320 — orcad restart-ownership safety documentation
  8. serve-validation follow-up — In-process CLI-form serve skips the CLI's flag validation and cross-flag guards #13006

Notes

  • No RPC, remote-wire, mobile, persistence, provider, or package-format contract changes; no mobile-facing RPC/protocol/pairing surface was touched.
  • SSH and folder workspaces remain unaffected; validation runs in the local process before workspace execution.
  • Linux, macOS, and Windows direct-serve option aliases remain accepted where they were previously accepted.

Checklist

  • Rebased onto current main stack (212c0e42)
  • This PR is focused
  • I explained what changed and why
  • 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 impact considered
  • Typecheck, focused tests, lint, and readiness gates pass locally

User-facing regressions

Not zero, and the first one is the sharpest in this stack.

  1. A systemd unit that expands to a bare --port now fails to start. ExecStart=/opt/orca/orca-linux.AppImage serve --port ${ORCA_PORT} with ORCA_PORT unset expands to a bare --port, which previously fell through to the default port 6768 and started. It now throws Missing value for --serve-port. and exits 1; with Restart=on-failure the unit retries until StartLimitBurst trips it into failed. The error names the flag, and fixing the unit file is the remedy — but a host that was serving before an upgrade stops serving after it.

    This is the direct consequence of the PR's purpose. Silently defaulting would restore exactly the class of bug being fixed, so it is a deliberate trade rather than an oversight.

  2. Four option combinations that previously booted are now refused at startup, each with an explicit message: --no-pairing together with --mobile-pairing (one silently won before), and --recipe-json without runtime pairing or without --project-root.

  3. Unknown flags now hard-fail with a suggestion instead of being ignored, e.g. --no-pair → Unknown flag --no-pair. Did you mean --no-pairing?. A typo that was previously silently dropped now stops startup — which is the point, but it is a behaviour change for anyone whose unit file carries a stale flag.

Verified on Ubuntu 24.04 hardware against the packaged AppImage: 22 of 22 cases behaved as specified — 15 valid invocations accepted, 7 invalid ones rejected with the exact expected exit code and message.

@greptile-apps

greptile-apps Bot commented Aug 31, 2026 •

Copy link
Copy Markdown

Greptile Summary

The PR validates direct in-process serve launches before runtime startup while preserving the existing CLI argument semantics.

  • Extracts main-process serve argument parsing into a dedicated startup module.
  • Shares cross-option validation between CLI and direct Electron serve paths.
  • Rejects near-miss pairing flags while preserving open-ended Chromium switches.
  • Extends managed cleanup for legacy AppImage command wrappers.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
src/main/startup/serve-mode-argv.ts Normalizes CLI-form and mixed serve arguments while preserving repeated flags, equals-form values, and the option terminator.
src/main/startup/serve-options.ts Parses canonical and aliased serve options with final-occurrence semantics and validates them before runtime initialization.
src/shared/serve-option-validation.ts Centralizes contradictory-option checks and narrowly rejects near-miss pairing-related flags.
src/cli/handlers/core.ts Replaces duplicated CLI serve checks with the shared validation contract.
src/main/index.ts Delegates serve parsing to the startup module while retaining in-process lifecycle ownership and pre-startup failure handling.
src/main/cli/cli-command-installation.ts Extends stable legacy-command inspection to recognize current AppImage wrappers while preserving identity checks and foreign-wrapper protection.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Binary argv] --> B[Normalize serve-mode argv]
    B --> C[Parse serve options]
    C --> D[Reject pairing flag typos]
    C --> E[Validate cross-option invariants]
    D -->|Valid| F[Initialize runtime RPC server]
    E -->|Valid| F
    D -->|Invalid| G[Exit before startup]
    E -->|Invalid| G
    F --> H[Publish serve readiness]
Loading

Reviews (6): Last reviewed commit: "fix(serve): reject three-edit pairing fl..." | Re-trigger Greptile

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

The pairing-flag typo gate accepts only edit distance ≤ 2, while the CLI's own suggestion logic accepts ≤ 3. A 3-edit truncation like --no-pair is rejected by orca serve but silently accepted by the direct binary path, leaving pairing enabled — the exact fail-open this PR is meant to close. See the inline comment for the fix.

Reviewed changes

This run reviewed the full diff: extracting serve-option parsing out of src/main/index.ts into src/main/startup/serve-options.ts, and sharing cross-flag validation between the CLI and the direct in-process serve path.

  • Shared validation module — src/shared/serve-option-validation.ts centralizes the pairing/recipe-json cross-flag rules (getServeOptionValidationError) plus a near-miss pairing-flag gate (getServeFlagTypoError) used by both the CLI handler and the main-process parser.
  • Direct serve parser — getServeOptions now reads both --serve-* and bare --* aliases with last-occurrence-wins semantics, applies typo detection before startup, and throws (→ app.exit(1)) on malformed or contradictory options.
  • Argv normalization — normalizeServeModeArgv preserves --flag=value when the value begins with --, so --pairing-address=--no-pairng survives intact for the direct parser instead of splitting into a flag-shaped token.
  • Edit-distance extraction — levenshtein moved to src/shared/edit-distance.ts and re-exported from command-suggestion.ts, keeping the existing test import working.
  • Tests — parity tests plus focused parser/validation suites covering repeated flags, mixed aliases, = form, --, and flag-shaped values (54 tests in the changed/new files pass).

ℹ️ Nitpicks

  • The =-form preservation only holds on the direct binary path. orca serve --pairing-address=--no-pairng is re-serialized by serveOrcaApp as two tokens (--serve-pairing-address, --no-pairng), which the new typo gate rejects (previously it was silently dropped). Real pairing addresses never begin with --, so this is pathological, but it means the "values that begin with --" claim in the description only applies to one of the two paths.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

Comment thread src/shared/serve-option-validation.ts Resolved

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

The prior review's outstanding finding is still unaddressed: the pairing-flag typo gate at src/shared/serve-option-validation.ts:68 uses distance < bestDistance (catches distance ≤ 2), while the CLI's rankByDistance accepts <= 3. A 3-edit truncation like --no-pair is rejected by orca serve but silently accepted by the direct binary path, leaving pairing enabled. Commit 0a9c7ac only refactors core.ts and does not touch this line.

Reviewed changes

This incremental pass reviewed commit 0a9c7ac (src/cli/handlers/core.ts): the serve handler now reads no-pairing, mobile-pairing, recipe-json, and pairing-address from flags once into locals and reuses them across validation and serveOrcaApp. The change is behavior-preserving — typeof pairingAddressValue === 'string' narrows identically to the previous inline cast, and the === true boolean checks are unchanged. No new issues in this delta.

Pullfrog  | Fix it ➔ | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@nwparker

Copy link
Copy Markdown
Contributor Author

Restacked onto current main (212c0e42) and refreshed the direct-serve validation.

  • Restored the recorded fast-forward merge of fix(linux): remove legacy AppImage orca wrapper during migration #17685 (51add7e) to this target branch after the target ref had been reset, so the reviewed legacy AppImage wrapper cleanup remains in the stack.
  • Fixed the three-edit pairing typo boundary (--no-pair now fails closed like the CLI) and added regression coverage.
  • Moved the Linux marker-unusable message beside the downloaded-status producer and removed duplicate mock copies (net deletion).

Focused tests, typecheck, changed-code quality, formatting, and diff checks pass locally; the new CI run is in progress.

@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from 903d821 to 1486b1a Compare August 31, 2026 14:10
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 6fb82a6 to 785ad81 Compare August 31, 2026 14:10
@nwparker

Copy link
Copy Markdown
Contributor Author

Final restack note: #17683 now sits on #17320 1486b1a6205 and carries the reviewed cleanup as an equivalent cherry-picked commit (5e4c8f74849, source merge SHA 51add7e5987) plus the three-edit pairing typo fix (785ad81dff3). The duplicate updater refactor is inherited from #17318. All prior review threads are resolved or outdated; fresh CI is running.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Since the prior review, two commits landed: the three-edit pairing-flag typo threshold fix and a legacy AppImage CLI wrapper cleanup.

  • Three-edit typo threshold closed — getServeFlagTypoError now uses distance <= bestDistance, matching the CLI's SUGGESTION_THRESHOLD of 3, so a distance-3 truncation like --no-pair is rejected instead of silently leaving pairing enabled.
  • Test coverage extended — the typo suite adds --no-pair to the it.each cases, proving a distance-3 truncation is caught.
  • Legacy AppImage wrapper cleanup — inspectStableLegacyCommand delegates to the shared inspectStableCommand retry loop and treats a legacy command resolving to the current AppImage as managed, with a new install/remove test confirming foreign-AppImage wrappers are left intact.

Pullfrog  | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 785ad81 to 5264d60 Compare August 31, 2026 14:24

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

The new commit refined the pairing-flag typo gate to eliminate a false positive on legitimate Chromium/Electron switches without reopening the truncation fail-open.

  • Per-candidate edit-distance threshold — getServeFlagTypoError now rejects a typed flag at up to 3 edits only when the typed name is a prefix of a security flag (e.g. --no-pair vs --no-pairing); non-prefix near-misses are limited to 2 edits. This keeps the --no-pair truncation rejection while a distance-3 non-prefix switch like --no-parent is accepted instead of being mistaken for --no-pairing.
  • False-positive regression test — the "accepts arbitrary Chromium switches" case gained --no-parent, which the prior flat ≤ 3 rule would have flagged (the assertion is exact, so it fails against the old code).

Pullfrog  | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@nwparker

Copy link
Copy Markdown
Contributor Author

Rebase/CI follow-up complete: origin/main remains 212c0e42a651, so git rebase origin/main is a no-op. Current head 5264d602b8f is published and all required checks are green (run 33402417400, including package, native smoke, test shards, Pullfrog, and verify). The full stacked chain is mergeable/clean with no active unresolved review threads.

@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from 1486b1a to 1b1ca5d Compare September 1, 2026 09:18
@nwparker
nwparker requested a review from brennanb2025 as a September 1, 2026 09:18
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 5264d60 to 9fa7855 Compare September 1, 2026 09:19
@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from 1b1ca5d to ff0f27d Compare September 1, 2026 10:07
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 9fa7855 to eb4492e Compare September 1, 2026 10:07
@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from ff0f27d to 7e37e1e Compare September 1, 2026 10:29
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from eb4492e to 0e28dea Compare September 1, 2026 10:29
@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from 7e37e1e to 984b8cc Compare September 1, 2026 10:34
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 0e28dea to 12e998e Compare September 1, 2026 10:34
@nwparker
nwparker force-pushed the nwparker/linux-orcad-restart-safety branch from 984b8cc to cfda0c5 Compare September 1, 2026 10:41
@nwparker
nwparker force-pushed the nwparker/linux-serve-flag-validation branch from 12e998e to 4c7908e Compare September 1, 2026 10:41
@nwparker
nwparker merged commit 317d5c9 into nwparker/linux-orcad-restart-safety Sep 2, 2026
33 checks passed
nwparker added a commit that referenced this pull request Sep 2, 2026
* docs(linux): document orcad update restart safety

* docs(linux): scope restart census omissions

* docs(linux): use absolute service CLI launcher

* fix(serve): validate in-process serve options before startup (#17683)

* fix(linux): stop offering updates a distro-managed install cannot apply (#17918)

Closes #17702.

The resources/package-type marker is authoritative but never checked against
the host, so any repackager that unpacks Orca's .deb -- AUR, Nix, a container
rebuild -- inherits `deb` verbatim. Install feasibility was then computed
after a ~165 MB download, so those users got check -> download -> a card
promising an install command -> a dead end.

Validate the marker against the host: a deb/rpm marker with no matching
package manager in the trusted directories means a package manager owns this
install. This reuses the exact lists and resolver that
buildLinuxPackageInstallCommand already loops over, so a false positive is
impossible by construction -- any host flagged here would have failed with
no-package-manager after the download anyway. The gate only moves that
verdict earlier. Verified across Debian 12, Ubuntu 24.04, Arch, Fedora 40 and
openSUSE Leap: no false positive on a real deb host, correct on every
repackaging host.

The release is still reported, because the user does want to know 1.4.194
exists and to update through their distro; only the download path is closed.
`externallyManaged` is an additive optional field on the existing `available`
status, so older paired clients decode it unchanged. downloadUpdate() refuses
authoritatively, since main owns this verdict rather than the card, and
unwinds any pinned-build state first -- a Linux pinned jump resolves to
'release', and stranding isPinnedBuildActive would silently kill every
background check for the rest of the process.

Note the fix the issue suggests cannot work: electron-updater builds a
PacmanUpdater whose doDownloadUpdate looks for a .pacman asset Orca does not
publish, then dereferences undefined.
nwparker added a commit that referenced this pull request Sep 2, 2026
* fix(linux): give the CLI one entrypoint by extracting the AppImage once

* refactor(linux): trim AppImage CLI registration seams

* test(cli): assert registration lock serialization

* fix(linux): fence AppImage terminal shim mounts

* fix(linux): accept extracted AppImage runtimes with APPDIR only

* docs(linux): make headless AppImage extraction runnable

* refactor(linux): import bundled launcher directly

* fix(linux): reclaim superseded AppImage payloads and packaged symlinks

Pruning removed 3215 of 3216 files from a superseded generation and always
stranded resources/app.asar, leaking ~105 MB per version update. Electron's
asar shim reports a *.asar file as a directory, so the recursive remove tried
to rmdir a real file and failed with ENOTEMPTY; the .catch(() => {}) hid it.
Reproduced end to end on Ubuntu 24.04: 519M -> 623M across one update, and
519M again once the payload is actually reclaimed.

removeExtractedAppImagePayload holds process.noAsar for the removal, counted
so overlapping removals cannot hand the shim back early, and the prune site
now warns with the path instead of swallowing the rejection. All three
removal sites use it -- staging cleanup and displaced roots leaked the same
way.

Also reclaim symlinks left by a packaged deb/rpm install, which the
extracted-cache-only rule turned into a hard conflict on a deb -> AppImage
migration, and name the remedy in the conflict error.

* fix(linux): bound the CLI registration lock wait

`retries: 1000` caps the attempt count, not elapsed time, so at up to 1s per
attempt an IPC-driven registration could hang ~16 minutes against a wedged
holder with no feedback.

A legitimate holder is bounded by the extraction timeout, so wait that plus
slack and then fail with a message naming the lock file, rather than hanging.
`maxRetryTime` is forwarded verbatim to the `retry` package by proper-lockfile.

* fix(linux): stop re-extracting the AppImage on inode metadata churn

The extracted-payload cache key hashed ctime alongside dev/ino/size/mtime.
ctime moves on any inode metadata write -- `chmod +x`, which every AppImage
user is told to run, plus `chown`, an ACL or SELinux relabel, and a backup
restore -- none of which alter a byte of the payload.

Measured on Ubuntu 24.04: `chmod +x` leaves dev, ino, size and mtime
identical and moves ctime alone, so the key changed and the next launch paid
a full ~519 MB re-extraction and a multi-second stall to rebuild a payload it
already had, then pruned the old generation.

Key on content identity instead. An in-place content change moves mtime and
almost always size; a replacement moves the inode. The existing
replace-in-place test still passes.

* fix(linux): stop CLI commands from falling through to Chromium startup

* refactor(cli): remove redundant command membership check

* test(cli): cover command-named project selectors

* fix(cli): redirect the open-url command before startup

* test(linux): cover AUR serve wrapper flags

* fix(linux): tighten CLI launch detection

* fix(linux): respect CLI flag value boundaries

* fix(linux): strip injected Chromium switches from CLI args

* fix(linux): report a missing display instead of dying in uv_close

* refactor(linux): read display locks without a preflight race

* fix(linux): preserve unverified external displays

* chore: format reliability gate manifest

* test(packaging): split runtime resource checks

* fix(linux): fail serve when no display is available

* fix(linux): do not treat a lockless X socket as a dead display

An X server writes its lock beside its socket and both survive a crash
(verified against Xvfb under SIGKILL), so a socket with no lock was never
left by a crashed server. It is an endpoint published from elsewhere: a
container bind-mounting only /tmp/.X11-unix, WSLg, or a foreign PID
namespace. Declaring those dead made the desktop gate exit(1) on displays
that work, with no workaround, and the serve gate refuse to start.

Liveness now splits by ownership. A foreign DISPLAY trusts a lockless
socket; Orca's own :99 does not, because removeStaleDisplayArtifacts
unlinks the lock before the socket and so manufactures that state itself --
adopting it would resurrect the orphan-socket bug and stop the cleanup from
self-healing. The stale-lock rejection is unchanged.

Also correct four doc statements this behaviour falsified.

* fix(linux): fail closed when a stale socket blocks the Xvfb rebind

Readiness only checked that /tmp/.X11-unix/X99 exists. A stale socket we
could not unlink still exists after our own Xvfb refused to bind, so Orca set
DISPLAY to a dead server and Chromium died in Ozone init.

Measured on Ubuntu 24.04 against the pre-fix build: with a leftover :99
socket and no lock, serve exits 139 (SIGSEGV), the socket inode is unchanged
before and after, and no lock is recreated -- it neither cleaned up nor
respawned. To a user that is a crash, not a misconfiguration.

This is reachable in the documented topology, where orca-xvfb.service has no
User= and runs as root while serve runs as User=orca: /tmp is sticky, so the
orca uid cannot unlink a root-owned socket, rmSync fails, and Xvfb exits with
the display already active.

Readiness now requires the display to actually be live -- our socket plus a
lock naming a running process -- so the same state reports an unusable
display and exits 1 with the existing diagnosis.

* fix(linux): recognise abstract X sockets and inherited Wayland fds

Two display setups this gate could not prove were refused outright, and on the
desktop path that is app.exit(1) with no workaround.

An X server may bind only the abstract namespace (`@/tmp/.X11-unix/X0`), which
leaves no filesystem socket to stat. Abstract addresses are kernel-owned and
vanish the moment the owner exits, so an entry in /proc/net/unix is proof of a
live server -- no lock file needed and no stale entry possible. Verified on
Ubuntu 24.04, where 139 such addresses were present.

WAYLAND_SOCKET is an already-connected fd handed over by the compositor, so
there is no path to stat and WAYLAND_DISPLAY may be unset entirely. Its
presence is the display.

Both are consulted only after the filesystem-socket check fails, so no
existing verdict changes.

* fix(linux): never treat Orca's own display number as a foreign endpoint

Recognising a lockless X socket as live is correct for an endpoint published
from elsewhere -- a container bind mount, WSLg -- because an X server writes
its lock beside its socket and both survive a crash. It is wrong for
VIRTUAL_DISPLAY_NUMBER, because Orca's own teardown unlinks the lock before
the socket and so manufactures that exact state.

The managed branch was already strict, but a caller that sets DISPLAY=:99
explicitly takes the foreign path and skipped it, accepting a dead display
left by Orca's own interrupted cleanup. Route the managed number through the
strict probe on both paths.

Found by an adversarial audit of the asymmetry introduced earlier in this
branch; the documented systemd topology is unaffected because its Xvfb writes
a real lock.

* test(linux): add a packaged-artifact contract for the CLI launch paths

* test(linux): avoid buffered serve readiness detection

* test(linux): signal AppImage serve owner directly

* test(linux): tolerate readiness timeout boundary

* test(linux): add startup margin to shutdown oracle

* ci(linux): give package contracts timeout headroom

* fix(ci): route all Linux packaging contract changes

* test(linux): poll shutdown readiness without tail leaks

* test(linux): bound shutdown cleanup grace

* test(linux): assert on CLI output, not the harness's own control lines

run-cli-case.sh echoes `RESULT status=N case=<name>`, and the two cases named
*-skills asserted `expectOutput: 'skills'`. That substring was satisfied by
the case name in the harness's own line, so 2 of 8 cases asserted nothing
about the command -- gutting `skills` entirely would still have gone green.

Control lines are now excluded before matching, and both cases assert the
rendered help header, which only real help output produces. Verified on an
Ubuntu 24.04 host: 8/8 still pass against a stack-tip AppImage.

Also register the gate in reliability-gates.jsonc, which #15085 added a CI
Docker gate without. Red/green is recorded from a stock release AppImage
failing 4 of 8, three of them at status 133 (SIGTRAP).

* fix(linux): require static AppImage runtimes (#17319)

* test(linux): reject a wrong-architecture native binary at packaging time

Cross-building the arm64 slice on an x64 host silently packed an x86-64
`pty.node` -- the rebuild logged "Forcing native rebuild for linux-arm64" and
shipped the host's binary anyway. Every gate here inspects symbol versions,
which are perfectly valid on the wrong architecture, so nothing noticed.

Observed on a Raspberry Pi 5: the packaged app loaded, then failed with
"Failed to load native module: pty.node", and the launch contract reported
3 of 8 cases crashed rather than naming the cause. Swapping in the aarch64
`pty.node` took the same build to 8/8.

Compare ELF `e_machine` against the slice being packaged and fail with the
offending path. Checked before the glibc pass, because a wrong-architecture
binary's symbol versions are valid but meaningless and would send the reader
down the wrong path.

Release CI builds arm64 on a native runner, so this guards local and future
cross-builds rather than a shipped artifact.

* test(linux): judge per-arch vendored binaries against their own path

The first CI run of the architecture gate failed the x64 package job on
`@parcel/watcher-linux-arm64-glibc/watcher.node`. That binary is arm64 on
purpose: the package ships every architecture and its loader picks the match,
so its presence in an x64 build is correct.

Judge a binary against the architecture its own path names, falling back to
the slice when the path names none. That keeps the case this gate exists for
-- `bin/linux-arm64-*/node-pty.node` holding an x86-64 binary, which is what
shipped to a Raspberry Pi 5 -- while letting multi-arch dependencies through.

Dry-run over the real dependency tree flags nothing for either target arch.

* fix(linux): move deb/rpm update installation outside Orca (#17318)

* fix(linux): complete deb/rpm package metadata

* fix(linux): preserve CLI link during package upgrades

* docs(linux): document local RPM build prerequisites

* fix(linux): move deb/rpm update installation outside Orca

* fix(updater): preserve Linux recovery across stale events

* fix(updater): fence stale downloaded events by active target

* fix(updater): preserve active Linux package recovery

* test(linux): keep workflow order assertion in scope

* test(updater): assert stale recovery stays silent

* fix(updater): preserve Linux package recovery after checks

* refactor(updater): keep Linux marker message with status

* fix(linux): describe the right manual update path for deb/rpm hosts

A remote host installed from .deb or .rpm now reports
manual-service-update-required, and the guidance told the operator to
"update through the service manager that starts this server" -- which is
correct for unsupported-headless-serve but wrong for a package install,
where nothing about the remedy involves the service manager.

Say both, keyed on how the host was installed.

* docs(linux): document orcad update restart safety

* docs(linux): scope restart census omissions

* docs(linux): use absolute service CLI launcher

* fix(serve): validate in-process serve options before startup (#17683)

* fix(linux): stop offering updates a distro-managed install cannot apply (#17918)

Closes #17702.

The resources/package-type marker is authoritative but never checked against
the host, so any repackager that unpacks Orca's .deb -- AUR, Nix, a container
rebuild -- inherits `deb` verbatim. Install feasibility was then computed
after a ~165 MB download, so those users got check -> download -> a card
promising an install command -> a dead end.

Validate the marker against the host: a deb/rpm marker with no matching
package manager in the trusted directories means a package manager owns this
install. This reuses the exact lists and resolver that
buildLinuxPackageInstallCommand already loops over, so a false positive is
impossible by construction -- any host flagged here would have failed with
no-package-manager after the download anyway. The gate only moves that
verdict earlier. Verified across Debian 12, Ubuntu 24.04, Arch, Fedora 40 and
openSUSE Leap: no false positive on a real deb host, correct on every
repackaging host.

The release is still reported, because the user does want to know 1.4.194
exists and to update through their distro; only the download path is closed.
`externallyManaged` is an additive optional field on the existing `available`
status, so older paired clients decode it unchanged. downloadUpdate() refuses
authoritatively, since main owns this verdict rather than the card, and
unwinds any pinned-build state first -- a Linux pinned jump resolves to
'release', and stranding isPinnedBuildActive would silently kill every
background check for the rest of the process.

Note the fix the issue suggests cannot work: electron-updater builds a
PacmanUpdater whose doDownloadUpdate looks for a .pacman asset Orca does not
publish, then dereferences undefined.

* style(cli): restore prettier wrapping on install error copy

* test(linux): re-pin the child-process ratchets and the batch-shim allowlist after the merge
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…#18100)

* fix(linux): give the CLI one entrypoint by extracting the AppImage once

* refactor(linux): trim AppImage CLI registration seams

* test(cli): assert registration lock serialization

* fix(linux): fence AppImage terminal shim mounts

* fix(linux): accept extracted AppImage runtimes with APPDIR only

* docs(linux): make headless AppImage extraction runnable

* refactor(linux): import bundled launcher directly

* fix(linux): reclaim superseded AppImage payloads and packaged symlinks

Pruning removed 3215 of 3216 files from a superseded generation and always
stranded resources/app.asar, leaking ~105 MB per version update. Electron's
asar shim reports a *.asar file as a directory, so the recursive remove tried
to rmdir a real file and failed with ENOTEMPTY; the .catch(() => {}) hid it.
Reproduced end to end on Ubuntu 24.04: 519M -> 623M across one update, and
519M again once the payload is actually reclaimed.

removeExtractedAppImagePayload holds process.noAsar for the removal, counted
so overlapping removals cannot hand the shim back early, and the prune site
now warns with the path instead of swallowing the rejection. All three
removal sites use it -- staging cleanup and displaced roots leaked the same
way.

Also reclaim symlinks left by a packaged deb/rpm install, which the
extracted-cache-only rule turned into a hard conflict on a deb -> AppImage
migration, and name the remedy in the conflict error.

* fix(linux): bound the CLI registration lock wait

`retries: 1000` caps the attempt count, not elapsed time, so at up to 1s per
attempt an IPC-driven registration could hang ~16 minutes against a wedged
holder with no feedback.

A legitimate holder is bounded by the extraction timeout, so wait that plus
slack and then fail with a message naming the lock file, rather than hanging.
`maxRetryTime` is forwarded verbatim to the `retry` package by proper-lockfile.

* fix(linux): stop re-extracting the AppImage on inode metadata churn

The extracted-payload cache key hashed ctime alongside dev/ino/size/mtime.
ctime moves on any inode metadata write -- `chmod +x`, which every AppImage
user is told to run, plus `chown`, an ACL or SELinux relabel, and a backup
restore -- none of which alter a byte of the payload.

Measured on Ubuntu 24.04: `chmod +x` leaves dev, ino, size and mtime
identical and moves ctime alone, so the key changed and the next launch paid
a full ~519 MB re-extraction and a multi-second stall to rebuild a payload it
already had, then pruned the old generation.

Key on content identity instead. An in-place content change moves mtime and
almost always size; a replacement moves the inode. The existing
replace-in-place test still passes.

* fix(linux): stop CLI commands from falling through to Chromium startup

* refactor(cli): remove redundant command membership check

* test(cli): cover command-named project selectors

* fix(cli): redirect the open-url command before startup

* test(linux): cover AUR serve wrapper flags

* fix(linux): tighten CLI launch detection

* fix(linux): respect CLI flag value boundaries

* fix(linux): strip injected Chromium switches from CLI args

* fix(linux): report a missing display instead of dying in uv_close

* refactor(linux): read display locks without a preflight race

* fix(linux): preserve unverified external displays

* chore: format reliability gate manifest

* test(packaging): split runtime resource checks

* fix(linux): fail serve when no display is available

* fix(linux): do not treat a lockless X socket as a dead display

An X server writes its lock beside its socket and both survive a crash
(verified against Xvfb under SIGKILL), so a socket with no lock was never
left by a crashed server. It is an endpoint published from elsewhere: a
container bind-mounting only /tmp/.X11-unix, WSLg, or a foreign PID
namespace. Declaring those dead made the desktop gate exit(1) on displays
that work, with no workaround, and the serve gate refuse to start.

Liveness now splits by ownership. A foreign DISPLAY trusts a lockless
socket; Orca's own :99 does not, because removeStaleDisplayArtifacts
unlinks the lock before the socket and so manufactures that state itself --
adopting it would resurrect the orphan-socket bug and stop the cleanup from
self-healing. The stale-lock rejection is unchanged.

Also correct four doc statements this behaviour falsified.

* fix(linux): fail closed when a stale socket blocks the Xvfb rebind

Readiness only checked that /tmp/.X11-unix/X99 exists. A stale socket we
could not unlink still exists after our own Xvfb refused to bind, so Orca set
DISPLAY to a dead server and Chromium died in Ozone init.

Measured on Ubuntu 24.04 against the pre-fix build: with a leftover :99
socket and no lock, serve exits 139 (SIGSEGV), the socket inode is unchanged
before and after, and no lock is recreated -- it neither cleaned up nor
respawned. To a user that is a crash, not a misconfiguration.

This is reachable in the documented topology, where orca-xvfb.service has no
User= and runs as root while serve runs as User=orca: /tmp is sticky, so the
orca uid cannot unlink a root-owned socket, rmSync fails, and Xvfb exits with
the display already active.

Readiness now requires the display to actually be live -- our socket plus a
lock naming a running process -- so the same state reports an unusable
display and exits 1 with the existing diagnosis.

* fix(linux): recognise abstract X sockets and inherited Wayland fds

Two display setups this gate could not prove were refused outright, and on the
desktop path that is app.exit(1) with no workaround.

An X server may bind only the abstract namespace (`@/tmp/.X11-unix/X0`), which
leaves no filesystem socket to stat. Abstract addresses are kernel-owned and
vanish the moment the owner exits, so an entry in /proc/net/unix is proof of a
live server -- no lock file needed and no stale entry possible. Verified on
Ubuntu 24.04, where 139 such addresses were present.

WAYLAND_SOCKET is an already-connected fd handed over by the compositor, so
there is no path to stat and WAYLAND_DISPLAY may be unset entirely. Its
presence is the display.

Both are consulted only after the filesystem-socket check fails, so no
existing verdict changes.

* fix(linux): never treat Orca's own display number as a foreign endpoint

Recognising a lockless X socket as live is correct for an endpoint published
from elsewhere -- a container bind mount, WSLg -- because an X server writes
its lock beside its socket and both survive a crash. It is wrong for
VIRTUAL_DISPLAY_NUMBER, because Orca's own teardown unlinks the lock before
the socket and so manufactures that exact state.

The managed branch was already strict, but a caller that sets DISPLAY=:99
explicitly takes the foreign path and skipped it, accepting a dead display
left by Orca's own interrupted cleanup. Route the managed number through the
strict probe on both paths.

Found by an adversarial audit of the asymmetry introduced earlier in this
branch; the documented systemd topology is unaffected because its Xvfb writes
a real lock.

* test(linux): add a packaged-artifact contract for the CLI launch paths

* test(linux): avoid buffered serve readiness detection

* test(linux): signal AppImage serve owner directly

* test(linux): tolerate readiness timeout boundary

* test(linux): add startup margin to shutdown oracle

* ci(linux): give package contracts timeout headroom

* fix(ci): route all Linux packaging contract changes

* test(linux): poll shutdown readiness without tail leaks

* test(linux): bound shutdown cleanup grace

* test(linux): assert on CLI output, not the harness's own control lines

run-cli-case.sh echoes `RESULT status=N case=<name>`, and the two cases named
*-skills asserted `expectOutput: 'skills'`. That substring was satisfied by
the case name in the harness's own line, so 2 of 8 cases asserted nothing
about the command -- gutting `skills` entirely would still have gone green.

Control lines are now excluded before matching, and both cases assert the
rendered help header, which only real help output produces. Verified on an
Ubuntu 24.04 host: 8/8 still pass against a stack-tip AppImage.

Also register the gate in reliability-gates.jsonc, which stablyai#15085 added a CI
Docker gate without. Red/green is recorded from a stock release AppImage
failing 4 of 8, three of them at status 133 (SIGTRAP).

* fix(linux): require static AppImage runtimes (stablyai#17319)

* test(linux): reject a wrong-architecture native binary at packaging time

Cross-building the arm64 slice on an x64 host silently packed an x86-64
`pty.node` -- the rebuild logged "Forcing native rebuild for linux-arm64" and
shipped the host's binary anyway. Every gate here inspects symbol versions,
which are perfectly valid on the wrong architecture, so nothing noticed.

Observed on a Raspberry Pi 5: the packaged app loaded, then failed with
"Failed to load native module: pty.node", and the launch contract reported
3 of 8 cases crashed rather than naming the cause. Swapping in the aarch64
`pty.node` took the same build to 8/8.

Compare ELF `e_machine` against the slice being packaged and fail with the
offending path. Checked before the glibc pass, because a wrong-architecture
binary's symbol versions are valid but meaningless and would send the reader
down the wrong path.

Release CI builds arm64 on a native runner, so this guards local and future
cross-builds rather than a shipped artifact.

* test(linux): judge per-arch vendored binaries against their own path

The first CI run of the architecture gate failed the x64 package job on
`@parcel/watcher-linux-arm64-glibc/watcher.node`. That binary is arm64 on
purpose: the package ships every architecture and its loader picks the match,
so its presence in an x64 build is correct.

Judge a binary against the architecture its own path names, falling back to
the slice when the path names none. That keeps the case this gate exists for
-- `bin/linux-arm64-*/node-pty.node` holding an x86-64 binary, which is what
shipped to a Raspberry Pi 5 -- while letting multi-arch dependencies through.

Dry-run over the real dependency tree flags nothing for either target arch.

* fix(linux): move deb/rpm update installation outside Orca (stablyai#17318)

* fix(linux): complete deb/rpm package metadata

* fix(linux): preserve CLI link during package upgrades

* docs(linux): document local RPM build prerequisites

* fix(linux): move deb/rpm update installation outside Orca

* fix(updater): preserve Linux recovery across stale events

* fix(updater): fence stale downloaded events by active target

* fix(updater): preserve active Linux package recovery

* test(linux): keep workflow order assertion in scope

* test(updater): assert stale recovery stays silent

* fix(updater): preserve Linux package recovery after checks

* refactor(updater): keep Linux marker message with status

* fix(linux): describe the right manual update path for deb/rpm hosts

A remote host installed from .deb or .rpm now reports
manual-service-update-required, and the guidance told the operator to
"update through the service manager that starts this server" -- which is
correct for unsupported-headless-serve but wrong for a package install,
where nothing about the remedy involves the service manager.

Say both, keyed on how the host was installed.

* docs(linux): document orcad update restart safety

* docs(linux): scope restart census omissions

* docs(linux): use absolute service CLI launcher

* fix(serve): validate in-process serve options before startup (stablyai#17683)

* fix(linux): stop offering updates a distro-managed install cannot apply (stablyai#17918)

Closes stablyai#17702.

The resources/package-type marker is authoritative but never checked against
the host, so any repackager that unpacks Orca's .deb -- AUR, Nix, a container
rebuild -- inherits `deb` verbatim. Install feasibility was then computed
after a ~165 MB download, so those users got check -> download -> a card
promising an install command -> a dead end.

Validate the marker against the host: a deb/rpm marker with no matching
package manager in the trusted directories means a package manager owns this
install. This reuses the exact lists and resolver that
buildLinuxPackageInstallCommand already loops over, so a false positive is
impossible by construction -- any host flagged here would have failed with
no-package-manager after the download anyway. The gate only moves that
verdict earlier. Verified across Debian 12, Ubuntu 24.04, Arch, Fedora 40 and
openSUSE Leap: no false positive on a real deb host, correct on every
repackaging host.

The release is still reported, because the user does want to know 1.4.194
exists and to update through their distro; only the download path is closed.
`externallyManaged` is an additive optional field on the existing `available`
status, so older paired clients decode it unchanged. downloadUpdate() refuses
authoritatively, since main owns this verdict rather than the card, and
unwinds any pinned-build state first -- a Linux pinned jump resolves to
'release', and stranding isPinnedBuildActive would silently kill every
background check for the rest of the process.

Note the fix the issue suggests cannot work: electron-updater builds a
PacmanUpdater whose doDownloadUpdate looks for a .pacman asset Orca does not
publish, then dereferences undefined.

* style(cli): restore prettier wrapping on install error copy

* test(linux): re-pin the child-process ratchets and the batch-shim allowlist after the merge
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant