@bitkyc08/opencodex 2.53.0-preview.20260913 → 2.54.0-preview.20260914

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

@@ -0,0 +1,303 @@
+/**
+ * Restarting the Codex app you are running inside.
+ *
+ * The self-ancestry guard is correct to refuse a direct restart: terminating your own
+ * tree kills the command mid-flight and leaves the operator with neither a restarted
+ * app nor an explanation. But on a developer machine that refusal fires in the normal
+ * case, not a corner case - the measured shell is
+ * `zsh -> bundled codex app-server -> ChatGPT -> launchd`, so anything run from a Codex
+ * terminal or agent session is inside the tree. Without a handoff, the merged
+ * `--restart-codex` would refuse in exactly the situation that produced the original
+ * "it does nothing" report.
+ *
+ * So the refusal becomes a handoff: a detached helper outlives the caller, waits for it
+ * to exit, re-enumerates, and performs the restart from outside the tree.
+ *
+ * Two things make the helper safe to kill the app around:
+ *
+ * - It waits for the calling process to exit first. At that moment it is orphaned and
+ *   reparented, so it is no longer reachable by a tree walk from the app root. This
+ *   matters most on Windows, where `taskkill /T` follows live parent links and never
+ *   reparents orphans.
+ * - It re-runs the ancestry check itself rather than trusting the caller's finding, and
+ *   it passes `allowHandoff: false` so it can only ever take the direct path or refuse.
+ *   Recursion is structurally impossible rather than merely unlikely.
+ *
+ * Design: devlog/_plan/260913_cross_platform_desktop_app_restart/020_phase2_detached_self_handoff.md
+ */
+import { spawn } from "node:child_process";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { getConfigDir } from "../../config/paths";
+import {
+  readDesktopRestartLockOwner,
+  releaseDesktopRestartLock,
+  transferDesktopRestartLock,
+  type DesktopRestartLockIo,
+} from "./lock";
+
+/** How long the helper waits for its caller to exit before giving up. */
+const CALLER_EXIT_TIMEOUT_MS = 20_000;
+const CALLER_POLL_MS = 100;
+/** A plan older than this is not ours to run. */
+const PLAN_MAX_AGE_MS = 5 * 60_000;
+
+export interface DesktopRestartHandoffPlan {
+  schemaVersion: 1;
+  /** Pid the helper waits on before acting. */
+  callerPid: number;
+  createdAtMs: number;
+}
+
+export type HandoffStartOutcome =
+  | { kind: "started"; helperPid: number; logPath: string }
+  | { kind: "failed"; reason: "no_executable" | "plan_write_failed" | "spawn_failed" | "lock_transfer_failed" };
+
+export interface HandoffIo {
+  now?: () => number;
+  pid?: number;
+  execPath?: string;
+  argv?: readonly string[];
+  homeDir?: string;
+  lock?: DesktopRestartLockIo;
+  spawnHelper?: (command: string, args: readonly string[]) => { pid?: number | undefined; unref(): void };
+  isAlive?: (pid: number) => boolean;
+  sleep?: (ms: number) => void;
+}
+
+export function handoffLogPath(io: HandoffIo = {}): string {
+  return join(io.homeDir ?? getConfigDir(), "desktop-restart-handoff.log");
+}
+
+/**
+ * How to re-invoke this CLI as the helper.
+ *
+ * `process.execPath` alone is not enough, because it differs between running from a
+ * checkout, through the installed npm shim, and as a packaged binary. Resolution is
+ * explicit and a failure to resolve is a REFUSAL rather than a guess: spawning the
+ * wrong interpreter with a path that does not exist produces a helper that exits
+ * immediately and an operator who was told the restart was handed off.
+ */
+export function resolveHelperCommand(io: HandoffIo = {}): { command: string; args: string[] } | null {
+  const execPath = io.execPath ?? process.execPath;
+  const argv = io.argv ?? process.argv;
+  const entry = argv[1];
+  if (entry && existsSync(entry)) return { command: execPath, args: [entry] };
+  if (basename(execPath).replace(/\.exe$/i, "") === "ocx") return { command: execPath, args: [] };
+  return null;
+}
+
+function writePlan(path: string, plan: DesktopRestartHandoffPlan): boolean {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    // Exclusive create: the path is handed to another process, so it must not be
+    // possible to hand over a file somebody else authored.
+    const fd = openSync(path, "wx", 0o600);
+    try {
+      writeSync(fd, JSON.stringify(plan));
+    } finally {
+      closeSync(fd);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function startDesktopRestartHandoff(io: HandoffIo = {}): HandoffStartOutcome {
+  const resolved = resolveHelperCommand(io);
+  if (!resolved) return { kind: "failed", reason: "no_executable" };
+
+  const now = io.now ?? Date.now;
+  const callerPid = io.pid ?? process.pid;
+  const home = io.homeDir ?? getConfigDir();
+  const planPath = join(home, `desktop-restart-handoff-${callerPid}-${Math.random().toString(36).slice(2)}.json`);
+  const plan: DesktopRestartHandoffPlan = { schemaVersion: 1, callerPid, createdAtMs: now() };
+  if (!writePlan(planPath, plan)) return { kind: "failed", reason: "plan_write_failed" };
+
+  const args = [...resolved.args, "internal", "desktop-restart-handoff", "--plan", planPath];
+  let child: { pid?: number | undefined; unref(): void };
+  try {
+    child = (io.spawnHelper ?? defaultSpawnHelper)(resolved.command, args);
+  } catch {
+    try { unlinkSync(planPath); } catch { /* best effort */ }
+    return { kind: "failed", reason: "spawn_failed" };
+  }
+  if (child.pid === undefined) {
+    // A detached child reports a failed launch asynchronously, to a parent that is about
+    // to exit. An absent pid is the only synchronous evidence the spawn happened.
+    try { unlinkSync(planPath); } catch { /* best effort */ }
+    return { kind: "failed", reason: "spawn_failed" };
+  }
+  child.unref();
+
+  // Hand the lock over only AFTER a successful spawn. Doing it earlier 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 nothing.
+  //
+  // A FAILED transfer is not cosmetic. The lock would still name this process, which is
+  // about to exit, so it reads as stale for the whole helper wait and a concurrent
+  // restart could reclaim it and run a second ladder - the dual-kill the lock exists to
+  // prevent. Reporting failure here is safe because the helper independently refuses to
+  // act unless the lock names IT, so the spawned process becomes a no-op rather than an
+  // unsupervised restart.
+  if (!transferDesktopRestartLock(child.pid, io.lock)) {
+    return { kind: "failed", reason: "lock_transfer_failed" };
+  }
+  return { kind: "started", helperPid: child.pid, logPath: handoffLogPath(io) };
+}
+
+const defaultSpawnHelper = (command: string, args: readonly string[]): { pid?: number | undefined; unref(): void } =>
+  spawn(command, [...args], { detached: true, stdio: "ignore", windowsHide: true });
+
+export type HandoffRunOutcome =
+  | "restarted"
+  | "caller_still_running"
+  | "plan_unreadable"
+  | "plan_expired"
+  | "not_lock_owner"
+  | "restart_incomplete";
+
+function readPlan(path: string): DesktopRestartHandoffPlan | 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>;
+    if (view.schemaVersion !== 1) return null;
+    const callerPid = view.callerPid;
+    const createdAtMs = view.createdAtMs;
+    if (typeof callerPid !== "number" || !Number.isSafeInteger(callerPid) || callerPid <= 0) return null;
+    if (typeof createdAtMs !== "number" || !Number.isFinite(createdAtMs)) return null;
+    return { schemaVersion: 1, callerPid, createdAtMs };
+  } catch {
+    return null;
+  }
+}
+
+/** True when the path is inside the opencodex home AND named like a plan this CLI writes. */
+export function isOwnPlanPath(planPath: string, io: HandoffIo = {}): boolean {
+  const home = io.homeDir ?? getConfigDir();
+  let resolvedPlan: string;
+  let resolvedHome: string;
+  try {
+    resolvedHome = resolve(home);
+    resolvedPlan = resolve(planPath);
+  } catch {
+    return false;
+  }
+  if (dirname(resolvedPlan) !== resolvedHome) return false;
+  return /^desktop-restart-handoff-\d+-[a-z0-9]+\.json$/.test(basename(resolvedPlan));
+}
+
+function defaultIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function defaultSleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Append one JSON line per run. Counts, never command lines or OS error text: the same
+ * projection the management restart response already applies, for the same reason.
+ */
+function appendLog(io: HandoffIo, entry: Record<string, unknown>): void {
+  try {
+    const path = handoffLogPath(io);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify({ at: new Date((io.now ?? Date.now)()).toISOString(), ...entry }) + "\n");
+  } catch {
+    /* the restart matters more than the record of it */
+  }
+}
+
+export interface HandoffRunIo extends HandoffIo {
+  restart?: (allowHandoff: false) => { relaunch: "started" | "skipped"; reason?: string; stopped: number[]; surviving: number[] };
+  readLockOwner?: () => number | null;
+}
+
+export async function runDesktopRestartHandoff(
+  planPath: string,
+  io: HandoffRunIo = {},
+): Promise<HandoffRunOutcome> {
+  const now = io.now ?? Date.now;
+  const self = io.pid ?? process.pid;
+  // Only ever touch a file this CLI could have written. Unlinking whatever --plan points
+  // at turned a hidden helper command into an unlink oracle: a same-uid caller could pass
+  // a config path and have it deleted on the way to being told the plan was unreadable.
+  if (!isOwnPlanPath(planPath, io)) {
+    appendLog(io, { outcome: "plan_unreadable" });
+    releaseDesktopRestartLock(io.lock);
+    return "plan_unreadable";
+  }
+  const plan = readPlan(planPath);
+  // Unlink only AFTER the shape is confirmed, so a file that merely lives in the right
+  // directory under the right name is still not destroyed by a malformed read.
+  if (plan) {
+    try { unlinkSync(planPath); } catch { /* the plan is single-use either way */ }
+  }
+  if (!plan) {
+    appendLog(io, { outcome: "plan_unreadable" });
+    releaseDesktopRestartLock(io.lock);
+    return "plan_unreadable";
+  }
+  if (now() - plan.createdAtMs > PLAN_MAX_AGE_MS) {
+    // A plan left behind by a crash must not restart the app hours later.
+    appendLog(io, { outcome: "plan_expired" });
+    releaseDesktopRestartLock(io.lock);
+    return "plan_expired";
+  }
+
+  const isAlive = io.isAlive ?? defaultIsAlive;
+  const sleep = io.sleep ?? defaultSleep;
+  const deadline = now() + CALLER_EXIT_TIMEOUT_MS;
+  // Bounded by polls as well as by the clock. The clock alone is not enough: if sleep
+  // does not actually advance time - a frozen clock, a no-op sleep - this becomes a hot
+  // spin that never exits, inside a detached process nobody is watching.
+  const maxPolls = Math.ceil(CALLER_EXIT_TIMEOUT_MS / CALLER_POLL_MS) + 1;
+  for (let poll = 0; poll < maxPolls && now() < deadline && isAlive(plan.callerPid); poll++) {
+    sleep(CALLER_POLL_MS);
+  }
+  if (isAlive(plan.callerPid)) {
+    // A caller that outlives the window is not the short-lived `ocx sync` this was built
+    // for, and quitting the app out from under an unknown long-running process is not
+    // something to guess about.
+    appendLog(io, { outcome: "caller_still_running", callerPid: plan.callerPid });
+    releaseDesktopRestartLock(io.lock);
+    return "caller_still_running";
+  }
+
+  // The lock must name THIS process. It was made out to us by the caller; if it names
+  // anybody else, the transfer failed or somebody reclaimed it, and acting now would be
+  // the unsynchronised second ladder the lock exists to prevent.
+  const owner = (io.readLockOwner ?? (() => readDesktopRestartLockOwner(io.lock)))();
+  if (owner !== self) {
+    appendLog(io, { outcome: "not_lock_owner" });
+    return "not_lock_owner";
+  }
+
+  try {
+    const restart = io.restart
+      ? io.restart(false)
+      : (await import("../desktop-app-restart")).restartCodexDesktopApp({
+        allowHandoff: false,
+        lock: io.lock,
+      });
+    const ok = restart.relaunch === "started";
+    appendLog(io, {
+      outcome: ok ? "restarted" : "restart_incomplete",
+      reason: restart.reason,
+      stopped: restart.stopped.length,
+      surviving: restart.surviving.length,
+    });
+    return ok ? "restarted" : "restart_incomplete";
+  } finally {
+    releaseDesktopRestartLock(io.lock);
+  }
+}
+

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

@@ -0,0 +1,388 @@
+/**
+ * Linux adapter for the Codex desktop-app restart.
+ *
+ * Measured shape (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
+ *
+ *   /usr/bin/chatgpt -> /usr/lib/chatgpt/codex-launcher  (2-line sh script)
+ *   that execs /usr/lib/chatgpt/ChatGPT
+ *
+ *   3284901  /usr/lib/chatgpt/ChatGPT                         (root: no --type=)
+ *   3284913  /usr/lib/chatgpt/ChatGPT --type=zygote
+ *   3284951  /usr/lib/chatgpt/ChatGPT --type=gpu-process
+ *   3284953  /usr/lib/chatgpt/ChatGPT --type=utility ...
+ *
+ * The root's /proc/<pid>/environ is 1902 bytes of NUL: Chromium scrubs it after
+ * startup. Session variables survive only in children that inherited them before
+ * the scrub. Measured on lidge: DISPLAY=:1, XDG_SESSION_TYPE=x11,
+ * XDG_RUNTIME_DIR=/run/user/1000,
+ * DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  isUnderRoot,
+  type DesktopAppAdapter,
+  type DesktopAppInstall,
+  type DesktopExec,
+  type DesktopProcess,
+} from "./types";
+
+const INSTALL_ID = "chatgpt";
+const SHELL_NAME = "ChatGPT";
+/** Absolute candidates only. A chatgpt earlier on PATH must not redirect a kill or a launch. */
+const LAUNCHER_CANDIDATES = ["/usr/bin/chatgpt", "/usr/local/bin/chatgpt"] as const;
+const SETSID = "/usr/bin/setsid";
+const PROC_ROOT = "/proc";
+const MAX_ANCESTRY_HOPS = 16;
+/** Group-write 0o020 | world-write 0o002. Sticky/setgid bits are not a trust failure. */
+const GROUP_OR_WORLD_WRITE = 0o022;
+
+/**
+ * Copied into the relaunch environment and nothing else.
+ *
+ * /proc/<pid>/environ is another process's full environment and routinely carries
+ * API keys and session tokens. Copying it wholesale would move credentials between
+ * security contexts for no benefit.
+ */
+const SESSION_ENV_KEYS = [
+  "DISPLAY",
+  "WAYLAND_DISPLAY",
+  "XDG_RUNTIME_DIR",
+  "XDG_SESSION_TYPE",
+  "DBUS_SESSION_BUS_ADDRESS",
+] as const;
+
+const MINIMAL_ENV_KEYS = ["HOME", "USER", "LOGNAME", "LANG"] as const;
+const RELAUNCH_PATH = "/usr/local/bin:/usr/bin:/bin";
+
+function procPath(pid: number, leaf: string): string {
+  return PROC_ROOT + "/" + String(pid) + "/" + leaf;
+}
+
+function readProcExe(pid: number): string {
+  const link = readlinkSync(procPath(pid, "exe"));
+  return typeof link === "string" ? link : Buffer.from(link).toString("utf8");
+}
+
+function currentUid(): number | undefined {
+  try {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Root and shell must be uid 0 and not group/world writable.
+ *
+ * dirname(realpath(launcher)) alone is not enough: /usr/local/bin is group-writable
+ * on some systems, so a planted chatgpt -> ~/x/codex-launcher beside a ~/x/ChatGPT
+ * would make an attacker-chosen directory the membership boundary and the relaunch
+ * target. A failed check is a discovery failure, never a fallback to the next
+ * candidate -- otherwise the planted /usr/local/bin/chatgpt becomes the target.
+ *
+ * stat (follow) rather than lstat: a root-owned symlink to a user-writable directory
+ * must fail on the target's mode, not pass on the symlink's.
+ */
+function isTrustedSystemPath(path: string): boolean {
+  try {
+    const st = statSync(path);
+    return st.uid === 0 && (st.mode & GROUP_OR_WORLD_WRITE) === 0;
+  } catch {
+    return false;
+  }
+}
+
+function discoverFromCandidate(candidate: string): DesktopAppInstall | null | "absent" {
+  let resolvedLauncher: string;
+  try {
+    resolvedLauncher = realpathSync(candidate);
+  } catch {
+    return "absent";
+  }
+  const root = dirname(resolvedLauncher);
+  const shell = join(root, SHELL_NAME);
+  if (!isTrustedSystemPath(root) || !isTrustedSystemPath(shell)) return null;
+  return { id: INSTALL_ID, root, relaunch: candidate };
+}
+
+function parsePpidAndRealUid(status: string): { parentPid: number; uid: number } | null {
+  const ppidMatch = /^PPid:\s+(\d+)/m.exec(status);
+  const uidMatch = /^Uid:\s+(\d+)/m.exec(status);
+  if (!ppidMatch || !uidMatch) return null;
+  const parentPid = Number(ppidMatch[1]);
+  const uid = Number(uidMatch[1]);
+  if (!Number.isSafeInteger(parentPid) || !Number.isSafeInteger(uid)) return null;
+  return { parentPid, uid };
+}
+
+/**
+ * Field 22 (starttime) as an opaque token. Located after the LAST ')' because comm
+ * can contain spaces and parentheses -- this app's helpers are literally named
+ * "Codex (Service)".
+ */
+function parseStarttimeToken(stat: string): string | null {
+  const close = stat.lastIndexOf(")");
+  if (close < 0) return null;
+  const fields = stat.slice(close + 2).split(/\s+/);
+  const starttime = fields[19];
+  return starttime ? starttime : null;
+}
+
+function cmdlineHasElectronType(pid: number): boolean | "unreadable" {
+  try {
+    const args = readFileSync(procPath(pid, "cmdline")).toString("utf8").split("\0");
+    return args.some(arg => arg.startsWith("--type="));
+  } catch {
+    return "unreadable";
+  }
+}
+
+function parseEnviron(buf: Buffer): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const entry of buf.toString("utf8").split("\0")) {
+    if (!entry) continue;
+    const eq = entry.indexOf("=");
+    if (eq <= 0) continue;
+    out[entry.slice(0, eq)] = entry.slice(eq + 1);
+  }
+  return out;
+}
+
+function sessionEnvFrom(source: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of SESSION_ENV_KEYS) {
+    const value = source[key];
+    if (typeof value === "string" && value.length > 0) out[key] = value;
+  }
+  return out;
+}
+
+function byStarttimeAscending(a: DesktopProcess, b: DesktopProcess): number {
+  // starttime is a jiffies integer stored in a string. A lexical sort misorders
+  // it ("100" < "99"), so the oldest child -- the one most likely to still hold
+  // the pre-scrub session -- would not be tried first.
+  return Number(a.createdAt) - Number(b.createdAt);
+}
+
+function minimalRelaunchEnv(): Record<string, string> {
+  const env: Record<string, string> = { PATH: RELAUNCH_PATH };
+  for (const key of MINIMAL_ENV_KEYS) {
+    const value = process.env[key];
+    if (value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+let killProcess: (pid: number, signal: NodeJS.Signals) => void = (pid, signal) => {
+  process.kill(pid, signal);
+};
+
+/** Test-only seam, so a kill can be observed without ending a developer's own Codex. */
+export function setLinuxKillForTests(
+  next: ((pid: number, signal: NodeJS.Signals) => void) | null,
+): void {
+  killProcess = next ?? ((pid, signal) => { process.kill(pid, signal); });
+}
+
+type LinuxSpawn = (
+  command: string,
+  args: readonly string[],
+  options: { detached: boolean; stdio: "ignore"; env: NodeJS.ProcessEnv },
+) => { pid?: number | undefined; unref(): void };
+
+const defaultSpawn: LinuxSpawn = (command, args, options) => {
+  const child = spawn(command, [...args], {
+    detached: options.detached,
+    stdio: options.stdio,
+    env: options.env,
+    shell: false,
+  });
+  // Headless ENOENT arrives as an async 'error'; without a listener it is an
+  // uncaught exception that kills the caller after relaunch has already returned.
+  child.on("error", () => {});
+  return child;
+};
+
+let spawnProcess: LinuxSpawn = defaultSpawn;
+
+/** Test-only seam, so relaunch can be observed without starting ChatGPT. */
+export function setLinuxSpawnForTests(next: LinuxSpawn | null): void {
+  spawnProcess = next ?? defaultSpawn;
+}
+
+export const linuxDesktopAppAdapter: DesktopAppAdapter = {
+  discover(_exec): DesktopAppInstall | null {
+    for (const candidate of LAUNCHER_CANDIDATES) {
+      const found = discoverFromCandidate(candidate);
+      if (found === "absent") continue;
+      return found;
+    }
+    return null;
+  },
+
+  listProcesses(_exec, install): DesktopProcess[] | null {
+    // A missing or unreadable /proc is an enumeration failure, not absence. Collapsing
+    // those told users the app was not running and skipped a restart they asked for.
+    if (!existsSync(PROC_ROOT)) return null;
+    let names: string[];
+    try {
+      names = readdirSync(PROC_ROOT);
+    } catch {
+      return null;
+    }
+    const uid = currentUid();
+    if (uid === undefined) return null;
+
+    const out: DesktopProcess[] = [];
+    for (const name of names) {
+      if (!/^\d+$/.test(name)) continue;
+      const pid = Number(name);
+      if (!Number.isSafeInteger(pid)) continue;
+      try {
+        const executable = readProcExe(pid);
+        if (!isUnderRoot(executable, install.root)) continue;
+        const identity = parsePpidAndRealUid(readFileSync(procPath(pid, "status"), "utf8"));
+        if (!identity || identity.uid !== uid) continue;
+        const createdAt = parseStarttimeToken(readFileSync(procPath(pid, "stat"), "utf8"));
+        if (!createdAt) continue;
+        out.push({
+          pid,
+          parentPid: identity.parentPid,
+          createdAt,
+          executable,
+        });
+      } catch {
+        // Per-pid EACCES/ENOENT (and a pid that vanished mid-scan) skip that pid.
+        // They are not an enumeration failure.
+        continue;
+      }
+    }
+    return out;
+  },
+
+  isShell(entry, install): boolean {
+    if (entry.executable !== join(install.root, SHELL_NAME)) return false;
+    // Unreadable cmdline cannot prove this is the shell, so it is not a root.
+    return cmdlineHasElectronType(entry.pid) === false;
+  },
+
+  ancestryPids(_exec): number[] {
+    const chain: number[] = [process.pid];
+    let current = process.pid;
+    for (let hop = 0; hop < MAX_ANCESTRY_HOPS; hop++) {
+      let status: string;
+      try {
+        status = readFileSync(procPath(current, "status"), "utf8");
+      } catch (error) {
+        // Two different situations arrive here and they must not be merged.
+        //
+        // ENOENT means the pid is simply gone. That is a CLEAN end of chain and the
+        // normal state above an orphaned handoff helper, so the chain collected so far
+        // is returned and the caller can still be judged outside the tree.
+        //
+        // Any OTHER error means we could not look, and "could not look" must never be
+        // read as "we are outside the tree": that reading lets the ladder signal the
+        // shell hosting the caller's own session. Hop 0 is this process itself, which
+        // always exists, so a failure there is always a read failure.
+        const code = (error as NodeJS.ErrnoException | null)?.code;
+        if (hop > 0 && code === "ENOENT") return chain;
+        return [];
+      }
+      const parsed = parsePpidAndRealUid(status);
+      if (!parsed || parsed.parentPid <= 0) return chain;
+      const parent = parsed.parentPid;
+      if (chain.includes(parent)) return chain;
+      chain.push(parent);
+      if (parent === 1) return chain;
+      current = parent;
+    }
+    // Bound reached without finding the top. A truncated chain silently defeats
+    // the self-ancestry intersection, so this reports "could not establish".
+    return [];
+  },
+
+  requestQuit(_exec, _install, root): void {
+    // Honest ceiling: /proc/<root>/status on lidge had SIGTERM in neither SigCgt
+    // nor SigIgn, so the Linux shell has the default SIGTERM disposition.
+    // SIGTERM here is termination, not a graceful shutdown request. The app
+    // registers no DBus quit method and has no systemd unit.
+    killProcess(root.pid, "SIGTERM");
+  },
+
+  forceStop(_exec, root): void {
+    killProcess(root.pid, "SIGKILL");
+  },
+
+  captureRelaunchContext(_exec, _install, processes): Record<string, string> {
+    const ordered = processes.slice().sort(byStarttimeAscending);
+    for (const entry of ordered) {
+      let buf: Buffer;
+      try {
+        buf = readFileSync(procPath(entry.pid, "environ"));
+      } catch {
+        continue;
+      }
+      const environ = parseEnviron(buf);
+      // The root is typically oldest and all-NUL after Chromium's scrub. Keep
+      // walking until a child that inherited the session before the scrub.
+      if (!environ.XDG_RUNTIME_DIR) continue;
+      return sessionEnvFrom(environ);
+    }
+    return {};
+  },
+
+  relaunch(_exec, install, context): void {
+    if (!context.XDG_RUNTIME_DIR) {
+      // An app started without a session cannot reach the compositor, but
+      // Electron still takes the single-instance lock, so the user's real
+      // session then cannot start either.
+      throw new Error(
+        "missing graphical session: XDG_RUNTIME_DIR was not recovered from the live process tree",
+      );
+    }
+    const env = { ...minimalRelaunchEnv(), ...sessionEnvFrom(context) };
+    // The launcher is a sh script and Electron resolves its user-data directory
+    // from HOME. Starting it with only the five session variables would produce
+    // an app that launches and then behaves as a different user profile.
+    const child = spawnProcess(SETSID, [install.relaunch], {
+      detached: true,
+      stdio: "ignore",
+      env,
+    });
+    // A detached child reports a failed launch asynchronously, and this process is
+    // about to stop caring about it, so the 'error' event has nobody to reach. An
+    // absent pid is the synchronous signal that the spawn never happened - without
+    // this check a missing /usr/bin/setsid still reported relaunch: "started".
+    if (child.pid === undefined) {
+      throw new Error("failed to spawn " + SETSID + " for the Codex desktop app relaunch");
+    }
+    // detached already calls setsid(2); the setsid binary then auto-forks because
+    // it finds itself a group leader. The overlap is deliberate belt-and-braces
+    // against a runtime that changes detached semantics. No --fork is needed.
+    child.unref();
+  },
+};
+
+/**
+ * Linux needs no subprocess for discovery or enumeration - everything comes from
+ * /proc and the filesystem - so this exists only to satisfy the shared contract and
+ * to keep the ladder's adapter selection uniform. It is deliberately execFileSync
+ * with a bounded timeout rather than a throwing stub, so a future adapter method that
+ * does need a subprocess gets the same trusted-path, bounded-probe treatment as the
+ * other two platforms instead of inventing its own.
+ */
+export const linuxDefaultExec: DesktopExec = (file, args, options) => execFileSync(file, [...args], {
+  encoding: "utf-8",
+  stdio: ["ignore", "pipe", "ignore"],
+  timeout: options?.timeout ?? 10_000,
+});
+