Process management
How the desktop gateway spawns, monitors, and cleans up subprocesses like the AI coding sessions.
The ProcessManager in src/server/process-manager.ts governs how subprocesses are spawned, monitored, and cleaned up.
Spawn modes
Two modes in ProcessManager:
spawnDetached
Detached with stdio redirected to a log file (opens logFile append, unreferenced). Used for long-running background jobs.
exec
Wraps execFileAsync for one-shot calls.
Both modes call assertOperationPath(cwd) before spawning, enforcing the sandbox allowlist via security.ts.
Binary resolution
Electron on macOS inherits a minimal PATH. The server resolves user tools by spawning the login shell ($SHELL -ilc) wrapped in sentinels (__CLPATH_START__, __CLPATH_END__) to extract the real PATH. ~/ is expanded; npm_config_prefix and NPM_CONFIG_PREFIX are sanitized for nvm compatibility. Result is cached for the session.
resolveBinary / resolveBinarySync support overrides via Settings → Binary paths with result sources override | override_invalid | path | fallback.
Supported overrides: claude, codex, python3, git.
Cancel
Cloud cancel commands arrive as desktop.cancel over the relay. Local cancel is available from the UI.
Why structured process management matters
AI coding sessions are long-running, streaming, and sometimes die unpredictably. Generic subprocess plumbing leaks zombies, orphans telemetry, and drops partial output. The ProcessManager turns all three into bounded, observable, resumable behavior.