orca/docs/agent-status-over-wsl.md

Agent Status over WSL (STA-1515)

Status: implemented and rig-validated (2026-07-09 round 3 + 2026-07-10 round-4 re-run pinned to the hardened build, Windows 11 + WSL2 NAT): Claude end-to-end live — provisioning, working→done in the store, completion toast, loopback-only posture, and restart resume over a daemon-surviving PTY with the instance-keyed endpoint dir reused across restarts. The round-4 re-run also proved the --exec spawn form live (host process table) and the stale-exit reinstall upgrading the guest to the new bundle version in place. Residual: Codex's done/Stop leg unproven live — env-blocked on the rig (no dev-profile Codex credentials AND the model backend is unreachable from the guest under NAT); everything that fired behaved correctly. Confirm on a credentialed rig with a guest-reachable backend, ideally on a fresh distro to also observe the deferred Codex trust entries landing after config.toml is seeded. Owner: brennanb2025. Linear: STA-1515. Precedent this mirrors: the SSH agent-hook relay (src/relay/agent-hook-server.ts, src/shared/agent-hook-relay.ts, ingest at agentHookServer.ingestRemote in src/main/agent-hooks/server.ts).

Background — how we got here

GitHub issue 7565 reported OMP agents in WSL worktrees disappearing from the worktree sidebar after v1.4.124. Diagnosis split it into a regression and a pre-existing class gap:

• The regression was a title-normalization change (PR 7447) that stopped idle OMP titles from producing the sidebar's title-derived fallback row. Decision: the sidebar is moving to hook-driven rows only (fallback removal in flight, separate PR), so the fallback was not restored.
• The class gap is that agent hooks have never worked from inside WSL for any agent. Two scoped PRs fixed it for OMP alone (merged, live-validated on a Windows+WSL2-NAT rig):
  • PR 7642 — Orca-managed WSL shells wrap interactive omp invocations with --extension "$ORCA_OMP_STATUS_EXTENSION" (the env var is WSLENV /p-translated so the WSL process reads the extension out of the Windows filesystem via /mnt/c).
  • PR 7641 — when the extension's loopback POST cannot connect, it delivers via Windows-side /mnt/c/Windows/System32/curl.exe (a Windows process, so its 127.0.0.1 is the loopback Orca actually binds). Fire-and-forget spawn, --noproxy 127.0.0.1, memoized WSL/curl probes, load-tolerant timeouts (--connect-timeout 3 --max-time 10; 0.5s dropped events under load).

This document is the full context for the general fix: every other hook client is still dead from WSL, and the hooks-only sidebar change makes this work the gate for the Windows+WSL story.

Why hooks don't work on Windows+WSL — two independent gaps

Gap A — transport

The hook listener binds 127.0.0.1 only, deliberately (src/main/agent-hooks/server.ts, listen(0, '127.0.0.1'); auth via X-Orca-Agent-Hook-Token, 403 otherwise). Every hook client POSTs to a hardcoded http://127.0.0.1:$ORCA_AGENT_HOOK_PORT/hook/<source>.

WSL2 under default NAT networking is a VM with its own network namespace. Microsoft's localhost forwarding is one-way (Windows→WSL only): 127.0.0.1 inside WSL is WSL's own loopback, so every POST dies ECONNREFUSED — silently, because hook clients are deliberately fail-open. Reaching Windows from WSL would require the host vNIC IP (changes per boot) + a non-loopback listener bind + a firewall rule — all three conflict with the loopback-only security posture.

The env coordinates DO cross correctly (src/main/pty/wsl-orca-env.ts addOrcaWslInteropEnv: WSLENV PORT/u TOKEN/u ENV/u VERSION/u plus ORCA_AGENT_HOOK_ENDPOINT/p path-translated; called from src/main/ipc/pty.ts and src/main/daemon/pty-subprocess.ts). The address is simply unreachable.

Opt-in mirrored networking (Win11, .wslconfig) shares loopback and makes plain fetch work — the fix must not fight it. No wslinfo probing is needed: under mirrored mode the relay's preferred-port bind collides with the Windows listener and the EADDRINUSE fallback (below) handles it, while clients that go straight to the shared loopback reach the Windows listener directly. Both delivery paths stay valid.

Gap B — installation

Hook configs and scripts are written to the Windows home by every hook service: Claude settings.json + managed scripts, Codex config, Gemini/Cursor/Droid/Devin/Grok/ Copilot scripts, Amp/OpenCode plugin files, the Pi/OMP extension file. An agent inside WSL reads the WSL-side $HOME and sees none of it. There is zero WSL-targeted install code in src/main/agent-hooks/ or any hook service. SSH remotes have the exact precedent needed: dedicated remote installers (src/main/ssh/ssh-relay-session.ts remote settings.json handling; PR 7744 installed Droid/Copilot hooks over SSH).

Consequence: even mirrored-networking users get no hooks — transport fine, configs absent. OMP escapes Gap B by pointing across the boundary (/mnt/c path via /p translation) rather than installing WSL-side; that trick can carry file content for some clients, but shell hooks still execute inside WSL and then hit Gap A regardless.

Transport map — every client, how it posts

Endpoint file contract: writeEndpointFile (src/shared/agent-hook-listener.ts) emits exactly four keys (ORCA_AGENT_HOOK_PORT/TOKEN/ENV/VERSION) to endpoint.env (POSIX) / endpoint.cmd (Windows) — no host field. Shell clients source it to refresh stale coords after an Orca restart; node clients parse it. It is never executed as a delivery script. Clients prefer endpoint-FILE coords over env (restart re-coordination) — any transport change must preserve that property.

Client	Mechanism	Runtime that POSTs
Claude, Codex, Gemini, Cursor, Droid, Devin, Grok	managed shell script	curl (POSIX) / curl.exe (Windows), built in src/main/agent-hooks/installer-utils.ts
Copilot	managed script	curl (POSIX) / PowerShell Invoke-WebRequest (Windows)
command-code	managed script (parse-not-source hardened)	curl
Amp, OpenCode	in-process node plugin	fetch
Pi / OMP	bundled in-process extension (src/main/pi/agent-status-extension-source.ts)	fetch, now with the WSL curl.exe fallback

All of them target 127.0.0.1.

Status quo + why this gates the hooks-only sidebar

Today the worktree-card rows still have a title-derived fallback producer (src/renderer/src/components/sidebar/worktree-title-derived-agent-rows.ts), so WSL users DO currently see rows for title-rich agents (Claude ✳/spinner titles, Gemini glyphs) — degraded (generic text, no prompt/last-message preview, no notifications) but present. Title-poor agents are dark (Codex — hence GH 6907). When the hooks-only change removes that producer, every non-OMP agent in a WSL worktree loses its card row entirely until this work ships. Hook fidelity adds: prompt + last-assistant-message previews, waiting/blocked precision, completion notifications, AI Vault / native chat session integration.

Solution design — WSL relay + WSL-side installation

Transport (Gap A): guest-resident relay, host-owned stdio

Run a small receiver inside WSL on WSL's own loopback, listening on the very port the clients were already given ($ORCA_AGENT_HOOK_PORT — free inside WSL, since that port only exists on the Windows side). Unmodified clients then deliver successfully with zero client changes; the reporter's diagnostic relay in GH 7565 proved this shape live. Forward each parsed envelope to the Windows host over the relay's own stdio (Orca spawns it via wsl.exe, so it owns that pipe). Ingest through the existing trust boundary: agentHookServer.ingestRemote (src/main/agent-hooks/server.ts), envelope shape src/shared/agent-hook-relay.ts — identical to the SSH relay, which runs a loopback-only receiver on the remote box and forwards over the SSH control channel.

Port binding. Bind the inherited $ORCA_AGENT_HOOK_PORT first — it keeps every already-crossed coordinate (env and the /p-translated endpoint file) truthful with zero divergence. On EADDRINUSE inside the guest, fall back to the SSH relay's own pattern: bind 127.0.0.1:0, write a WSL-side endpoint file, and point WSL PTYs' ORCA_AGENT_HOOK_ENDPOINT at it (clients already prefer endpoint-file coords over env). The relay writes that WSL-side endpoint file in both modes so restart re-coordination never depends on /mnt/c translation being readable.

Lifecycle: one relay per distro per Orca instance (concurrent instances have distinct ports, so guest listeners never collide); ensure — not just start — whenever a WSL PTY exists: first spawn and daemon-PTY reattach after an Orca restart (WSL PTYs survive in the daemon; the new instance has a new port + token and must respawn the relay before surviving agents re-coordinate). The relay exits when its stdin closes: a lingering guest listener would let WSL's own Windows→WSL forwarder grab the freed Windows-side port and blackhole stale Windows-side hook posts. Restart if WSL restarts; token still validated at the relay's HTTP receiver; harmless under mirrored networking (bind fallback) and inert on non-WSL platforms (ensure only fires from WSL PTY spawns).

Reliability contract (invariant class agent-session.hook-transport): hook clients are fail-open silent, so the relay must not be — spawn failures, EADDRINUSE fallback, and forward errors each leave a diagnosable breadcrumb; the wsl.exe "Catastrophic failure (E_UNEXPECTED)" retry is bounded with backoff, never a spawn loop. Oracle: provider- contract tests with fault injection (stdin close → exit, occupied port → fallback + file rewrite, envelope round-trip to ingestRemote) rather than end-to-end flows only.

Design notes from a survey of comparable WSL-capable tools (kept nameless per policy):

• Guest-resident component + host-owned channel + guest-side installation, explicitly reusing the tool's SSH-remote machinery, is the established pattern. No surveyed tool makes guest processes dial back to a Windows-localhost listener — the merged OMP curl.exe stopgap is the outlier as a primary path (but see the round-4 revised stance below: it survives as the no-node fallback).
• Prefer host-owned stdio over Windows→WSL localhost port forwarding (wslhost forwarding is known-flaky under load; one surveyed tool dials the distro vNIC IP just to avoid it — stdio sidesteps the question entirely).
• WSL offers no persistent control channel between separate wsl.exe invocations — collapse the relay's ensure-installed + launch into one idempotent script per spawn.
• Install into the guest from inside the guest (download/extract in WSL) or stream the binary through wsl.exe stdin — not by copying through /mnt/c.

Installation (Gap B): WSL-side hook installers

Write agent hook configs/scripts into the WSL-side home, per agent, analogous to the SSH remote installers — via wsl.exe-executed scripts (preferred, mirrors SSH most closely) or \\wsl.localhost\<distro>\... writes. Without this half, the relay receives nothing: the hook clients themselves are absent from the WSL filesystem.

Alternatives considered (and why not)

1. Endpoint-file host/URL field — the file already crosses into WSL (/p-translated), but clients read only PORT/TOKEN and hardcode the host, so all ~13 still need edits; and a WSL-reachable listener bind breaks the loopback-only posture (LAN exposure, firewall prompts).
2. Replicate the curl.exe bridge per client — the shell clients share ~2 generated builders so it is cheaper than it sounds, but it is N point fixes, requires WSL interop enabled (/etc/wsl.conf can disable it), pays a per-event process spawn (load-sensitive, see validation facts), and keeps the ecosystem-outlier direction.
3. Listener-side bind changes / rely on mirrored networking — posture conflict / opt-in only.
4. OSC 9999 in-band status (src/shared/agent-status-osc.ts, parsed per-pane in pty-transport.ts and orca-runtime.ts) — zero-network and pane-attributed, but only viable for in-process clients and carries status payloads, not the full hook event vocabulary (prompts, tools, completion) — cannot replace the pipeline.

Facts + gotchas from the 2026-07-08 Windows-rig validation

• curl.exe interop delivery works under NAT (shipped for OMP), but per-event process spawn is load-sensitive: --connect-timeout 0.5 dropped 3/3 events to a healthy listener under load; fine at 3s. A resident relay avoids per-event spawns entirely.
• wslinfo --networking-mode distinguishes NAT vs mirrored.
• Clients prefer endpoint-FILE coords over env. Testing gotcha: unset ORCA_AGENT_HOOK_ENDPOINT in synthetic tests or events go to the real running app.
• Server ingest silently drops paneKeys that are not uuid:uuid-shaped — use real-shaped keys in synthetic validation.
• OMP is a Bun single-file binary; Bun's node:child_process/fetch compat held. Other in-process clients run inside their agents' runtimes — verify per runtime.
• Environmental: fresh WSL 2.7.10 intermittently threw "Catastrophic failure (E_UNEXPECTED)" from wsl.exe -d <distro> -- bash -lc under concurrent spawn load (cleared by wsl --terminate). The relay spawn path should tolerate/retry this.
• Fork-PR CI runs sit in action_required until approved: gh api repos/stablyai/orca/actions/runs/<id>/approve -X POST.

Acceptance

On a default-config Windows 11 + WSL2 NAT machine: launch Codex or Claude (explicitly not OMP) in a WSL worktree → live hook-driven worktree-card row with status transitions and a completion notification; hook listener still bound to Windows loopback only; zero per-client transport changes; hooks installed WSL-side automatically (no manual config); harmless under mirrored networking and inert on non-WSL platforms. After an Orca restart with the WSL agent still running (daemon-surviving PTY), status events resume without relaunching the agent.

2026-07-09 Windows-rig validation follow-ups

The first live GUI run proved every mechanism in isolation but failed end-to-end, yielding two fixes:

1. Link death must be handled, not just child death. A mux protocol error or timeout can kill the host↔guest link while the guest process (and its 204-returning receiver) stays alive — the exact observed signature: hooks POST 204, store never populates. wsl-hook-relay-link.ts now guarantees exactly-once death handling from either signal; the manager breadcrumbs it, kills the child, and self-restarts after a short cooldown (a live agent session produces no new PTY spawns to re-trigger ensure). ORCA_WSL_HOOK_RELAY_DEBUG=1 traces every received envelope pre-ingest so a live rig can pinpoint any residual drop. The full host chain is pinned by a live integration test (real bundle over real child stdio through the real manager into a real ingestRemote).
2. (Round 2) The renderer's SSH-era ownership gate dropped wsl:* events. With the link fixed, envelopes reached ingestRemote and the durable cache, but useIpcEvents.applyAgentStatus compares the stamped connectionId against the owning repo's — "wsl:<distro>" !== null for a local repo, so every WSL-relayed status died before setAgentStatus/notifications. Fix: wsl:* ids are transport provenance, not ownership — the gate normalizes them to local (null) via isWslHookRelayConnectionId, while still rejecting WSL-stamped events against SSH-owned repos. Provenance stays stamped (it made the drop diagnosable in the first place).
3. Codex reads a redirected home. Orca launches WSL Codex with CODEX_HOME pointed at the managed runtime home (~/.local/share/orca/codex-runtime-home/home), so installing hooks to ~/.codex left Codex dark. The installers now accept an explicit codex home; the trust write into config.toml is deferred while that file doesn't exist (the launch path seeds it only-if-absent — creating it first would cancel the seed), and the manager re-runs the idempotent installers on later ensures (throttled) to upsert trust once the seed lands. Consequence: the very first WSL Codex session after a cold relay may miss hooks; the next one has them.

2026-07-09 adversarial-review hardening (pre-rig round 3)

Four independent review lenses over the full diff; confirmed findings fixed:

• Endpoint identity (all 4 reviewers): the guest endpoint dir was keyed by the ephemeral Windows hook port, so a daemon-surviving agent kept sourcing the DEAD port-P1 file after an Orca restart — breaking the restart-resume acceptance criterion and regressing shipped OMP recovery. Now keyed by a restart-stable instance key (hash of the Windows endpoint file path = userData + namespace, crossed via ORCA_WSL_HOOK_INSTANCE): the restarted instance's relay REWRITES the same file, which is exactly what re-coordinates survivors.
• Restart policy: every failure now arms the restart timer (one failed relaunch no longer ends self-recovery), and the timer probes wsl --list --running first — wsl -d BOOTS a stopped distro, so recovery must never resurrect a VM the user shut down; a stopped distro's state is dropped instead (next WSL terminal re-ensures). Failure counters only reset after 2 min of stable uptime, so connect-then-die loops escalate to the 10-min cap instead of cycling every 10s.
• Install-dir versioning: the guest install dir is namespaced by bundle version, so concurrent Orca instances with different bundles (dev + prod) never reinstall over each other; tmp files carry the guest PID. The install spawn also gained the 30s timeout it was missing (a wedged wsl.exe could previously pin the state machine at 'starting' forever).
• Guest node resolution: candidates (PATH, nvm glob, fixed paths) are each version-probed, first pass wins — an apt node 12 on PATH no longer masks an nvm node 20 into a false "no node >= 18" 10-minute cooldown.
• wsl.exe text handling: WSL_UTF8=1 on all spawns + NUL-stripping on stderr, so the "Catastrophic failure" transient-retry matcher and breadcrumbs survive UTF-16LE output.
• Smaller: ordered post-sentinel chunk handoff (frame-decoder desync race), port-fallback breadcrumb now reaches host logs via the home handshake, bad home reply fails the connect (was: silently 'running' without installs), missing-bundle warn-once, distro map keys case-normalized, disposeAll wired to app will-quit, single-spawn Codex trust catch-up via a one-shot 60s reinstall timer.

Accepted gaps (reviewed, deliberately not addressed here): old version-namespaced install dirs accrete across upgrades (~200KB each); an outdated running daemon /p-translates the guest endpoint path until it restarts (hook scripts fall back to env coords, which same-port binding keeps correct); wslDistroCache caches a transient empty list for the app run (pre-existing semantics, now load-bearing for default-distro resolution); default-distro resolution caches the first answer for the app run.

2026-07-09 round-4 external adversarial review

A second adversarial sweep (five independent lenses: guest relay + fs bridge, host lifecycle state machine, app integration + renderer gate, design-vs-alternatives, and a platform fact-check of every WSL claim). Design verdict: the guest-resident relay over host-owned stdio is the right architecture — the zero-per-client-change chokepoint is what the curl.exe alternative cannot match, and the lifecycle weight is inherent to any guest-resident helper. Confirmed findings, all fixed on this branch:

• dropState identity race (major): the recovery timer re-checked state identity only BEFORE the async wsl --list --running probe; an ensure() landing during the probe could get its fresh state deleted by key — orphaning a live relay child outside the map (unkillable by disposeAll, duplicate relay on next ensure). Fixed: identity re-check after the probe await + identity-guarded delete in the manager.
• Distro-running probe failed OPEN: any probe error (including its 10s timeout) reported "running", so recovery could wsl -d — and thereby BOOT — a distro the user shut down, in exactly the wedged-wsl.exe failure mode where the probe errors. Now fails closed: drop the state; the next WSL PTY spawn re-ensures.
• Spawn form hardened to --exec: wsl.exe -- <cmd> routes through the distro's default login shell (Microsoft docs: only --exec runs "without using the default Linux shell"), so a fish/nushell chsh could mangle the launch; --exec sh -c/-s bypasses it and passes argv verbatim (no $-preprocessing, escaping shim dropped) — same form as the Codex WSL login spawn.
• Post-sentinel handoff microtask: pending chunks flushed synchronously inside the mux constructor, before the manager could register notification handlers — an envelope arriving in the trailing bytes dispatched to zero handlers (recovered only by the later replay request). Flush now rides a microtask: after the caller's synchronous wiring, still ahead of any subsequent stdout IO event.
• Relay process posture: the guest relay now mirrors the SSH relay's uncaughtException (log + exit → manager respawns) / unhandledRejection (log + survive) handlers.
• Replay cache recency cap: the WSL relay has no per-pane teardown signal, so the per-pane replay cache grew for the relay's lifetime; now capped at 256 panes, evicting longest-idle first (meta map kept in lockstep). Backstop for SSH too.
• Smaller: guest launch script derives the stale-exit code from the shared contract constant (was a hardcoded 42 twin); one-shot reinstall timer refuses to arm after dispose; fs-bridge scope comment states the lexical (symlink-following) bound honestly. New oracles: sentinel unit suite (chunk splits, overflow kill, timeout, microtask handoff), fs-bridge scoping suite, 403 + fallback endpoint-file rewrite, cache-cap eviction, and the recovery/manager race regressions.

Revised stance on the OMP curl.exe bridge — keep it, do not retire. The relay requires node ≥ 18 in the distro; a fresh WSL Ubuntu ships none, Codex CLI is a native binary that brings none, and Claude Code's native installer no longer implies a system node. A distro running only Codex would hit the no-node cooldown and stay dark — the exact GH 6907 shape. The interop bridge is the one delivery path with no guest runtime requirement, so it stays as the documented no-node fallback (currently wired for OMP; extending it to the shared shell-script builders is the tracked follow-up if no-node distros show up in telemetry). The relay remains the primary path: resident (no per-event spawn cost) and interop-independent.

Implementation map

• Guest: src/relay/wsl-agent-hook-relay.ts (entry; exits on stdin close), src/relay/wsl-hook-fs-bridge.ts (home-scoped fs RPCs for installs), src/relay/agent-hook-server.ts (token/preferredPort options + EADDRINUSE fallback). Bundled by config/scripts/build-relay.mjs → out/relay/wsl/.
• Host: src/main/agent-hooks/wsl-hook-relay-manager.ts (per-distro state machine), wsl-hook-relay-launch.ts (bundle resolve, guest launch/install scripts, spawn env, sentinel wait), wsl-hook-relay-link.ts (envelope forward + exactly-once link-death handling), wsl-hook-relay-deps.ts (DI seam), wsl-hook-fs-adapter.ts (SFTP-shaped adapter + installWslGuestHooks, which targets Codex's managed runtime home).
• Wiring: buildPtyHostEnv (src/main/ipc/pty.ts) ensures the relay on every WSL spawn and repoints ORCA_AGENT_HOOK_ENDPOINT at the guest endpoint file once known; src/main/pty/wsl-orca-env.ts picks /u vs /p by value shape.
• Contract shared by both sides: src/shared/wsl-hook-relay-contract.ts.
• Oracles: src/relay/wsl-agent-hook-relay.test.ts, src/main/agent-hooks/wsl-hook-relay-manager.test.ts (fault injection: stale-42 reinstall, no-node-43 cooldown, bounded E_UNEXPECTED retry, exit re-ensure gating, and a full installer run against an in-memory guest).

References

• GitHub: issues 6907 (Codex/WSL), 7091 + 7565 (OMP, fixed), 7563 (WSL CLI detection, adjacent); PRs 7642 + 7641 (OMP fixes), 7744 (SSH hook installers precedent), 7447 (title-collapse regression).
• Linear: STA-1515 (this work; ticket comments carry the same context).
• Key files: src/main/agent-hooks/server.ts, src/shared/agent-hook-listener.ts, src/shared/agent-hook-relay.ts, src/relay/agent-hook-server.ts, src/relay/relay.ts, src/main/pty/wsl-orca-env.ts, src/main/agent-hooks/installer-utils.ts, src/main/pi/agent-status-extension-source.ts, src/main/ssh/ssh-relay-session.ts, src/main/providers/windows-shell-args.ts, src/shared/wsl-login-shell-command.ts.