* refactor: group process and platform modules by ownership * refactor: preserve moved module workflow routing * refactor: preserve native loader and embedded bundle origins
11 KiB
macOS terminal permissions across updates
Read this before changing how the packaged macOS terminal daemon is launched, copied or cleaned up, or before treating a missing executable as a permission denial. Background: issue #13921; the signed native evidence is in PR #25848.
Why a signed copy started by launchd
A daemon forked from the app runs as Orca Helper and macOS charges its privacy access to the app
at its original path. While an update replaces that path, a daemon that first touches a protected
file is denied, and the denial persists after the new bundle arrives even though System Settings
still shows the grant. A missing executable alone does not cause it: a daemon that already read
protected files keeps working after its old executable is deleted.
So a packaged macOS GUI app starts its daemon from a private copy that the updater never touches:
- Each packaged macOS app ships a signed helper,
Contents/Helpers/Orca Agents.app(about 124 MiB): the pinned Node fromsrc/shared/node-runtime/node-runtime-pin.tsas its main executable, the daemon'sout/mainJS and that slice's node-pty.config/scripts/macos/terminal-host-bundle/macos-terminal-host-bundle.cjsbuilds and signs it inafterPack, boots it through one PTY round trip, and fails the build on any layout, Info.plist, OS floor, architecture or signature drift. macos-daemon-bundle.tskeeps one copy per helper build, named by the helper's CDHash, atuserData/daemon-host/macos/terminal-host-<cdhash>/app.noindex/Orca Agents.app. The helper is read from the bundle the running main process executes from, never the whole app. A present copy is reused as is. Otherwise the helper is cloned (APFS clone, regular copy otherwise) into a.staging-<pid>-*sibling, verified once withcodesign --verify --strict -R "=<app designated requirement>", and published with onerename; losing that rename to another publisher is fine. An app without the helper falls back to the fork.macos-daemon-launchd.tsruns the copy's Node on the copy'sdaemon-entry.jsas a non-persistent launchd job, so the daemon has Orca's own identity rather than the UI process's replaceable path. The label is fixed per profile and protocol (com.stablyai.orca.terminal.<profile hash>.v<protocol>). Before bootstrap a stopped job with that label is booted out. A running job gets a bounded wait for shutdown and launchd retirement; a job still running afterward gets the retired-service recovery below for this protocol's label only, and stays fatal unless that recovery releases it; an unreadable job is fatal.--entry-pathstays the installed app's entry, which the replacement preflight compares. The job file is 0600 and deleted right after bootstrap, because the environment may hold credentials. It setsAssociatedBundleIdentifierstocom.stablyai.orca, which is how a launchd job not installed through SMAppService names the app it belongs to for Local Network access. Readiness is the normal authenticated handshake, fenced by the launch nonce.
Node servers, SSH hosts, unpackaged builds, Linux and Windows keep the fork launcher. Adopting an
existing daemon never copies. Telemetry reports a daemon started from a copy as
spawner_path_class=stable-copy.
Only Developer ID builds exercise the helper path in practice. A local ad hoc build's designated requirement is a cdhash, which the helper (a different binary) cannot match, so it falls back to the fork.
Why the helper is com.stablyai.orca
TCC records grants against the designated requirement, which for Orca is the identifier plus team. Signing the helper with the app's own identifier lets it inherit every existing grant, including Full Disk Access, which a user can only add by hand. A distinct identifier would be a new client: new folder prompts naming it, and a new Full Disk Access row for every user.
The helper's bundle, executable and display name are Orca Agents; its identifier, signing team
and designated requirement still match Orca.app. This names the existing terminal-agent process
without changing its privacy client. Native chat providers still run under the GUI process. An
adopted older daemon keeps its original name until it exits; the fork fallback and Windows names
are unchanged.
macOS floor
The helper's Node declares LC_BUILD_VERSION minos 13.5, which is also the helper's
LSMinimumSystemVersion and NODE_RUNTIME_DARWIN_MINIMUM_OS. Packaging fails if a Node pin bump
changes it. Below 13.5 the launcher returns before copying and the fork runs, so those Macs keep the
pre-#25848 behaviour. Orca itself needs macOS 13.4, so only 13.4.x Macs take that path.
First launch
macOS takes about 1 s the first time a binary runs from a new path, so the first daemon of each
build starts that much slower; later daemons reuse the copy and pay nothing. During that first exec
the daemon's /usr/bin/login preflight can time out, and that one shell is spawned directly.
Security
The helper is a signed "run any JS as Orca" binary: it honours NODE_OPTIONS and any script path,
and Electron's fuses do not apply to it. Orca's own binary already allows the same, because its
RunAsNode fuse is enabled, so the helper adds no new exposure.
Fallback states
launchMacDaemonFromStableBundle returns null, and the launcher forks, only when no job from the
attempt can still claim the endpoint. It logs one [daemon] macOS terminal host fallback reason=<…>
line with MacStableLaunchFallbackReason: prepare-failed (helper, copy, signature or job file),
deadline, bootstrap-refused (launchd refused the job and it is absent), exited-before-ready
(the job stopped before answering), or endpoint-taken (another daemon owns the endpoint, which
the fork path then adopts normally). After bootstrap-refused or exited-before-ready the copy is
deleted if unused, so the next launch re-copies it. A timed-out bootstrap, or a job still running or
unreadable, throws: forking beside it could split the endpoint.
The stable attempt must hand off by MAC_STABLE_LAUNCH_HANDOFF_MS after the launch starts, so the
fork's own readiness wait and adapter install still fit the 60 s startup PTY gate. Preparation
shares one abort signal that ends early enough for bootstrap and the job's readiness wait to fit
too. A fallback after the handoff deadline throws instead of forking a daemon that would arrive
after the app has moved to local PTYs.
Cleanup rule
After publishing or reusing the current copy, each launch starts one background collection (one at
a time per process). It deletes every other entry under daemon-host/macos/, older copies and
crashed staging dirs, once lsof +D over it reports no process. lsof +D exits 1 even when it
lists users, so only empty stdout counts as unused; any timeout, stderr, truncated output or other
exit code keeps the copy. Nothing else can run a non-current copy: only this app launches daemons,
and only from the current copy. Staging dirs named with this process's pid are skipped, since they
may still be copying.
LaunchServices and Spotlight
The helper declares no links, documents or types, has a lower CFBundleVersion than the app and
LSUIElement, and was not registered in the signed spike, nested or copied. Copies sit in a
.noindex folder, which Spotlight skips, and Orca never registers them. Starting the daemon through
launchd leaves no record, but another process running the copy's executable directly can make
macOS register it, so retirement runs lsregister -u on the bundle before deleting it.
Retirement recognizes both Orca Agents.app and the legacy Orca Terminal Host.app inside unused
copies, so changing the current bundle name does not leave old LaunchServices registrations behind.
Do not register copies explicitly (lsregister -f or LSRegisterURL).
Executable UUID
Terminal processes' responsible process is the helper, and macOS Local Network privacy maps a
responsible process to an app by its main executable's LC_UUID (TN3179). Stock Node's UUID is
shared by every install of that Node build, so with it Orca's terminals and any other program on
that Node shared Local Network decisions in both directions, and LAN access was blocked while System
Settings showed Orca allowed (#21988).
Local Network also caches one UUID per bundle id, and the helper shares com.stablyai.orca with
the app. A helper UUID of its own keeps replacing the app's cached UUID and back: in testing it
flip-flopped, blocked some terminal and app connections, and prompted again after an update. So
packaging gives the helper exactly the main executable's UUID per CPU type (#41676: derived from
the app id, the app's executable name and the CPU type), stable across releases.
verifyMacTerminalHost and the release check fail if it drifts. The designated requirement is
unchanged, so file-access grants are unaffected.
Rollback
To turn this off, make launchMacDaemonFromStableBundle (macos-daemon-launchd.ts) return null
right after its platform checks: every launch then takes the fork path. Copy-launched daemons that
are still running are adopted as usual. Copies are only deleted by the collection, so keep it running
there (retireOtherMacDaemonCopies(root, '')) until no copy-launched daemon can remain; each copy
keeps about 124 MiB.
Existing sessions and status
RPC and signal shutdown share a five-second process-exit deadline, armed before terminal teardown. A stalled teardown must not leave the endpoint retired while the launchd job stays alive forever.
An explicit, untargeted Restart also recovers signed-helper jobs left by older builds after they retired their PID record and endpoint but failed to exit. Recovery uses exact launchd labels and arguments for this profile, ignores newer protocols, and preserves live or unreadable endpoints and services still publishing a PID record. It verifies descendant exits before killing the old root and releasing its label. A failed recovery is logged without blocking the current daemon's restart. A launch runs the same recovery only for the current protocol's label, and only once that label still blocks bootstrap after the retirement wait (#29361); otherwise the label refused every new terminal until a manual Restart. Node/SSH hosts do not perform GUI-service recovery.
Running old daemons keep their terminals; settings reports app and terminal-host Full Disk Access
separately, and a denied terminal is recovered by closing it or restarting the daemon. The packaging
hook also gives the main bundle and every Helper the Desktop, Documents and Downloads descriptions,
because the fork fallback still hosts terminals in Orca Helper.