Skip to content

fix(linux): stop Orca-managed terminals from launching the GNOME Orca screen reader via bare orca - #8347

Merged
nwparker merged 1 commit into
mainfrom
nwparker/bug-launching-orca-starts-the-gnome-orca-screen
Jul 12, 2026
Merged

nwparker merged 1 commit into
mainfrom
nwparker/bug-launching-orca-starts-the-gnome-orca-screen

Conversation

@nwparker

@nwparker nwparker commented Jul 12, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #7904

Problem

On stock Ubuntu GNOME, /usr/bin/orca is the GNOME screen reader. The Linux CLI already installs as orca-ide precisely to avoid shadowing it (since v1.4.36) — but every agent-facing surface still tells agents to run bare orca:

  • the orca-cli skill (command -v orca || command -v orca-ide, then orca status --json, …)
  • orchestration dispatch preambles (src/main/runtime/orchestration/preamble.ts uses orca in prod)
  • runtime CLI hint texts (orca linear …, orca terminal focus …)

So an agent inside an Orca-managed terminal on Ubuntu resolves orca to /usr/bin/orca and starts the screen reader, which begins speaking — exactly what the reporter hit ("launching Orca / using the orca MCP starts the GNOME Orca screen reader").

Fix

Scope a bare-orca shim to Orca-managed PTYs only, instead of touching the user's shells:

  • src/main/cli/linux-terminal-orca-cli-shim.ts (new) — writes <userData>/linux-orca-cli-shim/orca, a script that execs the bundled orca-ide launcher (or the stable $APPIMAGE wrapper when running from an AppImage). Memoized per userData path; failures are not cached; exec bit re-asserted for stale shims.
  • src/main/ipc/pty.ts — on packaged Linux, buildPtyHostEnv prepends that dir to the PTY PATH, mirroring the existing dev-mode cli/bin prepend, and covering both spawn paths (local provider + daemon) by construction.
  • src/main/cli/linux-bare-orca-dispatcher.ts — extracted the script builder (buildBareOrcaCliScript) so the existing orca serve ~/.local/bin dispatcher and the new PTY shim share one implementation; dispatcher marker behavior unchanged.
  • skills/orca-cli/SKILL.md — probe flipped to command -v orca-ide || command -v orca with a warning, so agents running outside Orca terminals on Linux never execute the screen reader while probing; header now states that orca is always safe inside Orca-managed terminals.

This deliberately does not install a global bare orca on desktop Linux (the reporter's own workaround): shadowing /usr/bin/orca account-wide would break the screen reader command for accessibility users. The shim is visible only on Orca-managed PTY PATHs.

Testing

  • New unit tests for the shim module (script content/quoting, AppImage target, exec-bit healing, no-launcher failure not cached).
  • New pty.test.ts case: packaged Linux spawn gets the shim dir ahead of /usr/bin on PATH.
  • Full src/main/ipc/pty.test.ts (284) and src/main/cli/ (63) suites pass; typecheck clean. (pnpm lint fails on main for an unrelated localization-catalog key in UsagePercentageDisplayChangeNotice.tsx; changed files are oxlint/oxfmt clean.)
  • Live simulation: a shim generated exactly like the module's output, first on PATH, routes orca status --json to the bundled launcher.

Runtime behavior is packaged-Linux-only, so it cannot be exercised in a macOS dev Electron; verified via the unit suites + PATH simulation above.

Known remaining gaps (pre-existing, not addressed here)

  • WSL: the guest CLI installs as orca-ide and WSL PTYs (Windows host) don't get this shim, so bare-orca preamble commands are command-not-found there (no screen-reader risk).
  • rc files that fully rewrite PATH can drop the prepend — same exposure as the existing dev-mode CLI prepend.

Made with Orca 🐋

…reader via bare `orca`

On Linux the CLI installs as orca-ide so it never shadows /usr/bin/orca
(GNOME's screen reader), but agent-facing surfaces (orca-cli skill,
dispatch preambles, CLI hints) all invoke bare `orca` — so on stock
Ubuntu an agent inside an Orca terminal launched the screen reader,
which started speaking (#7904).

Fix: prepend a userData-scoped shim dir (bare `orca` -> bundled
orca-ide launcher, or the stable AppImage) to the PATH of every
packaged-Linux managed PTY, mirroring the existing dev-mode cli/bin
prepend. The user's own shells — and their real screen reader command —
stay untouched. Also flip the orca-cli skill probe to prefer orca-ide
so agents outside Orca terminals never execute the screen reader.

Fixes #7904

Co-authored-by: Orca <help@stably.ai>
@coderabbitai

coderabbitai Bot commented Jul 12, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2bcd36b0-dda4-4877-b36a-c62c8b64c876

📥 Commits

Reviewing files that changed from the base of the PR and between 93497ac and 66396c1.

📒 Files selected for processing (6)
  • skills/orca-cli/SKILL.md
  • src/main/cli/linux-bare-orca-dispatcher.ts
  • src/main/cli/linux-terminal-orca-cli-shim.test.ts
  • src/main/cli/linux-terminal-orca-cli-shim.ts
  • src/main/ipc/pty.test.ts
  • src/main/ipc/pty.ts

📝 Walkthrough

Walkthrough

Adds a reusable bare-orca dispatcher script builder and a per-user Linux terminal shim that targets either the bundled orca-ide launcher or a stable AppImage. Packaged Linux PTY environments now prepend the shim directory to PATH. Tests cover script creation, executable permissions, memoization, recovery, AppImage selection, and PTY PATH ordering. Documentation updates clarify orca and orca-ide resolution behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description is missing most required template sections, including Summary, Screenshots, AI Review Report, Security Audit, and Notes. Add the required template sections and include testing, review, security, screenshots/no-visual-change, and notes details.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed It clearly summarizes the main fix: preventing Orca-managed terminals from launching the GNOME screen reader via bare orca.
Linked Issues check ✅ Passed The PR implements the #7904 fix by scoping an orca shim to managed Linux PTYs and avoiding a global shadow of /usr/bin/orca.
Out of Scope Changes check ✅ Passed The changes stay focused on the Linux orca collision fix, related PTY wiring, shared script logic, tests, and doc updates.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

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

@nwparker
nwparker merged commit 42cf64c into main Jul 12, 2026
3 checks passed
@nwparker
nwparker deleted the nwparker/bug-launching-orca-starts-the-gnome-orca-screen branch July 12, 2026 07:38
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…reader via bare `orca` (stablyai#8347)

On Linux the CLI installs as orca-ide so it never shadows /usr/bin/orca
(GNOME's screen reader), but agent-facing surfaces (orca-cli skill,
dispatch preambles, CLI hints) all invoke bare `orca` — so on stock
Ubuntu an agent inside an Orca terminal launched the screen reader,
which started speaking (stablyai#7904).

Fix: prepend a userData-scoped shim dir (bare `orca` -> bundled
orca-ide launcher, or the stable AppImage) to the PATH of every
packaged-Linux managed PTY, mirroring the existing dev-mode cli/bin
prepend. The user's own shells — and their real screen reader command —
stay untouched. Also flip the orca-cli skill probe to prefer orca-ide
so agents outside Orca terminals never execute the screen reader.

Fixes stablyai#7904

Co-authored-by: Orca <help@stably.ai>
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.

[Bug]: Launching Orca starts the GNOME Orca screen reader on Ubuntu (CLI installs as orca, colliding with /usr/bin/orca)

1 participant