[DeJeune]

What this PR does

Before this PR:

Windows and Linux SDK bindings could only select running applications. Binding an
installed app such as Calculator failed with UNSUPPORTED_CAPABILITY before launch.

After this PR:

• Resolve installed identities without launching: Windows AppsFolder/AUMIDs and
  executable paths; Linux XDG desktop names, IDs and paths.
• Revalidate the authorized identity before native launch, preserve running-only
  reacquisition, and wait for a matching accessible window.
• Linux launches per the Desktop Entry Specification with no GIO tools:
  DBusActivatable entries receive org.freedesktop.Application.Activate on the
  session bus (Exec only when no service is installed); other entries run their
  expanded Exec, detached from the runtime, opted into accessibility for Qt, Gecko
  and Chromium. Terminal entries are rejected.
• Carry installed identity through app discovery, sessions and snapshots, while
  preserving possible effects after dispatch failures or cancellation. Linux maps
  owners of activatable application bus names to identities first.
• Add native and protocol cold-launch coverage (Exec and D-Bus activation on Linux),
  CI integration, SDK guidance and a Changesets patch entry.

Fixes: None.

Why we need it and why it was done in this way

The shared Go backend explicitly rejected installed lookup and launch, while the
macOS backend already supported both. The optional application driver completes
that path without changing the wire protocol or host authorization contract.

The first Linux version delegated to gio launch. Real-machine acceptance on GNOME
showed that it exits before its D-Bus Activate call is delivered: the service of a
DBusActivatable app starts, never opens a window and quits from inactivity
(Clocks, Text Editor, Files, Settings; 17 entries on a stock Ubuntu GNOME). GLib
works around this dbus-daemon race only in gio open and gtk-launch.

The following tradeoffs were made:

• Windows launches through native Shell/application activation APIs outside the
  temporary UIA worker's kill-on-close Job Object.
• Linux expands Exec in Go (quoting, field codes, Path, Flatpak @@u markers
  passed through) instead of depending on GIO tools, which Debian-family KDE or
  minimal compositor installs may lack. A one-line POSIX sh shim records
  GIO_LAUNCHED_DESKTOP_FILE_PID before exec, so the runtime and desktop shells
  can associate the process with its entry. The command itself never runs in a shell.
• A Flatpak export resolves into a directory named after its deployment commit.
  Identity uses the installation's active link instead, while that link points
  at the same deployment, so updates keep the identity. Full symlink resolution
  still prevents aliases from creating a second identity.
• Chromium overwrites its environment to set process titles, so an Electron app's
  launch metadata cannot be read back. The runtime therefore remembers the exact
  PIDs it launched, with their start times, so a reused PID never inherits an
  identity. AppImages are matched by APPIMAGE only for processes running from
  the image's mount (APPDIR), so programs they start do not inherit the identity.
• D-Bus-activated processes run a service command line without launch metadata,
  so discovery first asks the bus which PID owns the application's name.
• Exec launches set QT_LINUX_ACCESSIBILITY_ALWAYS_ON, GNOME_ACCESSIBILITY and
  ACCESSIBILITY_ENABLED for the launched process only. Enabling
  org.a11y.Status.IsEnabled would also reach running apps, but GNOME persists it
  as a user setting. D-Bus-activated services do not inherit these variables.
• Chromium/Electron programs also get --force-renderer-accessibility; no
  environment variable or session setting exposes their page content. The switch
  is added only when Chromium's chrome_100_percent.pak sits beside the resolved
  program (or one level above a wrapper script, as with VS Code), or inside an
  AppImage. The AppImage is mounted read-only with its runtime's --appimage-mount,
  without running its application. Unknown programs never get the switch.
  Retrying with the switch after a failed launch was rejected: Electron does not
  fail without it, and relaunching would replay the launch or reach a
  single-instance app that ignores new switches.
• A Qt app with a GTK platform theme registers twice on AT-SPI. Discovery drops a
  childless registration when the same process has a populated one; otherwise
  every lookup of that app is ambiguous.
• Windows/Linux desktop policy may foreground launched applications.

The following alternatives were considered:

• Launching through a model terminal workaround would bypass the SDK identity and
  host stop checks.
• gtk-launch handles the race but takes only desktop IDs and adds a GTK tool
  dependency.
• Loading libgio through purego would reuse GIO fully but needs a GLib main loop
  and callbacks inside a CGO_ENABLED=0 runtime.
• go-freedesktop/desktopentry expands Exec but was 12 days old with no known
  importers.

Links to places where the discussion took place: None.

Breaking changes

None. Existing running-only bindings and legacy CLI/MCP launch policy are preserved.
Hosts need matching updated native artifacts to enable the new startup behavior.

Special notes for your reviewer

Validated:

• Shared Go resolver, desktop and app-stop regression tests, plus Go vet.
• Windows executable/packaged identities and cold launch of a GUI executable from
  a path containing Chinese characters and spaces; Calculator cold launch through
  the TypeScript SDK, including identity mismatch and launch: false preflight.
• Windows and Linux x64/arm64 runtime builds; Linux built with CGO_ENABLED=0.
• Linux real machine (Ubuntu 24.04 GNOME 46 Wayland, arm64): through the SDK,
  Calculator (Exec) and Clocks, Text Editor and Files (D-Bus activation) cold-launch
  with the correct identity and an accessibility tree. So do KWrite (Qt 6, native
  Wayland) and Snap Firefox, which used to time out. Name, ID, executable and
  path queries resolve; ambiguity, mismatch and launch: false are rejected
  without effects.
• Linux isolated sessions: the SDK cold-launch test passes for both Exec and
  D-Bus activation in X11, KDE KWin, Sway, Hyprland (nested in labwc) and headless
  GNOME Shell, each with native Wayland and XWayland apps where applicable. It
  also passes in KWin with gio, gtk-launch and gapplication hidden. CI runs
  it in every compositor job. With the old gio launch dispatch, the D-Bus case
  times out. The existing X11 engine/input suite still passes with the extended
  fixture.
• Linux desktop-entry tests, including spec Exec expansion and bus-name rules.
• SDK build/typecheck and five affected TypeScript client tests; Cherry Studio
  integration: 31 scoped control/REPL tests with scoped lint/format and docs checks.

The Windows executable symlink test skipped because the test host lacks symlink
privilege.

Not yet covered

Deferred to follow-ups and tracked in docs/exec-plans/tech-debt-tracker.md.

Desktops and sessions. The compositors above ran isolated, not as full logged-in
desktops, and only GNOME Wayland was tested on a real machine (arm64).

• Full Plasma, Hyprland and Sway logins, and the KDE X11 session (kwin_x11). In
  these, the session itself must export the display to D-Bus activation.
• XFCE, Cinnamon and MATE. No launch code is desktop-specific, and isolated X11
  passes, but these desktops were not installed.
• A real GNOME on X11 session, an x64 real machine, and non-systemd distributions.
  The isolated sessions use a plain dbus-daemon, not systemd activation.

Launch paths:

• No integration test for ServiceUnknown falling back to Exec, for an Activate
  error or cancellation after dispatch, for Path=, or for rejecting terminal entries.
• Launched apps get no systemd scope of their own. They stay in the runtime host's
  scope: KWrite started this way landed in app-com.anthropic.Claude-*.scope.
  Desktops may attribute the app to the host, and stopping that scope can end the app.
• No startup notification or Wayland activation token is passed, so focus follows
  compositor policy.
• Only Calculator was retried while already running; D-Bus apps were not.

Applications:

• Working: a GTK 3 fixture plus GTK 4/libadwaita apps (Calculator, Clocks, Text
  Editor, Files).
• Qt 6 (KWrite) on GNOME Wayland works when launched by the SDK. Qt apps that are
  already running, or that are started by D-Bus activation, still expose no tree
  until accessibility is enabled session-wide.
• Snap Firefox works when launched by the SDK from an unconfined host. Its AppArmor
  policy refuses AT-SPI to clients with another label: this test session runs as
  claude-desktop and was denied. A Firefox that is already running gets no opt-in.
• Electron (T3 Code from /opt with a quoted Exec and duplicate entries; Obsidian
  as an AppImage): launch, identity and page content work (103 and 104 elements;
  one without the detected switch). MuseScore and Calculator launch without it.
  Electron apps from Snap or Flatpak are not detected, so they get no switch.
• AppImage (Qt): MuseScore launches and is identified through its AppRun child.
  Its Qt Quick UI returns empty references for most of its 75 children.
• Flatpak: GNOME Weather (D-Bus activation through Flatpak's exported service) and
  KCalc (Qt 6) cold-launch by name in isolated X11, KWin and GNOME Shell sessions
  configured as after login. Identities come from .flatpak-info, and the Qt
  opt-in reaches the sandbox. In a session started before Flatpak was installed,
  neither app resolves by name and Weather cannot be activated (no bus service)
  until the user logs in again. This matches the desktop shells. A real desktop
  after re-login is untested.
• Not tried: Java, Wine, and KDE apps on a full KDE desktop.

Linux acceptance commands (need Xvfb or Xephyr, AT-SPI, Python GI and GTK 3 for the
fixture; the runtime needs neither Python nor GIO):

npm ci --ignore-scripts
npm run sdk:build
mkdir -p dist/native
(cd apps/OpenComputerUseLinux && go build -o ../../dist/native/open-computer-use .)
apps/OpenComputerUseLinux/testdata/x11-session.sh sh apps/OpenComputerUseLinux/testdata/app-launch-session.sh
(cd apps/OpenComputerUseLinux && COMPUTER_USE_LINUX_LAUNCH_TEST=1 testdata/x11-session.sh go test . -run SDKColdLaunchDesktopEntry -count=1 -v)

SDK/native packages have not been published.

Checklist

• Branch: This PR targets main
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and keep it simple
• Refactor: N/A; this is an application-launch feature
• Upgrade: Native artifact requirements and older-runtime behavior are documented
• Documentation: SDK/protocol guidance and an execution plan are updated
• Self-review: Reviewed the changed code and platform effect/identity boundaries
• Linux: Real-machine cold-launch acceptance on GNOME Wayland
• Linux: Launch acceptance in isolated KWin, Sway, Hyprland and GNOME Shell

Release note

Support identity-authorized application startup on Windows and Linux. Action required: update matching native runtime packages. Linux launches desktop entries through D-Bus activation or Exec and needs no GIO tools.

🤖 Generated with Claude Code