@bitkyc08/opencodex 2.53.0 → 2.54.0

package/src/codex/desktop-app/lock.ts

@@ -0,0 +1,226 @@
+/**
+ * Singleton lock for desktop-app restarts.
+ *
+ * Two restarts running at once are not merely wasteful, they are destructive: the
+ * first quits the app and relaunches it, the second re-enumerates during that window,
+ * sees the FRESHLY STARTED shell as a target, and kills it. Two
+ * `ocx sync --restart-codex` runs, or one handoff racing an ssh-issued direct run,
+ * are enough to produce it.
+ *
+ * Contended callers do not queue. Queueing would rebuild the same race one step
+ * later, so a caller that cannot take the lock reports `restart_in_flight` and stops.
+ *
+ * Two properties make the wp5 handoff work on top of this:
+ *
+ * - **Own-pid reentrancy.** A lock already naming this pid counts as held, not as
+ *   contention. That is what lets the detached helper run the ordinary ladder — the
+ *   caller hands it a lock already made out to it, and the helper takes no special
+ *   path. Without this the feature deadlocks: the caller holds the lock, discovers
+ *   it is inside the tree, and spawns a helper that waits for a lock its own parent
+ *   is holding.
+ * - **Compare-and-delete release.** A process only ever deletes a lock naming
+ *   itself. An unconditional unlink would let a late release destroy somebody else's
+ *   live lock, which is exactly the mutual exclusion this file exists to provide.
+ *
+ * Design: `devlog/_plan/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md` §4.1.
+ */
+import { mkdirSync, openSync, closeSync, writeSync, readFileSync, unlinkSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { getConfigDir } from "../../config/paths";
+
+/** A lock older than this is stale regardless of what its owner pid says. */
+const LOCK_MAX_AGE_MS = 5 * 60_000;
+
+export interface DesktopRestartLockRecord {
+  ownerPid: number;
+  createdAtMs: number;
+}
+
+export interface DesktopRestartLockIo {
+  lockPath?: string;
+  isAlive?: (pid: number) => boolean;
+  now?: () => number;
+  pid?: number;
+}
+
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readRecord(path: string): DesktopRestartLockRecord | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const view = parsed as Record<string, unknown>;
+    const ownerPid = view.ownerPid;
+    const createdAtMs = view.createdAtMs;
+    if (typeof ownerPid !== "number" || !Number.isSafeInteger(ownerPid) || ownerPid <= 0) return null;
+    if (typeof createdAtMs !== "number" || !Number.isFinite(createdAtMs)) return null;
+    return { ownerPid, createdAtMs };
+  } catch {
+    // Unreadable or malformed: treat as absent so a corrupted file cannot wedge every
+    // future restart. The staleness rules below still bound how long a real lock holds.
+    return null;
+  }
+}
+
+/**
+ * Exclusive create ON THE LOCK PATH. This is the whole mutual exclusion.
+ *
+ * The obvious-looking alternative - write a staging file with `wx` and `rename` it
+ * over the lock - is NOT exclusive: `wx` on a unique staging name always succeeds, and
+ * both racers then rename, so both believe they hold the lock and each kills the
+ * other's freshly relaunched app. The exclusivity has to come from `O_EXCL` on the
+ * contended path itself.
+ */
+function tryCreateExclusive(path: string, record: DesktopRestartLockRecord): boolean {
+  mkdirSync(dirname(path), { recursive: true });
+  let fd: number;
+  try {
+    fd = openSync(path, "wx", 0o600);
+  } catch {
+    return false;
+  }
+  try {
+    writeSync(fd, JSON.stringify(record));
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/**
+ * Atomic replace, used ONLY by an owner handing the lock to its helper.
+ *
+ * Safe there precisely because it is not the contended path: the caller already holds
+ * the lock, so there is no race to lose.
+ */
+function writeRecord(path: string, record: DesktopRestartLockRecord): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const staging = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  const fd = openSync(staging, "wx", 0o600);
+  try {
+    writeSync(fd, JSON.stringify(record));
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(staging, path);
+}
+
+export type DesktopRestartLockAcquisition =
+  | { acquired: true; record: DesktopRestartLockRecord }
+  | { acquired: false; heldBy: number };
+
+/**
+ * Take the lock, or report who holds it.
+ *
+ * Staleness is decided by owner liveness first and age second. Both read liveness by
+ * pid, so both inherit a small exposure: a recycled pid inside the window reads as
+ * "still alive" and produces a false `restart_in_flight`. That fails in the safe
+ * direction — a restart that did not happen, rather than one that happened to the
+ * wrong process — and the age bound stops it lasting.
+ */
+export function acquireDesktopRestartLock(
+  io: DesktopRestartLockIo = {},
+): DesktopRestartLockAcquisition {
+  const path = io.lockPath ?? defaultLockPath();
+  const isAlive = io.isAlive ?? defaultIsAlive;
+  const now = io.now ?? Date.now;
+  const self = io.pid ?? process.pid;
+
+  const existing = readRecord(path);
+  if (existing) {
+    // Own-pid reentrancy: a lock handed to us, or one we already hold.
+    if (existing.ownerPid === self) return { acquired: true, record: existing };
+    const stale = !isAlive(existing.ownerPid) || now() - existing.createdAtMs > LOCK_MAX_AGE_MS;
+    if (!stale) return { acquired: false, heldBy: existing.ownerPid };
+    // Stale. Clear it and then compete for the exclusive create like anyone else rather
+    // than writing straight over it: two processes can observe the same stale lock, and
+    // only O_EXCL decides which of them actually gets it.
+    try {
+      unlinkSync(path);
+    } catch {
+      /* somebody else cleared it first, which is fine - the create below still decides */
+    }
+  }
+
+  const record: DesktopRestartLockRecord = { ownerPid: self, createdAtMs: now() };
+  if (tryCreateExclusive(path, record)) return { acquired: true, record };
+
+  const winner = readRecord(path);
+  if (winner && winner.ownerPid === self) return { acquired: true, record: winner };
+  if (winner) {
+    // Lost the race fairly. Reporting contention is the honest answer; retrying would be
+    // the queue this deliberately avoids, and queueing rebuilds the same race one step
+    // later.
+    return { acquired: false, heldBy: winner.ownerPid };
+  }
+
+  // The file exists but names nobody: truncated, corrupt, or left behind by a writer
+  // that died between creating it and writing it. Without this it would block every
+  // future restart forever, reported as contention with an owner of 0 - a lock nobody
+  // holds and nobody can clear. Remove it and make exactly one more attempt, so a real
+  // winner that appears in between still keeps the lock.
+  try {
+    unlinkSync(path);
+  } catch {
+    /* somebody else cleared it first */
+  }
+  if (tryCreateExclusive(path, record)) return { acquired: true, record };
+  const successor = readRecord(path);
+  if (successor && successor.ownerPid === self) return { acquired: true, record: successor };
+  return { acquired: false, heldBy: successor?.ownerPid ?? 0 };
+}
+
+/**
+ * Hand the lock to a process that does not exist yet as far as the lock is concerned.
+ *
+ * Called only after a successful helper spawn. Doing it before would strand the lock
+ * on a pid that never came into being, and the next restart would have to wait out
+ * the staleness window for no reason.
+ */
+export function transferDesktopRestartLock(
+  toPid: number,
+  io: DesktopRestartLockIo = {},
+): boolean {
+  const path = io.lockPath ?? defaultLockPath();
+  const now = io.now ?? Date.now;
+  const self = io.pid ?? process.pid;
+  const existing = readRecord(path);
+  if (!existing || existing.ownerPid !== self) return false;
+  try {
+    writeRecord(path, { ownerPid: toPid, createdAtMs: now() });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Who currently holds the lock, or null when nobody does or it is unreadable. */
+export function readDesktopRestartLockOwner(io: DesktopRestartLockIo = {}): number | null {
+  return readRecord(io.lockPath ?? defaultLockPath())?.ownerPid ?? null;
+}
+
+/** Compare-and-delete. Never removes a lock owned by another process. */
+export function releaseDesktopRestartLock(io: DesktopRestartLockIo = {}): void {
+  const path = io.lockPath ?? defaultLockPath();
+  const self = io.pid ?? process.pid;
+  const existing = readRecord(path);
+  if (!existing || existing.ownerPid !== self) return;
+  try {
+    unlinkSync(path);
+  } catch {
+    /* already gone */
+  }
+}
+
+export function defaultLockPath(): string {
+  // getConfigDir owns OPENCODEX_HOME resolution, including ~ expansion and the caching
+  // every other consumer sees. Re-deriving it here would drift from it.
+  return join(getConfigDir(), "desktop-restart.lock");
+}

package/src/codex/desktop-app/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Platform contract for the Codex desktop-app restart.
+ *
+ * One ladder in `../desktop-app-restart.ts` drives every platform; the only things
+ * that actually differ are identity, discovery, membership, the two stop primitives
+ * and relaunch. Keeping those seven behind this interface is what stopped the
+ * PID-reuse and fail-closed reasoning from being re-derived three times, once per
+ * operating system, with two of the three getting it subtly wrong.
+ *
+ * Design and audit history: `devlog/_plan/260913_cross_platform_desktop_app_restart/`.
+ */
+import { sep } from "node:path";
+
+/** Bounded subprocess options. A hung probe must never wedge `ocx sync`. */
+export interface DesktopAppExecOptions {
+  timeout?: number;
+  windowsHide?: boolean;
+}
+
+/** Returns stdout. Options are part of the seam so the timeout is testable. */
+export type DesktopExec = (
+  file: string,
+  args: readonly string[],
+  options?: DesktopAppExecOptions,
+) => string;
+
+/** One discovered installation of the Codex desktop app. */
+export interface DesktopAppInstall {
+  /** Stable platform-specific identity, used in messages and for relaunch. */
+  id: string;
+  /**
+   * Absolute, ALREADY `realpath`-RESOLVED directory every member executable must
+   * live under. Resolution happens once here rather than per candidate so that
+   * {@link isUnderRoot} is a pure string comparison against a trusted value.
+   */
+  root: string;
+  /** Opaque relaunch descriptor only the owning adapter interprets. */
+  relaunch: string;
+}
+
+export interface DesktopProcess {
+  pid: number;
+  parentPid: number;
+  /**
+   * Platform-native start-time token, compared verbatim and never parsed.
+   *
+   * This is the field that distinguishes a process from a replacement that reused
+   * its pid. A pid alone is not an identity across a graceful-close window long
+   * enough for the OS to recycle one.
+   */
+  createdAt: string;
+  /** Absolute executable path, used for membership and the shell predicate. */
+  executable: string;
+}
+
+export interface DesktopAppAdapter {
+  /** `null` means discovery failed. Never throws. */
+  discover(exec: DesktopExec): DesktopAppInstall | null;
+  /**
+   * `null` means the probe could not RUN. `[]` means it ran and found nothing.
+   *
+   * The distinction is not pedantic: collapsing them told users the app was not
+   * running and silently skipped a restart they had explicitly asked for (#2557).
+   */
+  listProcesses(exec: DesktopExec, install: DesktopAppInstall): DesktopProcess[] | null;
+  /**
+   * True when this member is the app shell rather than a helper.
+   *
+   * "Parent is not a member" is not sufficient on its own. macOS crashpad handlers
+   * are launchd children, so they sit at ppid 1 and would otherwise be classified
+   * as roots — including stale ones left by an instance that already exited, which
+   * would be signalled and could never be made to "survive" cleanly.
+   */
+  isShell(process: DesktopProcess, install: DesktopAppInstall): boolean;
+  /**
+   * Ancestry of the current process, innermost first.
+   *
+   * `[]` means "could not establish that we are outside the tree" and the ladder
+   * fails closed on it. A parent pid naming no live process is NOT that case: it is
+   * a clean end of chain, which is the normal state of the detached handoff helper
+   * on Windows, where orphans are never reparented.
+   */
+  ancestryPids(exec: DesktopExec): number[];
+  /** Ask the app to quit. Best effort; the ladder decides what happens next. */
+  requestQuit(exec: DesktopExec, install: DesktopAppInstall, root: DesktopProcess): void;
+  /** Unconditional termination of one shell and its tree. */
+  forceStop(exec: DesktopExec, root: DesktopProcess): void;
+  /**
+   * Capture what the relaunch will need, from the LIVE tree, before anything stops.
+   *
+   * This is on the contract rather than inside the Linux adapter because of its
+   * ordering obligation. A ladder that called it after termination would work on
+   * macOS and Windows and produce a Linux app that cannot reach the compositor —
+   * the failure would look platform-specific when it is really an ordering bug.
+   */
+  captureRelaunchContext(
+    exec: DesktopExec,
+    install: DesktopAppInstall,
+    processes: readonly DesktopProcess[],
+  ): Record<string, string>;
+  /** Start the app again. THROWS on failure; the ladder reports `relaunch_failed`. */
+  relaunch(
+    exec: DesktopExec,
+    install: DesktopAppInstall,
+    context: Record<string, string>,
+  ): void;
+}
+
+/**
+ * Path-boundary membership test.
+ *
+ * A raw `startsWith` admits siblings: an install root of `/usr/lib/chatgpt` would
+ * also match `/usr/lib/chatgpt-evil/ChatGPT`, and `/Applications/ChatGPT.app` would
+ * match `/Applications/ChatGPT.app-evil/...`. Both are plantable by the same user
+ * whose processes are about to be signalled, so same-uid scoping does not cover it.
+ *
+ * `root` is expected to be `realpath`-resolved by discovery already.
+ */
+export function isUnderRoot(executable: string, root: string): boolean {
+  if (!executable || !root) return false;
+  if (executable === root) return true;
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  return executable.startsWith(prefix);
+}
+
+/**
+ * Shells whose parent is not itself a member of the tree.
+ *
+ * Helpers are deliberately enumerated but never returned here: they are what
+ * {@link DesktopAppAdapter.captureRelaunchContext} reads on Linux, and terminating
+ * the shell takes them anyway.
+ */
+export function rootShells(
+  processes: readonly DesktopProcess[],
+  install: DesktopAppInstall,
+  adapter: Pick<DesktopAppAdapter, "isShell">,
+): DesktopProcess[] {
+  const memberPids = new Set(processes.map(entry => entry.pid));
+  return processes.filter(entry =>
+    adapter.isShell(entry, install) && !memberPids.has(entry.parentPid));
+}

package/src/codex/desktop-app/windows.ts

@@ -0,0 +1,239 @@
+/**
+ * Windows adapter for the Codex desktop-app restart.
+ *
+ * Moved from `desktop-app-restart.ts`. Behaviour is the Appx/CIM/taskkill path
+ * that already shipped: runtime package discovery, current-user GetOwner
+ * scoping, CloseMainWindow then taskkill /T /F, relaunch through the discovered
+ * AUMID. The shape is DesktopAppAdapter so the ladder, not this file, owns
+ * PID-reuse re-verification and the fail-closed sequencing.
+ *
+ * Measured (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md §3):
+ * OpenAI.Codex MSIX, ChatGPT.exe, InstallLocation under WindowsApps.
+ */
+import { execFileSync } from "node:child_process";
+import { sep, win32 } from "node:path";
+import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsTaskkillExe } from "../../lib/windows-elevation";
+import {
+  isUnderRoot,
+  type DesktopAppAdapter,
+  type DesktopAppInstall,
+  type DesktopExec,
+  type DesktopProcess,
+} from "./types";
+
+/** Every probe is bounded; PowerShell module loading is the slow part. */
+const PROBE_TIMEOUT_MS = 10_000;
+const MAX_ANCESTRY_HOPS = 16;
+const SHELL_BASENAME = "chatgpt.exe";
+
+const POWERSHELL_PROBE_OPTIONS = { timeout: PROBE_TIMEOUT_MS, windowsHide: true } as const;
+
+/**
+ * isUnderRoot prefixes with the host path.sep and is case-sensitive. Windows
+ * membership is case-insensitive, and this file is executed by Unix CI against
+ * backslash paths, so both sides are folded onto the host separator first.
+ * The boundary itself — sibling `OpenAI.Codex-evil` must not match root
+ * `OpenAI.Codex` — is still isUnderRoot's, which is why the PowerShell
+ * StartsWith is only a cheap pre-filter.
+ */
+function toHostMembershipPath(windowsPath: string): string {
+  const lowered = windowsPath.toLowerCase();
+  return sep === "\\" ? lowered : lowered.replaceAll("\\", "/");
+}
+
+function isMemberExecutable(executable: string, root: string): boolean {
+  return isUnderRoot(toHostMembershipPath(executable), toHostMembershipPath(root));
+}
+
+/**
+ * Runtime discovery, never a hardcoded identifier. The beta MSIX package family
+ * changes between builds, so a literal AUMID would silently stop matching and
+ * then either do nothing or — worse — match a package we did not mean.
+ */
+function discoverPackage(exec: DesktopExec): DesktopAppInstall | null {
+  const script = [
+    "$ErrorActionPreference='SilentlyContinue'",
+    "Import-Module Appx -ErrorAction SilentlyContinue",
+    "$p = Get-AppxPackage -Name OpenAI.Codex",
+    "if (-not $p) { $p = Get-AppxPackage -Name OpenAI.CodexBeta }",
+    "if (-not $p -or -not $p.InstallLocation) { 'MISS' } else {",
+    "  $p.PackageFamilyName; $p.InstallLocation; \"$($p.PackageFamilyName)!App\"",
+    "}",
+  ].join("; ");
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], POWERSHELL_PROBE_OPTIONS);
+  } catch {
+    return null;
+  }
+  const lines = stdout.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+  if (lines.length < 3 || lines[0] === "MISS") return null;
+  const [family, installLocation, aumid] = lines;
+  if (!family || !installLocation || !aumid) return null;
+  return { id: family, root: installLocation, relaunch: aumid };
+}
+
+/**
+ * Only `ChatGPT.exe` processes whose image lives under the discovered install
+ * location AND owned by the current user. The install location alone is not
+ * enough: an MSIX package under `WindowsApps` is shared, so on a multi-user
+ * machine another account's Codex desktop matches the same path. The app-server
+ * collector already pays for `GetOwner` for exactly this reason.
+ *
+ * `CreationDate` is captured so a PID can be re-verified before it is signalled;
+ * a graceful-close window is long enough for Windows to recycle a PID.
+ *
+ * ExecutablePath is included so membership can be decided by {@link isUnderRoot}
+ * rather than by PowerShell's `StartsWith`, which is a prefix test and would
+ * admit a sibling `OpenAI.Codex-evil` directory.
+ */
+function listPackageProcesses(exec: DesktopExec, install: DesktopAppInstall): DesktopProcess[] | null {
+  const literal = install.root.replace(/'/g, "''");
+  const script = [
+    "$ErrorActionPreference='SilentlyContinue'",
+    `$root = '${literal}'`,
+    "$me = ([Security.Principal.WindowsIdentity]::GetCurrent()).Name",
+    "Get-CimInstance Win32_Process -Filter \"Name='ChatGPT.exe'\" |",
+    "  Where-Object { $_.ExecutablePath -and $_.ExecutablePath.StartsWith($root, 'OrdinalIgnoreCase') } |",
+    "  ForEach-Object {",
+    "    $o = Invoke-CimMethod -InputObject $_ -MethodName GetOwner",
+    "    if ($o -and $o.ReturnValue -eq 0 -and $o.User) {",
+    "      $owner = if ($o.Domain) { \"$($o.Domain)\\$($o.User)\" } else { $o.User }",
+    "      if ($owner -ieq $me) {",
+    "        \"$($_.ProcessId) $($_.ParentProcessId) $($_.CreationDate.ToString('o')) $($_.ExecutablePath)\"",
+    "      }",
+    "    }",
+    "  }",
+  // Statements must be newline-separated. Joining with a space concatenates
+  // `$ErrorActionPreference='SilentlyContinue' $root = '...'` into one malformed statement,
+  // which PowerShell rejects — so the probe threw and every caller read "not running" (#2557).
+  ].join("\n");
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], POWERSHELL_PROBE_OPTIONS);
+  } catch {
+    // A probe that could not run is NOT proof the app is absent. Returning [] here made a
+    // failed enumeration indistinguishable from "no targets", so the CLI reported the app as
+    // not running and skipped a restart the user had explicitly asked for.
+    return null;
+  }
+  const processes: DesktopProcess[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    const parsed = parseProcessLine(line, install.root);
+    if (parsed) processes.push(parsed);
+  }
+  return processes;
+}
+
+function parseProcessLine(line: string, root: string): DesktopProcess | null {
+  const match = /^\s*(\d+)\s+(\d+)\s+(\S+)(?:\s+(.+))?$/.exec(line);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  const parentPid = Number(match[2]);
+  const createdAt = match[3] ?? "";
+  const listed = (match[4] ?? "").trim();
+  // The live probe emits ExecutablePath. Historical listings, and the tests that
+  // script them, were three tokens because the PowerShell filter is already
+  // Name='ChatGPT.exe' under root. Synthesize that image so executable is
+  // populated without treating a missing path as a different process.
+  const executable = listed.length > 0 ? listed : `${root.replace(/[\\/]+$/, "")}\\ChatGPT.exe`;
+  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parentPid) || !createdAt || !executable) {
+    return null;
+  }
+  // Authoritative membership. PowerShell StartsWith already cheap-filtered, but
+  // that test is a string prefix and is how a sibling install would sneak in.
+  if (!isMemberExecutable(executable, root)) return null;
+  return { pid, parentPid, createdAt, executable };
+}
+
+/**
+ * Full Windows parent chain for this process, innermost first.
+ *
+ * `process.ppid` is one level, which is not enough: a terminal hosted inside the
+ * desktop app sits several hops below `ChatGPT.exe`, so a one-level check would
+ * miss the exact case the guard exists for and we would terminate our own host.
+ * The chain therefore comes from CIM, with a bound so a corrupted parent cycle
+ * cannot spin.
+ */
+function windowsAncestryPids(exec: DesktopExec): number[] {
+  const chain: number[] = [process.pid];
+  let current = process.pid;
+  for (let hop = 0; hop < MAX_ANCESTRY_HOPS; hop++) {
+    let stdout: string;
+    try {
+      stdout = exec(resolveTrustedWindowsPowerShellExe(), [
+        "-NoProfile", "-NonInteractive", "-Command",
+        `$ErrorActionPreference='SilentlyContinue'; (Get-CimInstance Win32_Process -Filter "ProcessId=${current}").ParentProcessId`,
+      ], POWERSHELL_PROBE_OPTIONS);
+    } catch {
+      // An unreadable chain must not be read as "not our ancestor".
+      return [];
+    }
+    const trimmed = stdout.trim();
+    // Empty output means the pid has no live CIM entry: a CLEAN end of chain, not
+    // a read failure. Windows never reparents orphans, so the detached handoff
+    // helper always has a dead parent link once its caller exits. Reading that as
+    // unreadable would make the helper refuse forever and the feature would never
+    // work on Windows.
+    if (trimmed === "") return chain;
+    const parent = Number(trimmed);
+    if (!Number.isSafeInteger(parent) || parent <= 0) return chain;
+    if (chain.includes(parent)) return chain;
+    chain.push(parent);
+    current = parent;
+  }
+  // Bound reached without finding the top. A truncated chain silently defeats the
+  // self-ancestry intersection, so this reports "could not establish" instead.
+  return [];
+}
+
+export const windowsDesktopAppAdapter: DesktopAppAdapter = {
+  discover(exec): DesktopAppInstall | null {
+    return discoverPackage(exec);
+  },
+
+  listProcesses(exec, install): DesktopProcess[] | null {
+    return listPackageProcesses(exec, install);
+  },
+
+  isShell(entry): boolean {
+    return win32.basename(entry.executable).toLowerCase() === SHELL_BASENAME;
+  },
+
+  ancestryPids(exec): number[] {
+    return windowsAncestryPids(exec);
+  },
+
+  requestQuit(exec, _install, root): void {
+    exec(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `$p = Get-Process -Id ${root.pid} -ErrorAction SilentlyContinue; if ($p) { [void]$p.CloseMainWindow() }`,
+    ], POWERSHELL_PROBE_OPTIONS);
+  },
+
+  forceStop(exec, root): void {
+    exec(resolveTrustedWindowsTaskkillExe(), ["/PID", String(root.pid), "/T", "/F"], POWERSHELL_PROBE_OPTIONS);
+  },
+
+  captureRelaunchContext(): Record<string, string> {
+    // The session is supplied by the shell:AppsFolder launch, so nothing needs
+    // carrying forward.
+    return {};
+  },
+
+  relaunch(exec, install): void {
+    // Throws on failure so the ladder reports relaunch_failed. The old code
+    // returned targets_survived here, which was dishonest: everything HAD died
+    // and it was the relaunch that failed.
+    exec(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Start-Process 'shell:AppsFolder\\${install.relaunch}'`,
+    ], POWERSHELL_PROBE_OPTIONS);
+  },
+};
+
+export const windowsDefaultExec: DesktopExec = (file, args, options) => execFileSync(file, [...args], {
+  encoding: "utf-8",
+  timeout: options?.timeout ?? PROBE_TIMEOUT_MS,
+  windowsHide: options?.windowsHide ?? true,
+});