docs(linux): use absolute service CLI launcher

config/scripts/headless-serve-shutdown-workflow.test.mjs

@@ -181,7 +181,10 @@ describe('headless serve shutdown PR gate', () => {
     expect(headlessLinuxProse).toContain(
       'A separately paired runtime is outside that boundary; local execution and SSH hosts reached through this runtime are not. An affected or unknown omission, missing scope, failed request or lost connection is `unverifiable`'
     )
-    expect(headlessLinuxGuide).toContain('sudo -Hu orca orca-ide terminal list --json')
+    expect(headlessLinuxGuide).toContain(
+      'sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json'
+    )
+    expect(headlessLinuxGuide).not.toContain('sudo -Hu orca orca-ide terminal list --json')
     expect(headlessLinuxGuide).not.toContain('Two facts make this safe and predictable')
   })
 
@@ -189,12 +192,13 @@ describe('headless serve shutdown PR gate', () => {
     const commandRule =
       'The registered Linux CLI command is `orca-ide`, not `orca`, to avoid shadowing the GNOME Orca screen reader.'
     const substitutionRule =
-      "Bare `orca` is available only through Orca's terminal-scoped shim; from an ordinary shell, substitute `orca-ide` for `orca` in commands below."
-    const censusCommand = '`sudo -Hu orca orca-ide terminal list --json`'
+      "From an ordinary shell outside that service user's managed environment, substitute `orca-ide` for `orca` in commands below."
+    const censusCommand = '`sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json`'
 
     expect(headlessLinuxProse).toContain(commandRule)
     expect(headlessLinuxProse).toContain(substitutionRule)
     expect(headlessLinuxProse).toContain(censusCommand)
+    expect(headlessLinuxGuide).toContain('best-effort dispatcher at `$HOME/.local/bin/orca`')
     expect(headlessLinuxProse.indexOf(substitutionRule)).toBeLessThan(
       headlessLinuxProse.indexOf(censusCommand)
     )

config/scripts/orcad-operations-restart-safety.test.mjs

@@ -26,6 +26,10 @@ describe('orcad operations restart safety', () => {
     expect(operationsProse).toContain(
       "Every `omittedHostIds` entry must be explicitly accounted for outside the target service's execution boundary"
     )
+    expect(operationsProse).toContain(
+      '`sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json`'
+    )
+    expect(operationsGuide).not.toContain('sudo -Hu orca orca-ide terminal list --json')
     expect(operationsProse).toContain(
       'A separately paired runtime is outside that boundary; local execution and SSH hosts reached through this runtime are not. An affected or unknown omission, missing scope, truncation, a failed request or lost contact makes the result `unverifiable`'
     )

docs/reference/headless-linux-server.md

@@ -333,9 +333,12 @@ sudo systemctl enable --now orca-xvfb.service orca-serve.service
 ## CLI Install Note
 
 The registered Linux CLI command is `orca-ide`, not `orca`, to avoid shadowing
-the GNOME Orca screen reader. Bare `orca` is available only through Orca's
-terminal-scoped shim; from an ordinary shell, substitute `orca-ide` for `orca`
-in commands below.
+the GNOME Orca screen reader. Desktop-managed terminals receive a
+terminal-scoped bare-`orca` shim. A packaged headless `orca serve` also makes a
+best-effort dispatcher at `$HOME/.local/bin/orca` for the service user's own
+shell, so the Claude Teams launcher can resolve its bare command; it does not
+replace another user's `orca`. From an ordinary shell outside that service
+user's managed environment, substitute `orca-ide` for `orca` in commands below.
 
 On a headless host, you do not need to open the desktop UI just to run the
 server. Invoke the AppImage directly:
@@ -406,7 +409,12 @@ every terminal and agent in its cgroup; an agent conversation may be resumable,
 but its current process and any in-flight command are gone.
 
 Immediately before stopping the service, obtain a fresh census as the service's
-OS account and home: `sudo -Hu orca orca-ide terminal list --json`. Proceed only when it is
+OS account and home. Use the installer's absolute launcher path so `sudo`'s
+`secure_path` cannot hide a per-user registration:
+`sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json`.
+Replace both `orca` and `/home/orca` with the service account and home used by
+your unit; for an extracted deployment, use its absolute `resources/bin/orca-ide`
+launcher instead. Proceed only when the result is
 untruncated, has an explicit `hostScope`, covers every execution host affected
 by this service stop, and lists no terminals on those hosts. Every
 `omittedHostIds` entry must be explicitly accounted for outside this service's

docs/reference/orcad-operations.md

@@ -85,8 +85,11 @@ pinned while it owns sessions. A combined-unit systemd stop or restart is differ
 the daemon and every live terminal after the graceful window.
 
 Before a cgroup-wide stop, obtain a fresh `orca-ide terminal list --json` result using the same OS
-account and home as the daemon (for example, `sudo -Hu orca orca-ide terminal list --json`). A safe
-empty census is untruncated, has an explicit `hostScope`, covers every
+account and home as the daemon. Invoke the installer's absolute launcher path so `sudo`'s
+`secure_path` cannot hide a per-user registration (for example,
+`sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json`). Replace both `orca` and
+`/home/orca` with the service account and home used by the unit; an extracted deployment may use
+its absolute `resources/bin/orca-ide` launcher instead. A safe empty census is untruncated, has an explicit `hostScope`, covers every
 execution host affected by the stop, and lists no terminals on those hosts. Every
 `omittedHostIds` entry must be explicitly accounted for outside the target service's execution
 boundary. A separately paired runtime is outside that boundary; local execution and SSH hosts