fix(desktop): Linux URL handler quotes the Exec path only when it must

[Mnigos]

The Linux URL handler always quotes its executable path. Older xdg-open generic handlers look up the first Exec word without unquoting it, so ordinary AppImage paths fail lookup and callbacks open in a browser.

Quote only paths containing Desktop Entry reserved characters. Keep both escaping layers and literal percent doubling. Both URL-handler writers use conditional quoting. The KDE capture helper retains its existing always-quoted serialization so previously installed helpers stay ready without a setup update. Credit to @Mnigos for #16670 and @tunnckoCore for tracing the legacy lookup failure. Fixes #16632.

Verification:

• 39 tests pass across the URL handler, pre-ready, and KDE capture suites (38 before test cleanup). Restoring main's URL serialization produces 4 failures; restoring it passes all 39.
• Real /bin/sh lookup against a temporary executable: quoted baseline exits 127; corrected plain path resolves and launches with the expected URL. This models the legacy lookup, not the complete xdg-open flow.
• KDE helper output is byte-identical to main for plain, percent-containing, and reserved-character paths; existing helper installations retain their serialization.
• Desktop typecheck and targeted lint/formatting pass.

This VM is headless Linux and has no xdg-open/gio, display, or Electron GUI dependencies. No real desktop OAuth callback, KDE capture, or packaged Electron launch was verified; macOS, Windows, iOS, and Android were not tested. The change is serialization, so screenshots do not show its behavior. Legacy generic xdg-open still cannot handle executable paths that require quotes or contain literal percent signs; this change improves ordinary installation paths.

Maintainer takeover: Codex GPT-6.1-Sol; tests: Codex GPT-6-Astra; independent review: Claude Opus 5.5 and Codex GPT-6-Sol. Harness: T3 Code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7a20f431-85a9-4545-8af0-56055c5b2b4c

📥 Commits

Reviewing files that changed from the base of the PR and between 7f99660 and 7c116a1.

📒 Files selected for processing: 2

• apps/desktop/src/app/DesktopLinuxUrlHandler.test.ts
• apps/desktop/src/app/DesktopLinuxUrlHandler.ts

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

📝 Walkthrough

Linux URL-handler desktop entries now conditionally quote the executable target. Targets that do not require quoting use desktop-entry string escaping, which doubles percent signs. Tests cover the escaping behavior and rendered entries.

Changes: Linux Exec argument escaping

Layer / File(s)	Summary
Conditional argument escaping apps/desktop/src/app/DesktopLinuxUrlHandler.ts, apps/desktop/src/app/DesktopLinuxUrlHandler.test.ts, apps/desktop/src/app/DesktopPreReadyPlatform.test.ts	The renderer quotes targets that contain characters requiring quoted Exec-argument escaping. Other targets use desktop-entry string escaping, which doubles percent signs. Tests cover parentheses, percent-encoded spaces, the AppImage path, and the complete non-AppImage fallback entry.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: juliusmarminge, kvnloo

Merge Risk: ⚪ Minimal · up to 7c116

Ordinary Linux executable paths receive the unquoted URL-handler entry, while paths requiring quotes retain their prior serialization. No new merge-blocking risk was identified.

Security architecture risk: 🔵 Low · up to 7c116

The change preserves executable selection, URL argument separation, and existing registration authority. No new security concern was identified. Risk is low because the changed launch syntax has not been verified through actual desktop launchers and end-to-end callbacks.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The affected authority is the existing Linux desktop handler for t3code or t3code-dev. The comparison shows no added service dependency, credential access, or cross-tenant authority; exposure changes are confined to how an existing executable target is presented to desktop launchers.

Trust Boundaries and Controls

• observed — Local launch-environment inputs select the executable before desktop dispatch. Callback URLs enter through the existing %U argument placeholder, not through the executable selector. The PR changes serialization at this boundary without adding a callback-controlled target or weakening the reserved-character escaping branch.

Resilience and Maintainability Implications

• observed — The writers retain their pre-existing direct-write behavior, and pre-ready setup still swallows setup failures. Neither atomic replacement nor transactional recovery is introduced. These remain existing lifecycle properties, not demonstrated PR-introduced security regressions.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title is concise and accurately identifies the Linux URL-handler fix: conditional quoting of the Exec path.
Description check		The description explains the problem, the conditional escaping change, scope and issue references, verification results, limitations, and agent attribution. It does not use the template headings, but …
Linked Issues check		Issue [#16632] requires the Linux t3code:// desktop entry to work with the legacy xdg-utils generic fallback. renderUrlHandlerDesktopEntry now leaves ordinary executable paths unquoted, doubles li…
Out of Scope Changes check		The changes stay within [#16632]. The implementation changes URL-handler Exec serialization only. The updated registration, pre-ready, and serialization tests support that fix. No unrelated product …

Full details: Description check

Explanation

The description explains the problem, the conditional escaping change, scope and issue references, verification results, limitations, and agent attribution. It does not use the template headings, but it provides the required information in a complete and focused form.

Full details: Linked Issues check

Explanation

Issue [#16632] requires the Linux t3code:// desktop entry to work with the legacy xdg-utils generic fallback. renderUrlHandlerDesktopEntry now leaves ordinary executable paths unquoted, doubles literal %, and keeps Desktop Entry escaping for paths that require quoting. The registration and pre-ready tests verify the plain-path output. The focused tests also verify reserved-character and percent-containing paths.

Full details: Out of Scope Changes check

Explanation

The changes stay within [#16632]. The implementation changes URL-handler Exec serialization only. The updated registration, pre-ready, and serialization tests support that fix. No unrelated product behavior is changed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

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

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

[macroscopeapp]

Approvability

Verdict: Approved at 7c116a1

Macroscope's review found this PR approvable — This is a small, self-contained Linux URL-handler bug fix that conditionally quotes existing Exec paths while preserving escaping for paths that require it. Production behavior changes only in desktop-entry serialization, with focused tests covering reserved characters and literal percent signs.

^{You can add or adjust custom eligibility rules. Learn more.}

[kvnloo]

Reviewed at dfeed739 — approve. Thanks @Mnigos for the focused patch, and credit to @tunnckoCore for tracing the original xdg-utils failure and @Serendeep for the CachyOS/Zen reproduction.

I independently reproduced the exact launcher boundary with the installed xdg-open 1.2.1, not just a mocked first_word: using an isolated XDG_DATA_HOME/XDG_CONFIG_HOME, XDG_CURRENT_DESKTOP=sway, a test x-scheme-handler entry, and recording handler/browser scripts:

Exec="/tmp/.../handler" %U  → BROWSER:t3test://app/hello
Exec=/tmp/.../handler %U    → HANDLER:t3test://app/hello

That supports the root cause and shows the new serialization reaches the intended URL handler via the actual generic xdg-open path. No T3/Clerk credentials or live OAuth were exercised in this isolated test.

Review of the diff: the reserved-character set agrees with the current freedesktop Exec rules; % doubling and both escaping layers are retained; both desktop-handler writers share the helper; paths requiring quoting retain the existing serialization. The KDE helper is an additional caller, but its existing space-containing path remains quoted. Scope is 3 files / 1 production helper, and the PR-head GitHub CI Test, Build, Lint and Typecheck jobs passed.

Nonblocking limits, as already acknowledged by the PR: legacy generic xdg-open still cannot launch an executable path requiring quotes (or containing %); and a browser launched with a different HOME/XDG registry can still fail independently. A final user-level CachyOS + Zen + running AppImage OAuth smoke test would be useful before considering #16632 fully closed, but I don't see a reason to expand this narrow fix to solve those unrelated launcher constraints.

Dismissing prior approval to re-evaluate dfeed73

Dismissing prior approval to re-evaluate 7f99660

[juliusmarminge]

Taking over this one as maintainer for batch desktop-app-01. I will merge current main, keep the conditional Exec quoting fix focused, preserve author credit, and run fresh tests and independent reviews. No merge in this pass.

Dismissing prior approval to re-evaluate 7c116a1