Claude account profiles: dormant WSL guest setup (Step 3 of 4) by brennanb2025 · Pull Request #24384 · stablyai/orca

brennanb2025 · 2026-10-01T13:25:38Z

	Files	Added	Deleted	Net
Test	8	$\color{#1a7f37}{\Huge{\mathbf{+}}}$515	$\color{#cf222e}{\Huge{\mathbf{−}}}$1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$514
Prod	16	$\color{#1a7f37}{\Huge{\mathbf{+}}}$517	$\color{#cf222e}{\Huge{\mathbf{−}}}$65	$\color{#1a7f37}{\Huge{\mathbf{+}}}$452

ELI5

#24351 points every Orca Claude launch at the selected account's own folder. This PR does the same inside WSL: each account gets its own Claude folder inside the Linux distro, and Claude terminals in WSL use the selected one. It stays switched off until #24434, so nothing changes for users yet.

What Changed

Step 3 of 4 for STA-3698. Builds on #24351.

ClaudeWslProfileRouter gives each WSL distro the same four actions as the main router:
- write the which-account file inside the distro;
- prepare a launch, which waits only for an account that has never been set up;
- return the launch settings;
- give WSL terminals their environment.
Account setup runs as Linux inside the distro (claude-profile-wsl-entry.ts). It runs feat(claude): prepare account profiles and shared history (Step 1 of 4) #24300's setup on Orca's pinned Node runtime, the same one OpenCode's WSL reader already downloads, using the same cache and the same folder in the distro.
- History links stay inside the distro, so they resolve in WSL.
- Nothing is ever linked across the Windows/WSL boundary.
Stopped distros are never booted. Background updates skip any distro that isn't running.
Dev and packaged builds use separate which-account files in the distro.
Unchanged: OpenCode, and how Orca runs commands in WSL. Folding OpenCode onto the shared runtime installer is a separate follow-up.

Why

Setting up from Windows over \\wsl.localhost would be wrong:

Windows Node writes link targets in Windows form, which Linux can't follow.
File moves over that network share don't get the guarantees the setup relies on.

A plain shell script can't merge settings.json without tools a distro may not have. Reusing the runtime Orca already ships for WSL is the smallest correct option.

Linked Issue

Part of STA-3698 (fixed by #24434). Refs #9582.

Visual Proof

N/A. Switched off until #24434.

Testing

Unit tests cover the WSL router: publish, waiting only for a first setup, refusals, skipping stopped distros. A test bundles the guest helper and runs it.
Shell-setup snapshots and OpenCode's files are unchanged from the base.
Real-distro testing on a Windows machine with WSL is planned before fix(claude): activate account profiles and remove credential replay (Step 4 of 4) #24434.
I manually tested these changes locally
Automated tests added/updated, or explained why not below

Agent skill upstream boundary

Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Checklist

This PR is small and focused
I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
Before/after screenshots or videos attached for UI changes, or N/A with reason
Self-reviewed for correctness, security, and performance
Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

Review round 1 of the dormant profile setup found that the pieces could be called without their safety checks, that one failed write or an unreadable bookkeeping file could silently stop sharing for good, and that Windows prompt history could bring back history the user cleared. - One entry, provisionClaudeAccountProfile: the profile gate (namespace, no linked components, outside ~/.claude and ~/.config/claude, and an ownership marker beside the home naming the account and target) runs first and refuses before creating anything; then history sharing, config provisioning, and the hook install after the settings merge. Results come back per surface with closed warning codes instead of message text. - The sharing ledger is keyed by surface name, records a value only after its write succeeded, and an unreadable ledger starts empty and is rewritten instead of blocking every surface. - The profile state file goes through the same locked writer as folder trust (Claude's <file>.lock plus the in-process queue), generalized as updateClaudeGlobalConfig. Onboarding and trust are still applied when the personal state file is unreadable. - WSL descriptors build guest POSIX paths; the state-file path style follows the injected platform. - Orca's managed statusLine has one owner in a profile: the settings merge never shares it, a user's own statusLine is shared over it, and the profile installer follows the default home's slot so a default opt-out reaches every profile. remove() takes the same destination; the remote installer cannot accept one. - Prompt history compares file identity (bigint dev+ino) on every platform, never drains the shared file into itself, drains retained copies in generation order, never reuses a stale cursor, and on Windows keeps a replaced default's old copy aside instead of replaying it. Directory merges keep going past a failed entry.

A user's own Claude hooks in ~/.claude (notifications, formatters) did not run under a managed account, because the whole hooks key stayed private. They are now shared like any other settings key: Orca's own hook entries and its managed statusLine are stripped from both the personal value and the profile's current value before the per-key ledger comparison, so they never travel through the merge and never make the key look user-owned. Orca entries already in the profile are kept on write, and the profile hook installer adds them on top as before. Prompt history: merged bytes that lack a final newline are terminated, so Claude's next record no longer fuses onto the last merged line. When a CLI rewrote the profile's history file (old records plus new), only the lines past the part it shares with the default history are added, instead of the whole file again.

Hooks and statusLine sharing: - When ~/.claude holds only Orca's hook entries, the user's shared hooks now read as an empty value instead of a missing key. Removing the user's last own hook in ~/.claude therefore reaches profiles that never edited it, and deleting the only shared hook inside a profile stays deleted. - A custom statusLine Orca shared, and the profile never edited, goes away when the default home drops it. When a shared custom line replaced Orca's line in a profile, the profile's statusline marker is dropped so Orca's line comes back once the default returns to it; a profile that opted out stays opted out. No other key gains deletion. - install/remove/getStatus with a profile directory refuse when it is the default home, or its settings.json resolves to the default one, instead of editing System Default's hooks and opt-out state. - The profile statusline rule reads the default settings under the userHome passed to the setup entry, not os.homedir(). Profile state and ownership: - A malformed `projects` value skips only folder trust (new warning code trust-refused); onboarding and shared keys still apply. - The ownership marker stores only host-local facts (account, runtime, distro). The execution host id is the caller's view of the host, so it stays in the in-memory descriptor and is not compared. Prompt history interruption paths: - With no cursor yet, a retained copy starts past the bytes it shares with the default history, so an interrupted share no longer replays the whole history. - A retained name for the shared file itself is removed with its cursor instead of lingering until a later scrub makes it look new. - The Windows link record is read three-state: unreadable stops the share instead of reading as "no link". If the record cannot be written after linking, the fresh link is undone. - An unreadable retained copy is reported and no longer blocks linking.

hook-service.ts and hook-settings.ts are compiled into the packaged CLI project, which lists every file explicitly. The statusline policy and profile destination modules they now import were missing, so the CLI typecheck failed with TS6307. The CLI still loads hook-service through the existing managed-agent-hook-controls build entry, which bundles both modules; neither imports electron.

- A profile whose hooks hold only Orca's entries and that sharing never recorded is no longer treated as a user edit, so the user's first own hook in ~/.claude reaches it (for example when the profile was set up before ~/.claude had any hooks). - A retained prompt-history file is removed as a second name for the shared file only when the default history does not itself link to it; otherwise it holds the only copy and is kept. - Default-home checks compare file identity: the profile hook destination check uses device and inode, and the profile/default separation check resolves on-disk case, so a case-only alias of ~/.claude is refused on case-insensitive filesystems. - A test pins that an unreadable leftover session tree no longer blocks linking.

QA found that removing a setting from ~/.claude never reached a managed account: deleting the whole `hooks` block left the user's hook running there. Only statusLine followed the default away. Every shared key now follows the same rule through the existing per-key ledger: when a key disappears from ~/.claude/settings.json (or mcpServers/theme from the personal state file), it is removed from the profile if the profile still holds exactly what Orca last shared. A value changed inside the account is kept. Keys Orca never shared, including denylisted ones, are never touched. Deleting the whole hooks block removes the user's shared hooks and keeps Orca's own entries. A missing source counts as empty; an unreadable source removes nothing.

…rofile-setup

…e by capability Restores the inline mobile allowlist so its source-scan guard sees every accounts.* method again, and the generated params catalog to generator order.

…ed config dir The function is defined only in a routed pane where claude is a real executable (the codex function's guard), re-reads the pointer only while CLAUDE_CONFIG_DIR is unset or still Orca's injected twin, accepts Git Bash drive paths, and starts on its own line after the fish/PowerShell codex text.

…lifecycle triggers Round-1 review fixes for the dormant profile routing: - Panes get the selected profile's CLAUDE_CONFIG_DIR plus an Orca twin at spawn, so nested shells and scripts inherit the account; System Default injects nothing and its home is the inherited CLAUDE_CONFIG_DIR. - An absent routing owner is System Default, never a throw; AI Vault and session-search scans receive profile roots from their parent, and the capability is advertised only where an owner is installed. - Account listing never throws: per-account readiness, a stale pointer is republished in the background and reported on the snapshot. - Profiles are set up at select and startup; a launch only sets up one that never was, and a worker fault on a prepared profile is a warning. The Claude version probe is cached per binary identity. - Pre-trust goes through the existing deadline- and realpath-guarded writer against the launch env's profile config. - Skill discovery keeps a caller's Claude root and a broken Claude selection no longer fails other providers. - The durable record carries a provider-neutral launchAccountHome, read through one helper by the launch fallback and the model catalog.

…temp-home readers

…published A pointer left naming the previous account would launch it silently; a missing pointer makes the claude function refuse visibly. A newer selection that raced the failed one keeps its pointer.

…r than 3.4 Shell tests skip system config and abort unless claude resolves to the fake.

…fig dir lookup - An overtaken publish that fails leaves the newer selection's pointer. - The runtime config dir falls back to the legacy home for an unresolvable account or a WSL target, so skill roots never fail for other providers. - WSL guest reader roots merge verbatim, never realpathed on this thread. - History readers include ~/.claude, where step-1 setup pools profile history. - System Default ignores a config dir an outer Orca injected (twin-marked).

…eate resolver A Claude agent-env CLAUDE_CONFIG_DIR the create path stored is now the home the launch pins and the model probe accepts.

…on record

A worker thread's os.homedir() ignores its own env, so the hook and statusline scripts now go under the home the job names. The worker test pins the process HOME to a sentinel, refuses to run unless the worker sees it, and asserts nothing lands there.

…d of setting null On .NET 9+ (pwsh 7.5+) SetEnvironmentVariable with $null creates an empty variable, so stripped auth vars reached claude as empty strings and the restore left CLAUDE_CONFIG_DIR empty in the user's session.

…file publishes A WSL pane now gets the same non-throwing, guest-free spawn env as a host pane; only select, startup and Claude launches publish into the guest. Overlapping publishes of one target share the newest publish while the selection still names the same profile, instead of failing as superseded. Publish issues name their WSL distro and drop out when the target is no longer routed. A late inspect from an older selection no longer replaces the newer one's verification, a failed guest request evicts the cached guest, and readiness is derived per account from the guest's owned homes.

With profiles, a failed select or remove republishes just its own target instead of running startup over every WSL distro, and a rollback failure is logged instead of replacing the error that caused the rollback.

Vault and usage scans pass Claude profile roots through the same running-distro filter as every other WSL root, so a stopped distro's UNC paths are never walked.

The helper only ever runs inside WSL from the desktop, so it moves out of the SSH relay artifacts (no upload, no relay version change) into out/relay/wsl beside the other WSL-only guest bundles. The three WSL bundle resolvers share one candidate list.

…wnload per caller The pinned Node runtime needs glibc 2.28, so a distro below the floor is refused before any download with a message naming both versions, as SSH hosts are. The shared download again owns its own deadline and each caller waits on its own signal, and the OpenCode reader keeps its architecture error text.

…h the WSL runner A cached guest no longer carries its 180 s preparation deadline into later requests. The helper runs through runWslProcess (stdin payload, WSL_UTF8), the distro is confirmed running once per preparation and once per request, a failed `claude --version` probe continues with an unknown version like native setup, the helper resolves from the WSL bundle dir, and the guest entry decodes stdin once so split UTF-8 survives.

…ing' into claude-profile-wsl-lane # Conflicts: # src/main/ipc/pty/ipc/spawn-preflight.ts # src/main/ipc/pty/runtime/spawn-preflight.ts

…e import()

…es, link setup folders by path - Prompt-history drain appends only lines the shared file lacks, so a purge never re-adds lines. - A set-aside history copy whose saved offset reaches its end is deleted on the next run. - Setup folders link to the default home's own entry, not its resolved target. - The profile gate and folder creation run once, in provisionClaudeAccountProfile. - installHooks receives only configDir; drop a duplicate test key that fails CI.

…p' into claude-profile-routing-lane

…nother account; zsh claude function; setup timeout - With account routing, a chat resume checks its transcript is in the launch folder; a missing one with a stored leaf refuses with historyInOtherAccount instead of starting fresh. - The launch folder of a selected account comes from prepareLaunch(); the resolver stays for System default. - zsh panes get the claude function like bash, fish and PowerShell (empty while routing is off). - The setup worker is terminated after 60 s so a later launch can retry. - Document that the setup marker means setup started, not finished.