orca/docs/reference/windows-daemon-host-relocation.md

Windows daemon-host relocation

On Windows the terminal daemon does not run from the install directory. Before it forks the daemon, Orca materializes a trimmed copy of its own runtime under %LOCALAPPDATA%\Orca\daemon-host\<app version>\ and forks the daemon from there (src/main/daemon/daemon-host-relocation.ts). This is what keeps live terminals alive across an auto-update and across a crash of the main process.

Read this before changing the copy plan, the host exe name, the LOCALAPPDATA layout, or config/nsis/orca-installer-hooks.nsh.

What the relocation actually escapes

The killer is electron-builder's process sweep — not file deletion. Windows will not delete a running image, so RMDir /r "$INSTDIR" cannot end the daemon on its own.

In app-builder-lib's allowOnlyOneInstallerInstance.nsh, FIND_PROCESS / KILL_PROCESS have two branches:

Branch	Condition	Selector
Primary	powershell.exe runs, Get-CimInstance resolves, and Get-ExecutionPolicy -Scope Process is not Restricted	Win32_Process where $_.Path.StartsWith('$INSTDIR', 'CurrentCultureIgnoreCase') — path-scoped
Fallback	otherwise	per-user: taskkill /F /IM "<AppName>.exe" /FI "PID ne $pid" /FI "USERNAME eq %USERNAME%"; per-machine: the same without the username filter — image-name-scoped

The upstream policy check can select the image-name fallback even when the inline process query works. Restricted disallows script files, not inline commands. A packaged trace for #22872 showed that fallback successfully killing the relocated Orca.exe during an update; the genuine-uninstall cleanup guard was not responsible.

Orca's customCheckAppRunning in config/nsis/orca-process-check.nsh tests the actual inline Get-CimInstance Win32_Process query with terminating errors. Success selects the path-scoped branch; any other result retains the upstream fallback. The hook reuses upstream process selection, retry, permission and installation-mode handling. It neither overrides execution policy nor assumes PowerShell is available.

A daemon outside $INSTDIR survives the path-scoped sweep. A genuinely unavailable process query still permits an image-name sweep and cold restore. Updates also run the old installed uninstaller, whose old capability check cannot be repaired by the new installer: the first upgrade can still cold-restore on an affected host. Once both binaries contain the hook, later updates use the actual capability test on both sides.

Why the exe is copied verbatim (and not renamed)

The host exe keeps the app exe's own file name (daemonHostExeName() returns basename(process.execPath)), so the relocated image is a byte-for-byte copy of the app binary under its original name.

An earlier revision copied it as orca-terminal-daemon.exe specifically so the fallback taskkill /IM Orca.exe could not match. That bought survival on the rare no-PowerShell host and cost a textbook defence-evasion signature: a process copies its own image into a user-writable directory under a different name so a kill-by-image-name cannot match it, then runs detached and survives the installer. Microsoft Defender for Endpoint flagged it as MITRE T1036 (Masquerading), and — because it is the process every other flagged action is attributed to — it acted as a reputation multiplier on unrelated findings. No VS Code fork does this.

Trading the fallback branch for the name is the right trade:

• On the primary branch nothing changes: the daemon still survives the update.
• On the fallback branch the daemon is killed with the app and terminals cold-restore on relaunch. That is the documented pre-relocation behaviour, a first-class outcome the update harness already asserts (--expect cold-restore), not a failure.
• Relocation is fail-open end to end anyway: any materialization failure returns null and the caller forks the install-dir host.

One new failure mode comes with it, on the fallback branch only. The daemon now matches FIND_PROCESS under the app's image name, so it enters electron-builder's retry loop (allowOnlyOneInstallerInstance.nsh:136-141). If the taskkill there fails to end it — an elevated or otherwise unkillable host — the loop reaches MessageBox ... /SD IDCANCEL and Quits, aborting a silent update rather than completing it. Under the old distinct name the daemon was invisible to that loop. Low probability (fallback branch and an unkillable daemon), but it is a real new path.

What this does not buy. Two things bound the win honestly:

• The strongest T1036 indicator is a PE-resource-vs-disk-name mismatch, and it was never firing: the shipped binary's OriginalFilename is empty (only InternalName = Orca is set), so there was no embedded name for the old disk name to contradict.
• The remaining behaviour — a signed app copying its own ~225 MB image into user-writable %LOCALAPPDATA% and running it detached under ELECTRON_RUN_AS_NODE=1 — is still execution from a non-standard user-writable location, which maps to T1036.005 and is a standard heuristic on its own.

So this removes a real but partial signal. Expect the score to drop; do not expect the process to stop being scored.

Options that were rejected

Option	Why not
Materialize the tree from the NSIS installer	The daemon host is ~246 MB. Writing it at install time doubles install footprint and lengthens the window in which the app is down during a silent update. Worse, on a per-machine install (INSTALL_MODE_PER_ALL_USERS) the installer runs as the installing admin, so $LOCALAPPDATA is the wrong user's — every other user still needs the runtime path, which means the runtime self-copy stays in the product and the signal is only made rarer.
Ship a second signed orca-terminal-daemon.exe in the installer	Orca.exe is 235,555,328 bytes (224.6 MiB). electron-builder's NSIS uses solid LZMA with a 64 MB dictionary, so a second copy 224 MB downstream does not dedupe; the compressed installer grows by roughly a whole compressed Electron binary, paid by every user on every update download. It also does not remove the runtime copy — the helper still has to reach %LOCALAPPDATA% to escape the sweep — so it buys the same signal reduction as the verbatim copy at a large download cost.
Override customCheckAppRunning to force a path-scoped kill on both branches	Cheap to write (~6 lines: !include "getProcessInfo.nsh", Var pid, and a macro that pins IsPowerShellAvailable, reusing upstream's dialog, retry loop and elevated handling) — but wrong at any size. Forcing the PowerShell branch on a host where PowerShell is genuinely absent makes FIND_PROCESS and KILL_PROCESS silently no-op, so the installer proceeds with the real app still running and its files in use. That is a worse outcome than the cold restore it would prevent, so this is not worth doing ever, not merely not now.
Hardlink instead of copy	Avoids the 246 MB entirely and is not a "copy" at all, but is NTFS-and-same-volume-only and introduces fresh failure modes (link counts, AV interception, cross-volume installs). Worth revisiting deliberately, not as part of a signal fix.

Invariants to preserve

• The host exe name is derived from process.execPath, never a literal. A future executableName or dev-channel rename must follow automatically; pinning a name of our own is how the mismatch creeps back.
• The daemon is identified by PID and command line, never by image name — in the product (daemon-pid-file-parse, daemon-process-inspection) and in the harness (tests/tools/win-update-e2e/daemon-processes.mjs). Nothing may start matching on the exe name.
• config/nsis/orca-installer-hooks.nsh kills the daemon by image name. That now also matches the app's own exe, which is correct on a genuine uninstall — the product is being removed — but its ${isUpdated} guard must stay: electron-builder runs the uninstaller during every update's uninstallOldVersion, and killing the daemon there defeats the whole feature. The legacy orca-terminal-daemon.exe name stays in the macro to reap hosts left by older builds.
• LOCAL_HOST_ROOT_NAME in daemon-host-relocation.ts and the path in the uninstall macro are the same directory. Change both together.
• Every native module the daemon bundle require()s must be in the copy plan (daemon-host-manifest.ts). A missing one does not fail the fork: bare require walks up from the relocated bundle, finds nothing, and the caller's fallback runs forever. That is how @vscode/windows-process-tree went missing and every process-table read became a powershell.exe CIM scan (#16905). A host missing the addon's runtime files counts as unmaterialized, so hosts built before it was copied get rebuilt.

Verifying a change

Unit coverage lives in src/main/daemon/daemon-host-relocation.test.ts (copy plan, native-addon mirror, verbatim naming, marker/atomic publish, fail-open, prune veto). Nothing in unit tests can prove survival, so any change to this file or to the NSIS macro needs the packaged harnesses:

• .github/workflows/win-update-survival-e2e.yml — builds an installer from the branch and updates it over itself with --expect survival. Verify normal and child-scoped Restricted policy; also verify released-to-branch migration with the expected cold-restore limitation.
• .github/workflows/win-crash-survival-e2e.yml — proves the daemon survives a main-process crash.
• .github/workflows/windows-terminal-restart-e2e.yml — terminal restart behaviour.
• .github/workflows/win-update-e2e.yml — release-tag-to-release-tag update, both survival and cold-restore profiles.

All four are workflow_dispatch-only (the two update workflows also carry a push trigger pinned to one historical feature branch), so they must be dispatched by hand against this branch before merging a change here — which requires the workflow files to already exist on main.