History

Brennan Benson e58de71f5e feat(codex): real-home routing + self-contained multi-account homes (#9501 ) * feat(codex): backfill managed-home sessions into the real Codex home once per host Orca-launched Codex sessions currently land only in the Orca-managed runtime home, so the user's own `codex resume` picker and app history never see them (#4444, #8612). Backfill the managed sessions tree into the real ~/.codex/sessions/YYYY/MM/DD layout once per host: - hardlink first (one physical rollout log), copy as the cross-volume fallback; existing target files are always skipped, nothing in either home is deleted or moved - idempotent; per-file failures leave the completion marker unset so the next startup retries cheaply - JSONL audit log of every link/copy/failure under <userData>/codex-session-backfill/ - honors the custom Codex session source home override, mirroring the existing system->managed bridge WSL managed homes are distro-local and need an in-distro variant; that is a follow-up. * feat(codex): flag-gated system-default real-home routing scaffolding Staged internal flag (default OFF, no settings UI): route the SYSTEM-DEFAULT Codex account at the user's real ~/.codex instead of Orca's managed runtime home. Flag OFF is byte-identical to today; managed (multi-account) selections are unchanged in either state. Routing (flag ON + host system default = no managed account): - CodexRuntimeHomeService.prepareForCodexLaunch / prepareForRateLimitFetch return null so the PTY/env layer injects no managed CODEX_HOME and the rate-limit fetcher + auth-presence gate fall back to ~/.codex (the background poller stops spawning Codex against the managed home — the #5370 auth war). - buildPtyHostEnv strips only a nested-Orca-inherited Orca-owned override (CODEX_HOME matching the private ORCA_CODEX_HOME marker), preserving a user-set CODEX_HOME. Shell-ready re-exports already no-op without the marker. - The headless commit-message Codex path strips the same inherited override. Hook install for the real-home lane (append-last into ~/.codex/hooks.json, trust via the app-server client) lands with the trust plumbing; the managed hook install is skipped for this lane meanwhile. Credit @jellychoco (#8606) for the native-home routing direction. Depends on the codex trust-rpc-grant plumbing for the real-home hook installer. * fix(codex): strip the daemon-inherited Orca CODEX_HOME override for real-home routing The daemon spawns PTYs from its own inherited environment and honors only spawnOptions.envToDelete, so mutating the sparse env object was not enough to strip an Orca-owned CODEX_HOME the daemon already carries. Add the strip to envToDelete for both daemon host-spawn paths, preserving a user-set CODEX_HOME. Verified live via CDP against a sandboxed dev instance (flag ON): an Orca-spawned pane reports empty CODEX_HOME/ORCA_CODEX_HOME, so Codex resolves its own ~/.codex. Adds daemon-path unit coverage (strip Orca-owned, preserve user-owned, no-op when flag OFF). * fix(codex): harden one-time session backfill * test(codex): cover staged cross-volume install * feat(codex): app-server trust-grant client, capability cache, and grant ledger Short-lived codex app-server JSON-RPC client (hooks/list + config/batchWrite, the same pair the Codex TUI 'Trust all' flow calls), run in a bundled ELECTRON_RUN_AS_NODE entry so synchronous launch prep can block on it with a hard deadline and guaranteed child reap. Capability cache modeled on GitCapabilityCache, scoped per execution host (native vs each WSL distro), with a narrow unknown-method/missing-subcommand unsupported predicate. The grant ledger records verified grants so steady-state launches skip the RPC. * fix(codex): grant managed hook trust via codex app-server RPCs in install/refresh Host and WSL installs now grant trust for Orca's managed status hooks through codex's own hooks/list -> config/batchWrite -> re-list verify, scoped to exactly the managed entries; the previous computeTrustedHash lane is the unchanged fallback for incapable/erroring CLIs. getStatus and the removal paths recognize ledger-recorded codex hashes so drift between codex's real algorithm and the replica no longer misreports or strands trust. SSH remote install is untouched by design. * test(codex): cover app-server trust grant client, cache, ledger, and lanes * test(codex): cover commit-message real-home override strip/preserve Adds the two cases for the headless commit-message Codex env under real-home routing: a nested-Orca-inherited Orca-owned CODEX_HOME is stripped, and a user-owned CODEX_HOME is preserved. * test(codex): WSL grant-lane coverage — in-distro invocation and fallback parity * feat(codex): real-home hook installer trusted via the codex app-server grant client With the real-home flag ON and the system-default selection, install Orca's status hook into the user's real ~/.codex before any pane spawns: - entry APPENDED LAST per managed event: codex hook trust keys are positional (source:event:group:handler), so appending keeps every user entry's position and trust record intact; user entries and unknown top-level hooks.json fields are preserved verbatim - trust is granted exclusively through the codex app-server client (hooks/list + config/batchWrite, verified by re-list); Orca never writes [hooks.state] into the user's real config.toml itself - if the grant lane is unavailable (old binary, unsupported RPC, verify failure), the appended entry is rolled back byte-exactly and the host keeps the managed-home lane end to end (PTY env, rate limits, commit messages) via a lane gate on the runtime-home service - one-time pristine backup of the user's hooks.json under Orca's userData; a rolling .bak sits next to the file (existing atomic writer) - hook opt-out sweeps Orca entries from the real home and drops Orca-owned trust records; flag-off downgrade re-arms the existing legacy system-home sweep, which removes the entry and its trust keys cleanly - the legacy system-home sweep is suppressed only while the real-home lane owns ~/.codex/hooks.json, so managed installs cannot delete the entry * fix(codex): resolve the trust-grant entry without requiring electron The grant bridge is reachable from plain-Node CLI entries, where the plain-node entry guard rejects any chunk containing require("electron"). Resolve the bundled session entry from __dirname (root chunk and chunks/ layouts) with an app.asar -> app.asar.unpacked rewrite for packaged runs, instead of electron's app path APIs. * fix(codex): keep session backfill off main thread Use asynchronous, sequential filesystem operations for the one-time rollout backfill, and avoid repeated target-directory probes. Treat inaccessible managed session roots as retryable failures instead of writing a false completion marker. * fix(codex): harden app-server trust grant fallback * fix(codex): install cross-volume session backfill copies atomically On a real Codex home whose filesystem supports no hardlinks (exFAT/FAT, some network mounts), the staged cross-volume copy was installed with a non-atomic copyFile(..., COPYFILE_EXCL) straight into the final rollout-.jsonl name. An install interrupted mid-copy (app quit, crash, ENOSPC during the deferred run) could strand a truncated rollout that the next run then skips as already-present, defeating the staging design's own guarantee that a failed copy never leaves a partial session behind. Install the fully-staged copy with an atomic rename instead, guarded by an existence re-check so it keeps the never-overwrite contract (and the rename source is the same immutable managed rollout, so any clobber would be byte-identical). Cover the no-hardlink-support target and an interrupted install that must leave no partial in the user's sessions tree. fix(codex): resolve grant entry from __dirname so plain-node CLI entries stay electron-free The build guard rejects any electron require reachable from plain-node entries; the bridge now maps app.asar to app.asar.unpacked by string replacement instead of consulting electron app paths. CLI typecheck project lists the new trust-grant module graph. * fix(codex): harden trust grant reconciliation * fix(codex): restore trust config permissions on rollback * fix(codex): harden real-home routing cleanup and retries * fix(codex): preserve unicode trust RPC responses * fix(codex): preserve remote env and complete real-home cleanup * fix(codex): preserve real-home lane invariants * test(terminal): isolate replacement idle reset assertion * fix(codex): preserve real-home dotfile links * fix(codex): preserve verified trust grants across launch prep * fix(codex): preserve dangling config symlinks on rollback * fix(codex): don't revoke a just-granted WSL home on a false 'missing' probe The async wsl.exe canonical-path settlement could report the runtime home 'missing' immediately after a verified RPC grant (a false negative — codex had just written and re-listed trust there), which drove the reconciliation 'remove' branch to delete all six granted [hooks.state] tables, leaving a bare [hooks.state] the launching pane read as 'hooks need review'. A 'missing' settlement now revokes only when no successful install ran this generation; a genuinely moved home still resolves to a different path and reinstalls. * test(codex): model codex config/batchWrite faithfully on Windows The grant-lane stub simulated codex by calling Orca's upsertHookTrustEntries, which writes both separator variants for a Windows key (a fallback-lane compat shim real codex never does) — fabricating duplicate tables and whitespace the RPC path never produces, so the byte-stable and no-duplicate assertions failed on win32. Replace it with a single-variant, blank-line-separated writer that matches the real 0.144.x binary's output. * feat(codex): collapse duplicate session listings across Codex roots Backfilled/bridged rollouts are hardlinked into both the real ~/.codex and Orca's managed runtime home, so AI Vault listed each session once per root (#7521). Dedup candidates by rollout file name pre-parse and parsed sessions by session id post-parse, keeping the canonical root: host real home first (unprefixed resume), then the managed runtime home, then other homes. Applies to local, WSL, and SSH-remote scans. * feat(codex): background sqlite index heal for backfilled sessions Codex's own state-DB metadata backfill is one-shot, so rollouts hardlinked in by Orca's session backfill never become visible to Codex's DB-driven surfaces. Extract the app-server stdio JSONL transport into codex-app-server-session (shared with the trust-grant client) and add a bounded, resumable background pass that drives Codex's lazy indexing via thread/read per backfilled session: recent-first, batched onto one short-lived server per batch with small concurrency, ledger + marker so steady-state startups are a no-op, stop-aware on quit, and capability-aware on CLIs without the app-server surface. * fix(codex): preserve session identity during dedup heal * fix(codex): preserve user trust during real-home cleanup * fix(codex): harden real-home heal boundaries * fix(codex): fail closed on unsafe backfill install * fix: harden real-home hook cleanup * fix(ai-vault): preserve execution boundaries and reap children * fix(codex): narrow app-server unsupported detection * fix(codex): bound user hook trust rebase retries per host The rebase lane ran a codex app-server session on every launch prep while a host was stuck (CLI without app-server support, or keys hooks/list cannot match). Gate the transaction on the shared capability cache and add the same 5-minute transient cooldown the grant lane uses, so sweep and legacy-cleanup retries cost plain fs reads instead of a codex session per pane spawn. * fix(codex): enforce real-home resume and heal boundaries * fix(codex): establish real-home lane before cleanup * fix(codex): stop index heal before delayed spawn * fix(codex): protect symlinked rolling backups * fix(ai-vault): preserve resume env deletion through drag * fix(codex): strip inherited Codex homes on mobile real-home resume The mobile resume surface types a bare real-home codex resume into a freshly created pane, but never asked for CODEX_HOME/ORCA_CODEX_HOME deletion at pane spawn, so an agentDefaultEnv-pinned or daemon-inherited Codex home rerouted the resume away from the user's real ~/.codex while the same session resumed correctly on desktop. Share the deletion helper from the AI Vault resume builders and forward it through the mobile launch and session.tabs.createTerminal call. * fix(codex): gate session migration on real-home lane * fix(codex): stop session backfill after opt-out * fix(codex): keep session heal failures retryable * fix(codex): keep session migration state recoverable * fix(codex): retry republished missing session heals * fix(codex): preserve hook symlink trust path * fix(codex): disambiguate POSIX trust paths * fix(codex): align hook trust source paths * fix(codex): harden trust grant lifecycle * fix(codex): restore envToDelete on client invocation type after base reconcile * test(codex): type child.stdout as PassThrough for oversized-output write * Assemble RC: reconcile app-server transport API across PRs Unify on the object RPC surface from the index-heal transport (#8921) while preserving the default-home env strip (#8828) and the narrowed missing-app-server capability signal (#8847): adapt the user-hook-trust-rebase consumer + tests, port envToDelete stripping into the shared session, and route stderr classification through the canonical capability-signal module. * RC: enable system-default real-home routing by default (flag ON) Flip codexSystemDefaultRealHomeEnabled to default ON for this RC's staged rollout (a user can still opt out by setting it false, which stays byte-identical to managed-home behavior). This is the only intended behavior difference between the RC branch and the individual PRs. Updates the two tests that assumed the prior OFF default. * fix(codex): snapshot hooks.json bytes+parse in one read to close real-home clobber race The install/sweep/legacy-cleanup paths parsed hooks.json, then did a separate later read to capture the previous bytes for the pre-write generation guard. A concurrent save (second Orca instance or the user editing the file) could land between the parse and that second read and be silently overwritten. readHooksJsonWithRaw returns the raw bytes and parse from a single read so the guard compares against exactly what it parsed. Adds a regression test that mutates hooks.json mid-RPC and asserts the sweep aborts without clobbering. * fix(codex): sanitize managed account config trust * fix(codex): guard OAuth add for custom providers * fix(codex): persist outgoing managed tokens before real-home lane takeover (PR-C) prepareForCodexLaunch returns null early for the real-home / system-default lane before syncForCurrentSelection runs. If a managed account is still recorded as synced when the selection has dropped to the system default (nulled without a sync pass, or auto-deselect on missing managed auth), a Codex-refreshed token stranded in the shared runtime home is never persisted to its canonical per-account home -> token loss. Read the outgoing managed account's refreshed token back before the real home takes over. The real-home lane implies host === null, so running the managed->system-default transition restores only Orca's runtime mirror from ~/.codex and never writes the real ~/.codex. It is a no-op once the selection has already been reconciled, so the normal select path does not double-write. * fix(codex): preserve refreshes across all default transitions * feat(codex): show system-default/real-home account identity in switcher (PR-B) The account switcher modeled the system-default Codex account as activeAccountId:null with no identity fields, so the null row rendered blank ("System default" / generic subtitle) even though its effective login is whatever ~/.codex/auth.json currently is. Add a CodexSystemDefaultIdentity descriptor {hasAuth, authKind, email, providerAccountId, workspaceLabel} to CodexRateLimitAccountsState, resolved live and READ-ONLY from ~/.codex by the accounts service and returned from listAccounts()/getSnapshot(). The settings switcher now renders the null (system-default) row as that real identity: the OAuth email when signed in, "Custom provider — no usage tracked." for env-key/custom-provider logins (auth.json with OPENAI_API_KEY, or an OPENAI_API_KEY env with no auth.json), and the generic fallback when signed out. Identity is host-scoped (per-distro WSL keeps the generic label). Orca never writes ~/.codex; managed-account switches only touch Orca-owned homes, so the system-default identity stays a stable, displayed source of truth. Usage already routes to the real home via getSystemCodexHomePath, so the switcher now attributes it to a real face. Tests (sandboxed temp homes only): OAuth email/provider resolution, api-key auth.json and env-key (no auth.json) as custom-provider, signed-out, and select/deselect of a managed account never mutating ~/.codex/auth.json. * fix(codex): parse multiline provider pins in OAuth guard * fix(codex): harden managed trust sanitization * fix(codex): harden system-default identity rendering * feat(codex): give each managed account a self-contained CODEX_HOME; retire shared mirror (PR-E) With the real-home flag ON, a host managed account now launches directly against its own codex-accounts/<id>/home instead of the shared runtime mirror + auth.json hot-swap: - codex-home-paths: syncSystemCodexResourcesIntoManagedHome links system resources into any managed home (ownership-marker discipline; never symlinks into / mutates ~/.codex). - runtime-home-service: prepareForCodexLaunch / prepareForRateLimitFetch / syncForCurrentSelection route the per-account home directly and skip the shared-home hot-swap + token read-back; each home keeps its own auth in place (fixes GAP-5 concurrent auth race). Session discovery scans every per-account home. - hook-service / hook-trust-promotion: install/getStatus/refresh accept a runtimeHomePath so hooks + RPC-granted trust land in the per-account home. - service: config mirror into a self-contained home uses the trust- preserving merge so granted hook/project trust survives account switches. - codex-session-root-dedup: rank codex-accounts/<id>/home as canonical managed alongside the shared runtime home. Flag-OFF and the system-default real-home (null) lane are unchanged; the nested-Orca CODEX_HOME===ORCA_CODEX_HOME daemon strip (#5370) is preserved. Sandboxed tests only; ~/.codex is never mutated. * fix(codex): validate per-account home ownership * fix(codex): keep managed rollouts discoverable across real-home opt-out WI-4 lossless migration/rollback validation for pre-E shared-mirror managed accounts. Session discovery gated the per-account home scan on the real-home flag, so opting back out (flag OFF) hid every rollout an account accumulated while the flag was ON — the data stayed on disk but vanished from the AI Vault until the flag flipped back on. Scan a managed host home whenever it holds a sessions/ tree, independent of the flag; a never-enabled install keeps its homes credential-only so opt-out stays byte-identical to today. Forward migration was already lossless (the shared mirror is always scanned) and the opt-out credential read-back already refuses to overwrite a fresher per-account token; add tests locking all three invariants. Sandboxed tests only; ~/.codex is never touched. * fix(codex): migrate stranded shared auth on E takeover * test(e2e): isolate Electron from developer Codex home * test(codex): add real-account validation harness * fix(codex): finish C and E matcher composition * fix(codex): bound validation harness shutdown * test(codex): isolate hook lifecycle user data * test(codex): cover realistic account-home migration * fix(codex): keep standalone home tripwire active * test(codex): fingerprint system auth in validation reports * fix(codex): bind managed homes to account ownership * fix(codex): normalize Windows trust source identity * fix(codex): make Windows trust upgrade transactional * test(codex): use TypeScript pipeline for validation scripts * test(codex): run validation modules through native node * test(codex): allow slow Windows tripwire startup * fix(codex): survive lingering Windows codex login processes in add-account On Windows, codex login can keep running (with descendants) after it has written auth.json, holding OS handles on the per-account managed home (log/codex-login.log). That made doAddAccount's post-login cleanup fail with ENOTEMPTY (rmSync) and left an orphaned codex-accounts/<id>/home. - runCodexLogin now watches for auth.json on Windows and force-kills the login process tree (taskkill /t) if it lingers past a short grace period; the forced exit is treated as a successful login. The 120s timeout path also kills the whole tree instead of only the direct child. macOS/Linux behavior is unchanged. - safeRemoveManagedHome now removes homes with rmSync maxRetries / retryDelay (mirroring the local-worktree-filesystem Windows policy) and no longer lets a cleanup failure mask the original add error. - run-codex-real-account-validation.mjs accepts --temp-parent / ORCA_CODEX_VALIDATION_TEMP_PARENT so the disposable root can live outside %USERPROFILE% on Windows, and fails with an actionable message before creating anything when the temp parent is inside the primary home. The real-home guard is unchanged. * fix(codex): preserve managed-account MCP .credentials.json on per-account-home migration (#8440) Codex file-mode MCP OAuth tokens live in $CODEX_HOME/.credentials.json, keyed by MCP server URL with no account identity of their own. The legacy shared-mirror -> per-account-home migration only carried auth.json, so an existing managed account with authed MCP servers had its tokens stranded on upgrade and silently needed re-auth. Carry the shared mirror's .credentials.json into the same identity-proven per-account home alongside auth.json: only into the single uniquely-matched active account (no cross-account leak), only when the destination has none yet (never clobber a newer file the account authed in its own home), atomic 0600, absent-source no-op. New MCP auth already lands in the per-account home since that home is CODEX_HOME. * fix(codex): preserve Windows reauthentication login flow * test(codex): build real-account validation harness cross-platform on Windows The harness built its app with execFileSync('npx', ['electron-vite', ...]), but npx resolves to a .cmd shim on Windows that execFileSync cannot launch (ENOENT), so the harness could not build its own app there and required --skip-build with a prebuilt out/main/index.js. Extract resolveElectronViteBuildCommand(repoRoot): it runs the repository-local electron-vite JS entry (node_modules/electron-vite/bin/electron-vite.js) with the current Node binary (process.execPath), which resolves identically on macOS, Linux, and Windows with no shell. It throws a clear error if the local entry is missing (install deps or pass --skip-build). --skip-build behavior is unchanged. Add regression coverage asserting the build command uses process.execPath and the repo-local JS entry (not npx), and that a missing entry fails clearly. * fix(codex): version the MCP creds migration independently of the auth marker The auth carry and the MCP .credentials.json carry (#8440) shared one existence-only v1 marker, so any build that stamped the auth-only marker first would strand the MCP store forever. The MCP carry now concludes via its own per-account-mcp-creds-migration-v1.json marker and runs even when the auth marker is already present; ordering is code-enforced instead of landing-discipline-enforced. Also isolate per-account read failures: one stale or deleted account home no longer aborts the whole migration. The broken account stays in the unique-identity ambiguity gate via its stored fields but is never read or written, so the active account still migrates. * fix(codex): fail corrupt managed auth.json without echoing credential bytes A raw JSON.parse SyntaxError from loadOAuthCredentials could carry auth file fragments into logs and the add/reauth error surface. Throw a sanitized error instead; filesystem errors still propagate unchanged. * fix(mobile): give the pairing runtime a disposable home for the E2E boot guard The main-process guard now refuses to start with ORCA_E2E_USER_DATA_DIR set but the real user home, and this was the one caller not updated — the temporary pairing runtime crashed before emitting its pairing URL. * test(codex): canonicalize harness containment guards and retry cleanup Resolve symlinks before the disposable-root containment checks so a symlinked temp parent cannot smuggle the throwaway home inside the primary home, and give the final cleanup rm Windows retry/force so a briefly lingering codex handle cannot strand the credential-bearing root. * test(codex): add lane-aware containment mode to the real-account harness The Windows gate-D run proved strict zero-event whole-profile containment is structurally unreachable with the real-home flag ON: system-default spawn sites deliberately delete CODEX_HOME so native codex resolves the real ~/.codex, and on Windows the binary ignores the USERPROFILE sandbox. Its own volatile runtime churn (root sqlite/WAL/SHM, tmp/, log/) is the shipped Phase-1 design, not a candidate defect. --lane-aware-containment records those designed events without aborting while every other real-home write — auth.json, config.toml, .credentials.json, hooks.json, sessions/, anything unknown — remains a hard violation and still aborts the run. Default behavior is unchanged (strict); the absolute zero-event claim stays carried by macOS runs, where HOME does sandbox native codex. * test(codex): allow the real-account harness to pin the real-home flag off --system-default-real-home off seeds and env-pins the flag OFF so every codex spawn gets an explicit managed CODEX_HOME and native codex never resolves the OS profile. This is the only Windows configuration where the strict zero-event whole-profile tripwire is reachable, and it matches the stable-rollout default; flag-ON runs keep lane-aware classification. * test(codex): correct the flag-off harness comment to kill-switch rationale The rollout ships all codex-home changes at once (no phased rollout), so flag OFF is the emergency kill-switch lane, not the stable default. * test(e2e): canonicalize the isolated E2E home path The disposable HOME lives under os.tmpdir(), whose spelling is an alias on CI (macOS /var symlink, Windows 8.3 RUNNER~1). Git canonicalizes worktree paths, so worktrees created under the aliased home never matched the app's listing — golden core flows and the packaged crash-survival harness failed with 'worktree created but not found in listing'. Resolve the home to its canonical spelling at creation in both the e2e helper and the packaged-app driver. * fix(codex): address CodeRabbit review on the landing PR - carry envToDelete through the mobile agent-resume startup plan so a real-home Codex resume cannot inherit an ambient CODEX_HOME - strip Orca-owned Codex overrides in the commit-message WSL fallback, matching the host fallback - strip ELECTRON_RUN_AS_NODE in the computer-e2e driver like every other home-isolation caller - drop the unused hooksEnabled parameter from isRealHomeCodexHookLaneUsable * feat(codex): ship real-home routing unconditionally, remove the rollout flag The codexSystemDefaultRealHomeEnabled setting is gone from types and constants and the helper no longer consults settings — the system-default real-home lane and per-account homes ship for everyone in one release. This also un-strands profiles that rc-era builds stamped with false (the setting had no UI, so every stored false was a seeded artifact that would have silently kept those users on the legacy mirror forever). The ORCA_CODEX_SYSTEM_DEFAULT_REAL_HOME env override survives strictly as a test-rig control: the containment harness pins the legacy lane for strict zero-event Windows runs, e2e home isolation pins lanes inside disposable homes, and the legacy-lane test suites now route their per-test lane selection through it. --------- Co-authored-by: OrcaWin <alpha-eng@stably.ai>		2026-07-20 14:34:53 -07:00
..
README.md	test(e2e): prove the terminal daemon survives a main-process crash on Windows (#7742 ) (#9311 )	2026-07-19 11:27:29 -07:00
app-driver.mjs	feat(codex): real-home routing + self-contained multi-account homes (#9501 )	2026-07-20 14:34:53 -07:00
assertions.mjs	test(e2e): prove the terminal daemon survives a main-process crash on Windows (#7742 ) (#9311 )	2026-07-19 11:27:29 -07:00
cli-args.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
daemon-processes.mjs	test(e2e): prove the terminal daemon survives a main-process crash on Windows (#7742 ) (#9311 )	2026-07-19 11:27:29 -07:00
installer-steps.mjs	fix(win-update-e2e): install wait compared incomparable exe version formats (#7850 )	2026-07-08 19:45:48 -04:00
interactivity-probes.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
onboarding-profile.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
platform-guard.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
powershell-runner.mjs	test(e2e): prove the terminal daemon survives a main-process crash on Windows (#7742 ) (#9311 )	2026-07-19 11:27:29 -07:00
preflight.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
registry-shortcut-backup.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
run.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
window-enum.ps1	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
window-watch.mjs	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00
window-watch.ps1	Windows terminal update-survival (single consolidated PR) (#7538 )	2026-07-07 19:21:07 -04:00

README.md

win-update-e2e — packaged NSIS update proof harness

Windows only. Given two Orca Windows installers (version N and N+1), this harness performs a real silent update and proves, with machine-checkable assertions, what happens to the terminal daemon and its sessions across the update — and whether any console/terminal window flashes.

Companion harness: proving the daemon survives a crash of the main process (GitHub #7742), rather than an update, lives in tools/win-crash-survival-e2e. It reuses the shared modules in this directory (app driver, daemon discovery, PowerShell runner, platform guard, table renderer).

It is the Phase 0 "proof harness" deliverable from docs/windows-terminal-update-survival-plan.md. It exists specifically because the July 2026 attempt shipped four broken RCs without ever installing the packaged artifact (see docs/windows-terminal-update-survival-postmortem.md, "Why verification missed every one of these"). Its design refuses to repeat those verification failures:

Window visibility is measured by window enumeration + owner/canary attribution — never by conhost command-line heuristics. The post-mortem proved conhost flags invert with parent console state and MainWindowHandle is 0 for Windows-Terminal-hosted consoles. See window-enum.ps1.
Interactivity is proven by execution, not by result-shape. Typed commands write sentinel files; the harness checks the files. A command that "runs and returns correct output" but flashes a window is still caught, because the window watch runs independently.
The daemon is identified by command-line marker, never by exe name. With ELECTRON_RUN_AS_NODE the daemon image is Orca.exe; a relocated Phase 1 host may be a differently-named copied binary. See daemon-processes.mjs.
Each run uses an isolated userData dir so its daemon's socket/token path is unique and never collides with the many other daemons a dev box or CI runner can host.

Usage

pnpm win-update-e2e --from <setup.exe> --to <setup.exe> --expect <profile>
# or download release assets via gh (one call each):
pnpm win-update-e2e --from-release v1.4.124-rc.9 --to-release v1.4.125-rc.1 --expect cold-restore

Or directly: node tools/win-update-e2e/run.mjs --from ... --to ... --expect ...

Flags

Flag	Meaning
`--from <path>` / `--to <path>`	Local `orca-windows-setup.exe` for base (N) / update (N+1)
`--from-release <tag>` / `--to-release <tag>`	Download the setup asset from a GitHub release tag via `gh`
`--expect cold-restore \| survival`	Assertion profile (required)
`--install-dir <path>`	Isolated-install mode (see below) — install into `<path>`
`--asset-pattern <glob>`	gh asset glob (default `*windows-setup.exe`)
`--soak-seconds <n>`	Post-relaunch window-watch soak (default `180`)
`--keep-install`	Skip teardown/uninstall for debugging (ignored in isolated)

Profiles

cold-restore — today's behavior and the baseline that must keep passing against current main. The installer's path sweep kills the in-dir daemon, so: old daemon PID is dead, a fresh daemon exists, scrollback is cold-restored (best-effort), a new terminal is interactive, and zero unexpected console/terminal windows appear.
survival — the Phase 1 target. Daemon PID unchanged across the update, marker process still alive, the pre-update session still interactive (typed input echoes, Ctrl+C interrupts), and zero unexpected windows.

Safety

This harness installs, overwrites, and can uninstall a real app. Two guards protect a developer's machine; a clean CI/VM is unaffected by either:

Pre-existing app process → hard refusal. If an Orca app process (not a daemon) is already running, the run aborts and prints the offending PIDs. The harness never kills a process it did not start.
Pre-existing install → refusal unless --allow-existing-install. If an Orca install already exists under %LOCALAPPDATA%\Programs, the run refuses, because installing N then N+1 would silently overwrite that build and leave the --to version behind. Pass --allow-existing-install to proceed anyway.

Uninstall behavior at teardown follows ownership:

No pre-existing install (harness fully owns it): teardown silently uninstalls, unless --keep-install.
--allow-existing-install was used (an install existed first): teardown does not uninstall — removing a build the harness did not place would be wrong. It prints a prominent note that the machine now has the --to version and the prior build was not restored.

Isolated install mode (developer machines)

On a clean CI/VM the harness installs into the default per-user location (%LOCALAPPDATA%\Programs\Orca). A developer's box already has a real Orca there, and the safety guards above would (correctly) refuse to run. Isolated mode (--install-dir <path>) lets the harness run on that box without disturbing the real install.

The /D mechanism. electron-builder's NSIS honors the standard NSIS /D=<path> override for the install directory (node_modules/app-builder-lib/templates/nsis/multiUser.nsh). /D is special: it must be the last argument and cannot be quoted, so the path must be absolute and spaces-free (validated by validateInstallDir). The installer's kill-sweep only matches processes under its own $INSTDIR, so a separate directory never touches the real install's app or daemon processes.

Why registry/shortcut backup-restore exists. /D relocates files only. Regardless of /D, the installer writes InstallLocation + the uninstall entry to the same per-user HKCU keys as the real install (HKCU\Software\<APP_GUID> and HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\<key>, node_modules/app-builder-lib/templates/nsis/include/installer.nsh) and rewrites the Start Menu / Desktop shortcuts. Left hijacked, the user's next real update would install into the test directory. So isolated mode, before installing:

Snapshots the shared state (registry-shortcut-backup.mjs): reg exports each existing key to .reg files, copies the Orca *.lnk shortcuts, and records a manifest (which keys/shortcuts existed, the pre-run InstallLocation).
Runs the full install → update → assert proof against the isolated directory.
Always restores at teardown (a try/finally wraps everything after the snapshot): reg imports keys that pre-existed, reg deletes keys the test created, copies shortcuts back / deletes test-created ones, then re-reads InstallLocation and verifies it matches the snapshot. On mismatch it prints a loud block with the exact manual reg import command to recover. Isolated teardown always uninstalls the test install (the harness owns the directory) and removes the directory if empty — --keep-install is ignored.

Residual risk. The backup/restore covers InstallLocation, the uninstall entry, and the Orca shortcuts — the state that steers a future update and the user-visible launchers. It does not attempt to snapshot auto-update state files under the real install's userData (the harness uses an isolated userData throughout, so it never writes there), and it cannot restore state if the machine loses power mid-teardown (re-run with a valid --install-dir to let restore complete, or run the printed reg import by hand). The .reg backups live under the run's temp dir until a successful teardown removes it.

Example.

pnpm win-update-e2e \
  --from-release v1.4.124-rc.9 --to-release v1.4.125-rc.1 \
  --expect cold-restore --install-dir C:\OrcaE2E

Read-only, touches nothing — print what isolated mode would snapshot on this machine:

node tools/win-update-e2e/registry-shortcut-backup.mjs

What it does

Preflight — assert win32; warn if elevated; refuse to run if a pre-existing Orca app process (not a daemon) is running that the harness did not start (it is printed and the run aborts — the harness never kills a user's processes); snapshot the baseline set of visible top-level windows.
Install N silently (<setup.exe> /S) and locate Orca.exe.
Launch the installed app (Playwright _electron, isolated userData), create ≥2 terminals, start a marker in one: a powershell loop that sets a unique window-title canary, records its PID, and heartbeats a file.
Record the daemon PID (scoped pid-file + live-process scan), marker PID, and session tab ids.
Close the app normally; verify the detached daemon is still alive.
Start the window watch — a background PowerShell loop polling visible top-level windows every 500ms, diffing against baseline, recording every new window (and title change) to a JSONL log through the update and soak.
Install N+1 silently (the update).
Relaunch the app.
Assert per profile, then print a PASS/FAIL/INFO evidence table.
Teardown (unless --keep-install) — close app, kill only harness-created processes, silent-uninstall.

Exit code is 0 when every non-informational assertion passes, else 1 (2 for a CLI usage error).

Standalone instrument self-tests (no installers needed)

Each probe module runs on its own so the harness's own instruments are testable:

# Opens a real transient console window and asserts the watch catches it:
node tools/win-update-e2e/window-watch.mjs --selftest

# Read-only: list daemon processes + PID files on this machine:
node tools/win-update-e2e/daemon-processes.mjs [--user-data <dir>] [--scope <substr>]

# Emit the current visible-window snapshot as JSON:
powershell -File tools/win-update-e2e/window-enum.ps1

Files

File	Responsibility
`run.mjs`	Orchestrator + CLI entry
`cli-args.mjs`	Argument parsing / validation
`preflight.mjs`	win32/elevation checks, pre-existing-app refusal, baseline snapshot
`installer-steps.mjs`	Silent install/update/uninstall, exe discovery, gh download
`registry-shortcut-backup.mjs`	Isolated mode: snapshot/restore the shared HKCU keys + Orca shortcuts
`app-driver.mjs`	Playwright Electron launch + terminal driving (production-safe DOM selectors)
`interactivity-probes.mjs`	Sentinel-file echo / heartbeat / Ctrl+C probes
`daemon-processes.mjs`	Daemon PID discovery (command-line marker + pid file), scoped
`window-enum.ps1`	Shared visible-top-level-window enumerator (P/Invoke `EnumWindows`)
`window-watch.ps1`	Background baseline-diff watch loop → JSONL
`window-watch.mjs`	Node wrapper: start/stop watch, `--selftest`, baseline capture
`assertions.mjs`	Window-event classification + profile PASS/FAIL table
`platform-guard.mjs`	`assertWin32`, elevation detection
`powershell-runner.mjs`	Windows PowerShell 5.1 spawn helpers

Known limitations

Scrollback fidelity is best-effort. A production build renders the terminal with WebGL, so xterm text is not reliably in the DOM and the e2e SerializeAddon is not exposed. When text cannot be read the check reports INFO (unknown), never a false FAIL.
Daemon file log does not exist yet in packaged builds (the fork's stdio is suppressed). The "daemon log free of ERROR lines" assertion is INFO until Phase 0 daemon logging lands, then it reads <userData>/logs/daemon.log.
The harness assumes the packaged main honors ORCA_E2E_USER_DATA_DIR to relocate userData; verify this against a real packaged build.