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

package/src/cli/restart-scope.ts

@@ -0,0 +1,184 @@
+/**
+ * The restart scope a command was asked for, and the post-write restart itself.
+ *
+ * Its own module because `sync`, `sync-cache` and `catalog pull` all need it, and
+ * having `catalog.ts` import it from `dispatch.ts` would make the two files circular.
+ */
+import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import type { AfterCatalogWriteAppServerResult } from "../codex/app-server-processes";
+import type { DesktopAppRestartResult } from "../codex/desktop-app-restart";
+
+/**
+ * Which restart a command was asked for.
+ *
+ * `--restart-codex` used to mean app-server-only, and the desktop restart was a
+ * separate Windows-only opt-in. That split existed because quitting the app ends live
+ * conversations, which is a bigger consent than restarting a background helper. The
+ * reasoning was sound and is superseded by an explicit maintainer decision:
+ * `--restart-codex` now means the app is fully stopped and started again. The narrow
+ * behaviour did not disappear, it moved to a flag that names it.
+ *
+ * One reader for every command, so `sync`, `sync-cache` and `catalog pull` cannot
+ * drift in what the same flag means.
+ */
+export interface RestartScope {
+  /** Signal matching app-server / code-mode-host processes. */
+  appServers: boolean;
+  /** Fully quit and relaunch the Codex desktop app. */
+  desktopApp: boolean;
+}
+
+export function readRestartScope(
+  args: readonly string[],
+  log: Pick<Console, "error">,
+): RestartScope {
+  const appServerOnly = args.includes("--restart-app-server-only");
+  const legacyDesktop = args.includes("--restart-desktop-app");
+  const restartCodex = args.includes("--restart-codex");
+  if (legacyDesktop) {
+    log.error(
+      "--restart-desktop-app is deprecated: --restart-codex now restarts the Codex "
+      + "desktop app on every platform. The flag still works and will be removed in a "
+      + "future release.",
+    );
+  }
+  if (appServerOnly && (restartCodex || legacyDesktop)) {
+    // Contradictory scopes, and the NARROW one wins. Losing live conversations is
+    // unrecoverable; a stale model picker is not. A user who typed the app-server-only
+    // flag asked not to lose them.
+    log.error(
+      "--restart-app-server-only overrides --restart-codex/--restart-desktop-app; "
+      + "the desktop app was left running.",
+    );
+    return { appServers: true, desktopApp: false };
+  }
+  if (appServerOnly) return { appServers: true, desktopApp: false };
+  if (restartCodex || legacyDesktop) return { appServers: true, desktopApp: true };
+  return { appServers: false, desktopApp: false };
+}
+
+export interface RestartScopeOutcome {
+  appServers?: AfterCatalogWriteAppServerResult;
+  desktopApp?: DesktopAppRestartResult;
+}
+
+/**
+ * The post-write restart, for every command that performs one.
+ *
+ * App-servers that belong to the desktop tree are excluded when a desktop restart is
+ * also going to run: the app-server is a CHILD of the app on every platform, so
+ * signalling it first and then quitting the app interrupts the operator's in-flight
+ * turn twice in one command. A discovery or probe failure yields no exclusion, which
+ * is the safe direction - a missed exclusion costs an extra interruption, a wrong one
+ * leaves a stale app-server serving a roster that no longer exists.
+ */
+export async function handleRestartScopeAfterWrite(
+  scope: RestartScope,
+  log: Pick<Console, "log" | "error">,
+): Promise<RestartScopeOutcome> {
+  const { listCodexDesktopAppPids } = await import("../codex/desktop-app-restart");
+  // KNOWN LIMITATION on Windows. The exclusion matches pids against the discovered
+  // desktop tree, and the Windows probe enumerates only ChatGPT.exe, while Windows
+  // app-servers run as codex.exe / codex-code-mode-host. They therefore never match and
+  // still receive SIGTERM before the app quits, so Windows keeps the double interruption
+  // this exclusion removes on macOS and Linux - where the app-server executable does live
+  // under the bundle or install root and is enumerated.
+  //
+  // Closing it means widening the Windows probe past ChatGPT.exe, which is the same query
+  // that decides what may be killed, so it needs its own verification rather than being
+  // appended here. The restart itself is correct on Windows either way; the cost is one
+  // extra interrupted turn.
+  const excludePids = scope.desktopApp ? (listCodexDesktopAppPids() ?? []) : [];
+  const appServers = afterCatalogWriteHandleAppServers({
+    restart: scope.appServers, log, excludePids,
+  });
+  const desktopApp = scope.desktopApp ? await handleDesktopAppRestart(log) : undefined;
+  return { appServers, desktopApp };
+}
+
+/**
+ * Report the outcome of a desktop-app restart. Kept next to the callers so every
+ * command tells the user the same thing.
+ */
+export async function handleDesktopAppRestart(
+  log: Pick<Console, "log" | "error">,
+): Promise<DesktopAppRestartResult> {
+  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
+  const { startDesktopRestartHandoff } = await import("../codex/desktop-app/handoff");
+  const result = restartCodexDesktopApp({
+    // The CLI is the one caller whose exit is exactly the signal the helper waits for,
+    // so it is the one caller allowed to hand off. The management service is not (it
+    // runs in a proxy that never exits) and the helper itself is not (recursion).
+    startHandoff: () => {
+      const outcome = startDesktopRestartHandoff();
+      return outcome.kind === "started"
+        ? { helperPid: outcome.helperPid, logPath: outcome.logPath }
+        : null;
+    },
+  });
+  switch (result.reason) {
+    case "unsupported_platform":
+      log.error(
+        `Restarting the Codex desktop app is not supported on ${process.platform}; `
+        + "nothing was stopped.",
+      );
+      return result;
+    case "restart_in_flight":
+      log.error(
+        "Another Codex desktop-app restart is already running; this one did nothing. "
+        + "Wait for it to finish and check again.",
+      );
+      return result;
+    case "relaunch_failed":
+      log.error(
+        "The Codex desktop app was stopped but could not be started again. Launch it manually.",
+      );
+      return result;
+    case "package_discovery_failed":
+      log.error(
+        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
+        + "manually to refresh the model picker.",
+      );
+      return result;
+    case "handoff_started":
+      // Saying the session will end is the point. The operator is about to lose the
+      // terminal they typed into, and a message that omits that reads as a hang.
+      log.log(
+        "This command is running inside the Codex app, so the restart was handed off to "
+        + `a detached helper (pid ${result.handoff?.helperPid ?? 0}). The app will quit and `
+        + `relaunch in a moment; this session will end with it. Outcome: ${result.handoff?.logPath ?? ""}`,
+      );
+      return result;
+    case "self_ancestry":
+      log.error(
+        "Refusing to restart the desktop app because this command is running inside it, "
+        + "and the restart could not be handed off to a detached helper. "
+        + "Run 'ocx sync --restart-codex' from a terminal outside the app instead.",
+      );
+      return result;
+    case "process_probe_failed":
+      // Distinct from `no_targets`: we could not look, which is not the same as looking and
+      // finding nothing. Saying "not running" here sent users away believing there was nothing
+      // to restart (#2557).
+      log.error(
+        "Could not enumerate Codex desktop processes, so the app was not restarted. "
+        + "Quit and relaunch the desktop app manually to refresh the model picker.",
+      );
+      return result;
+    case "no_targets":
+      log.log("Codex desktop app is not running; nothing to restart.");
+      return result;
+    case "targets_survived":
+      log.error(
+        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
+        + "Quit the desktop app manually to refresh the model picker.",
+      );
+      return result;
+    default:
+      if (result.relaunch === "started") {
+        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
+      }
+      return result;
+  }
+}
+

package/src/codex/app-server-processes.ts

@@ -17,8 +17,8 @@ import {
 import { readCodexCatalogPath } from "./catalog/parsing";
 
 export const STALE_CODEX_APP_SERVER_HINT =
-  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex). "
-  + "On Windows the desktop app itself may also need a full restart (ocx sync --restart-desktop-app).";
+  "If Codex still shows an older model list, run `ocx sync --restart-codex`: it restarts the long-lived app-server "
+  + "processes and fully restarts the Codex desktop app, whose model picker is what actually holds the stale list.";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -563,8 +563,8 @@ export function formatStaleCodexAppServerWarning(
   return (
     `WARNING: ${processes.length} Codex app-server process(es) still running (PID${processes.length === 1 ? "" : "s"}: ${pids}). `
     + "Disk catalog/cache were updated, but Codex may keep showing the old model list until those processes restart. "
-    + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to send SIGTERM only to matching app-server processes. "
-    + "On Windows the desktop app itself may also need a full restart (`ocx sync --restart-desktop-app`). "
+    + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to restart those processes and the Codex desktop app. "
+    + "Use `--restart-app-server-only` to leave the desktop app running. "
     + "Active turns may be interrupted."
   );
 }
@@ -1176,6 +1176,19 @@ export interface AfterCatalogWriteAppServerOptions {
   restart: boolean;
   log?: Pick<Console, "log" | "error"> | null;
   io?: CodexAppServerProcessIo;
+  /**
+   * Pids already covered by a desktop-app restart in this same command.
+   *
+   * The app-server is a CHILD of the Codex desktop app on every platform, so signalling
+   * it and then quitting the app interrupts the operator's in-flight turn twice in one
+   * command. Excluding the desktop tree leaves the quit to do that work once.
+   *
+   * Standalone app-servers - the npm wrapper pair, SSH bootstraps - are not members of
+   * that tree and are still signalled. An empty list means no exclusion, which is what a
+   * failed discovery or probe yields: a missed exclusion costs an extra interruption, a
+   * wrong one leaves a stale app-server serving a roster that no longer exists.
+   */
+  excludePids?: readonly number[];
 }
 
 export interface AfterCatalogWriteAppServerResult {
@@ -1189,7 +1202,9 @@ export interface AfterCatalogWriteAppServerResult {
 export function afterCatalogWriteHandleAppServers(
   options: AfterCatalogWriteAppServerOptions,
 ): AfterCatalogWriteAppServerResult {
-  const processes = listCodexAppServerProcesses(options.io);
+  const excluded = new Set(options.excludePids ?? []);
+  const processes = listCodexAppServerProcesses(options.io)
+    .filter(process => !excluded.has(process.pid));
   const hint = STALE_CODEX_APP_SERVER_HINT;
   if (processes.length === 0) {
     return { processes, warned: false, hint };

package/src/codex/app-server-restart-service.ts

@@ -28,11 +28,26 @@ import {
 import type { CodexAppServerProcessIo } from "./app-server-processes";
 import type {
   CodexAppServerStateResponse,
+  CodexDesktopRestartSummary,
   CodexRestartResponse,
 } from "../lib/codex-restart-contract";
 import { getServerListenPort } from "../server/lifecycle";
 
+async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
+  const { restartCodexDesktopApp } = await import("./desktop-app-restart");
+  const outcome = restartCodexDesktopApp({ allowHandoff: false });
+  return {
+    attempted: outcome.attempted,
+    stopped: outcome.stopped,
+    surviving: outcome.surviving,
+    relaunch: outcome.relaunch,
+    ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
+  };
+}
+
 export interface CodexRestartServiceIo {
+  /** Desktop-restart seam, so a route test cannot terminate the developer's own Codex. */
+  restartDesktopApp?: () => Promise<CodexDesktopRestartSummary>;
   /** Process-layer seam, forwarded to every app-server-processes call. */
   processIo?: CodexAppServerProcessIo;
   /** Catalog refresh seam. Resolves to whether a catalog or cache write happened. */
@@ -114,7 +129,18 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   (io.resetStateCache ?? resetCodexAppServerCatalogStateCache)();
   const before = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});
 
+  // Done here, before the early returns, because the model picker lives in the DESKTOP
+  // app: "no app-server is running" is not a reason to leave a stale roster on screen,
+  // and an operator who pressed restart still wants the app back on the current catalog.
+  //
+  // allowHandoff is false and that is deliberate. The handoff waits for the CALLING
+  // process to exit, and this runs inside a long-lived proxy that does not, so every
+  // handoff started here would sit out its window and fail after the operator had
+  // already been told it was handed off. An honest refusal beats that.
+  const desktop = await (io.restartDesktopApp ?? defaultRestartDesktopApp)();
+
   const nothingToDo = (): CodexRestartResponse => ({
+    desktopApp: desktop,
     success: true,
     stateBefore: before.state,
     synced,
@@ -174,6 +200,7 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
       surviving: [],
       failed: [],
       code: "nothing_running",
+      desktopApp: desktop,
     };
   }
 
@@ -207,8 +234,10 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   };
 
   const result = (io.restart ?? restartCodexAppServers)(targets, guardedProcessIo);
+
   const clean = result.surviving.length === 0 && result.failed.length === 0;
   return {
+    desktopApp: desktop,
     success: clean,
     stateBefore: before.state,
     synced,

package/src/codex/catalog/provider-fetch.ts

@@ -2321,7 +2321,7 @@ async function gatherRoutedModelsWithAuth(
   return models;
 }
 
-/** Bound a proven Codex-forward custom row without changing its stored configuration. */
+/** Bound a custom row whose model id has pinned native Codex metadata, without changing stored configuration. */
 function boundCustomNativeReasoning(
   model: CatalogModel,
   allowed: readonly string[],
@@ -2625,8 +2625,8 @@ async function gatherRoutedModelsUncached(
         : {}),
       // Explicit custom-row ladder wins over the inherited provider row below: the merge only
       // gap-fills, so a stored `[]` (explicit "no reasoning") or a declared ladder is kept
-      // instead of being replaced by that row's metadata. Only proven native aliases are
-      // bounded against their own capability source after the merge.
+      // instead of being replaced by that row's metadata. Capability-backed native model ids
+      // are bounded against their own pinned ladder after the merge, including gateways.
       ...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
       ...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
       ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
@@ -2679,8 +2679,16 @@ async function gatherRoutedModelsUncached(
       ...(base.codexToolMode === undefined && replaced.codexToolMode !== undefined ? { codexToolMode: replaced.codexToolMode } : {}),
       ...(base.capabilities === undefined && replaced.capabilities !== undefined ? { capabilities: replaced.capabilities } : {}),
     } : base;
-    const reasoningBounded = codexForwardNativeCapabilityAlias
-      ? boundCustomNativeReasoning(merged, nativeReasoningEfforts(cm.modelId), nativeAliasDefaultEffort)
+    // Catalog-advertised efforts are bounded whenever the model id is a pinned native
+    // slug. Desktop validates that id, so a gateway such as YYLJ/gpt-6-astra still cannot
+    // advertise none/minimal. Full native identity stays behind the alias predicate.
+    const nativeEffortSource = hasNativeOpenAiCapabilityMetadata(cm.modelId);
+    const reasoningBounded = nativeEffortSource
+      ? boundCustomNativeReasoning(
+        merged,
+        nativeReasoningEfforts(cm.modelId),
+        nativeAliasDefaultEffort ?? nativeDefaultReasoningEffort(cm.modelId),
+      )
       : merged;
     // Vision-sidecar coverage only: when the enriched provider's shared predicate matches
     // noVisionModels or text-without-image modelInputModalities, advertise image input so the

package/src/codex/catalog/sync.ts

@@ -49,7 +49,7 @@ import { codexAccountLogLabel, fallbackCodexAccountLogLabel } from "../account-l
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readCodexCatalogPathForHome, readConfiguredAutoReviewModel, readNativeBaseline } from "./parsing";
 import type { CatalogModel, MultiAgentMode, RawCatalog, RawEntry } from "./parsing";
-import { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, applyNativeVisibility, CODEX_NATIVE_ALIAS_CATALOG_KIND, desktopAllowlistSuppressedNativeSlugs, disabledNativeSlugs, isNativeAliasCatalogEntry, isUnsupportedOpenAiNativeSlug, NATIVE_OPENAI_MODELS, RETIRED_NATIVE_OPENAI_MODELS, nativeContextLimits, observedAccountBoundNativeEntries, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, shouldUpgradeToUpstreamEntry, SUPPORTED_NATIVE_OPENAI_SLUGS, upstreamNativeEntry, type NativeContextLimitsInput } from "./metadata";
+import { accountBoundNativeOpenAiSlugs, accountBoundNativeOpenAiSlugsBySelector, applyNativeVisibility, CODEX_NATIVE_ALIAS_CATALOG_KIND, desktopAllowlistSuppressedNativeSlugs, disabledNativeSlugs, hasNativeOpenAiCapabilityMetadata, isNativeAliasCatalogEntry, isUnsupportedOpenAiNativeSlug, NATIVE_OPENAI_MODELS, RETIRED_NATIVE_OPENAI_MODELS, nativeContextLimits, observedAccountBoundNativeEntries, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, shouldUpgradeToUpstreamEntry, SUPPORTED_NATIVE_OPENAI_SLUGS, upstreamNativeEntry, type NativeContextLimitsInput } from "./metadata";
 import {
   bundledCatalogCacheState,
   loadBundledCodexCatalog,
@@ -316,6 +316,13 @@ function routedDisplayName(slug: string, model?: CatalogModel, config?: Pick<Ocx
   return slug;
 }
 
+function preservePinnedNativeCustomReasoning(model?: CatalogModel): boolean {
+  return model !== undefined
+    && model.catalogKind === CODEX_CUSTOM_MODEL_CATALOG_KIND
+    && hasNativeOpenAiCapabilityMetadata(model.id)
+    && Array.isArray(model.reasoningEfforts);
+}
+
 /**
  * Cria uma entrada nativa ou roteada a partir do snapshot upstream, de um clone
  * do template ou de campos mínimos. Aplica os metadados e limites pertinentes
@@ -380,7 +387,9 @@ export function deriveEntry(
         e,
         model?.reasoningEfforts,
         model?.defaultReasoningEffort,
-        preserveExactReasoning || codexForwardNativeCapabilityAlias !== null,
+        preserveExactReasoning
+          || codexForwardNativeCapabilityAlias !== null
+          || preservePinnedNativeCustomReasoning(model),
       );
       // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
       // native tool/search/responses-lite contract while preserving the routed slug and wire id.
@@ -429,7 +438,7 @@ export function deriveEntry(
   };
   if (isRouted) {
     applyRoutedCodexToolMode(entry, model?.codexToolMode);
-    applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExactReasoning);
+    applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExactReasoning || preservePinnedNativeCustomReasoning(model));
   }
   else {
     applyReasoningLevels(entry, isGpt56NativeSlug(slug) ? undefined : ["low", "medium", "high", "xhigh"]);

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

@@ -0,0 +1,268 @@
+/**
+ * macOS adapter for the Codex desktop-app restart.
+ *
+ * Measured shape (devlog/_plan/260913_cross_platform_desktop_app_restart/001_platform_topology.md):
+ *
+ *   15901     1  /Applications/ChatGPT.app/Contents/MacOS/ChatGPT
+ *   16733 15901  /Applications/ChatGPT.app/Contents/Resources/codex ... app-server ...
+ *   15903     1  .../Contents/Frameworks/Codex Framework.framework/.../browser_crashpad_handler
+ *
+ * The bundle is named ChatGPT.app but its identifier is com.openai.codex, and the
+ * display name is shared with a different OpenAI product. Every identity decision
+ * here therefore keys on the identifier, never on the name.
+ */
+import { realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import {
+  isUnderRoot,
+  type DesktopAppAdapter,
+  type DesktopAppInstall,
+  type DesktopExec,
+  type DesktopProcess,
+} from "./types";
+
+const BUNDLE_ID = "com.openai.codex";
+const CONVENTIONAL_BUNDLE = "/Applications/ChatGPT.app";
+const SHELL_SUFFIX = "/Contents/MacOS/ChatGPT";
+
+/** Absolute system locations only. PATH is never consulted for any of these. */
+const PS = "/bin/ps";
+const OSASCRIPT = "/usr/bin/osascript";
+const OPEN = "/usr/bin/open";
+const MDFIND = "/usr/bin/mdfind";
+const PLIST_BUDDY = "/usr/libexec/PlistBuddy";
+
+const PROBE_TIMEOUT_MS = 10_000;
+const MAX_ANCESTRY_HOPS = 16;
+
+function shellPath(bundle: string): string {
+  return join(bundle, "Contents", "MacOS", "ChatGPT");
+}
+
+function readBundleIdentifier(exec: DesktopExec, bundle: string): string | null {
+  try {
+    return exec(PLIST_BUDDY, [
+      "-c", "Print :CFBundleIdentifier",
+      join(bundle, "Contents", "Info.plist"),
+    ], { timeout: PROBE_TIMEOUT_MS }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function confirmBundle(exec: DesktopExec, candidate: string): DesktopAppInstall | null {
+  if (!candidate) return null;
+  let resolved: string;
+  try {
+    // Resolved ONCE here so membership is a pure comparison against a trusted value.
+    // A prefix test against an unresolved path admits sibling directories such as
+    // /Applications/ChatGPT.app-evil/..., which the same user can create.
+    resolved = realpathSync(candidate);
+  } catch {
+    return null;
+  }
+  if (readBundleIdentifier(exec, resolved) !== BUNDLE_ID) return null;
+  return { id: BUNDLE_ID, root: resolved, relaunch: BUNDLE_ID };
+}
+
+interface PsSnapshot {
+  pid: number;
+  parentPid: number;
+  createdAt: string;
+  uid: number;
+  executable: string;
+}
+
+/**
+ * Column order matters. lstart is five whitespace-separated tokens, and the executable
+ * path itself contains spaces and parentheses on this app (Codex (Service).app), so
+ * everything after the uid is taken as the remainder of the line rather than split.
+ *
+ * comm as the FINAL -o column yields the full, untruncated executable path; this was
+ * checked against a 150+ character helper path rather than assumed. The 16-character
+ * truncation people expect belongs to ucomm.
+ */
+function parsePsLine(line: string): PsSnapshot | null {
+  const match = /^\s*(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\S+\s+\S+\s+\S+)\s+(\d+)\s+(.+)$/.exec(line);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  const parentPid = Number(match[2]);
+  const uid = Number(match[4]);
+  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parentPid) || !Number.isSafeInteger(uid)) {
+    return null;
+  }
+  return {
+    pid,
+    parentPid,
+    createdAt: (match[3] ?? "").trim(),
+    uid,
+    executable: (match[5] ?? "").trim(),
+  };
+}
+
+function readPsSnapshots(exec: DesktopExec): PsSnapshot[] | null {
+  let stdout: string;
+  try {
+    stdout = exec(PS, ["-Ao", "pid=,ppid=,lstart=,uid=,comm="], { timeout: PROBE_TIMEOUT_MS });
+  } catch {
+    // A probe that could not RUN is not evidence of absence.
+    return null;
+  }
+  const out: PsSnapshot[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    const parsed = parsePsLine(line);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+/**
+ * Prefer the bundle the RUNNING shell executes out of.
+ *
+ * Membership is path-scoped while the quit and the relaunch are bundle-id-scoped. If
+ * two bundles claim com.openai.codex, discovering by identifier alone could enumerate
+ * one installation and quit the other. Starting from the live process makes the thing
+ * we quit the same thing we counted.
+ */
+function discoverFromRunningShell(exec: DesktopExec): string | null {
+  for (const snapshot of readPsSnapshots(exec) ?? []) {
+    if (!snapshot.executable.endsWith(SHELL_SUFFIX)) continue;
+    return snapshot.executable.slice(0, -SHELL_SUFFIX.length);
+  }
+  return null;
+}
+
+function currentUid(): number | undefined {
+  try {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+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 setDarwinKillForTests(
+  next: ((pid: number, signal: NodeJS.Signals) => void) | null,
+): void {
+  killProcess = next ?? ((pid, signal) => { process.kill(pid, signal); });
+}
+
+export const darwinDesktopAppAdapter: DesktopAppAdapter = {
+  discover(exec): DesktopAppInstall | null {
+    const running = discoverFromRunningShell(exec);
+    if (running) {
+      const confirmed = confirmBundle(exec, running);
+      if (confirmed) return confirmed;
+    }
+    let spotlight = "";
+    try {
+      const query = "kMDItemCFBundleIdentifier == '" + BUNDLE_ID + "'";
+      spotlight = exec(MDFIND, [query], { timeout: PROBE_TIMEOUT_MS })
+        .split(/\r?\n/)
+        .map(entry => entry.trim())
+        .find(entry => entry.length > 0) ?? "";
+    } catch {
+      spotlight = "";
+    }
+    return confirmBundle(exec, spotlight) ?? confirmBundle(exec, CONVENTIONAL_BUNDLE);
+  },
+
+  listProcesses(exec, install): DesktopProcess[] | null {
+    const snapshots = readPsSnapshots(exec);
+    if (snapshots === null) return null;
+    const uid = currentUid();
+    // Without a uid there is no way to scope the result to this user, and reporting an
+    // empty list would tell the caller the app is not running (#2557's failure mode in a
+    // different disguise). This is a probe failure.
+    if (uid === undefined) return null;
+    const out: DesktopProcess[] = [];
+    for (const snapshot of snapshots) {
+      if (!isUnderRoot(snapshot.executable, install.root)) continue;
+      // Same user only.
+      if (snapshot.uid !== uid) continue;
+      out.push({
+        pid: snapshot.pid,
+        parentPid: snapshot.parentPid,
+        createdAt: snapshot.createdAt,
+        executable: snapshot.executable,
+      });
+    }
+    return out;
+  },
+
+  isShell(entry, install): boolean {
+    return entry.executable === shellPath(install.root);
+  },
+
+  ancestryPids(exec): 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(PS, ["-o", "ppid=", "-p", String(current)], { timeout: PROBE_TIMEOUT_MS });
+      } catch (error) {
+        // ps -p <pid> exits 1 with empty output when the pid does not exist, and
+        // execFileSync turns a non-zero exit into a throw. Without this branch the
+        // clean-end handling below is unreachable in production, every dead parent reads
+        // as unreadable, and the orphaned handoff helper refuses the one job it exists
+        // for. Hop 0 is this process, which always exists, so a failure there is real.
+        const status = (error as { status?: unknown } | null)?.status;
+        if (hop > 0 && status === 1) return chain;
+        // Anything else: could not look, so we cannot conclude we are outside the tree.
+        return [];
+      }
+      const trimmed = stdout.trim();
+      // Empty output means the pid has no live parent entry: a CLEAN end of chain, not
+      // a read failure. The detached handoff helper reaches exactly this state once its
+      // caller exits, and reading it as unreadable would make the helper refuse the one
+      // job it exists for.
+      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);
+      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" instead.
+    return [];
+  },
+
+  requestQuit(exec, install): void {
+    // The Apple event, so the app runs its own termination path. Delivery is
+    // synchronous; termination is not, which is why the ladder always waits and
+    // re-verifies identity afterwards.
+    exec(OSASCRIPT, ["-e", 'quit app id "' + install.id + '"'], { timeout: PROBE_TIMEOUT_MS });
+  },
+
+  forceStop(_exec, root): void {
+    killProcess(root.pid, "SIGKILL");
+  },
+
+  captureRelaunchContext(): Record<string, string> {
+    // LaunchServices supplies the session, so nothing needs carrying forward.
+    return {};
+  },
+
+  relaunch(exec, install): void {
+    // Deliberately without -g: the operator asked for a restart and expects the app in
+    // front of them. An unknown bundle id exits non-zero with
+    // LSCopyApplicationURLsForBundleIdentifier() failed, which the ladder turns into
+    // relaunch_failed rather than a silent no-op. Not -n either: a second instance is
+    // both unreliable to obtain and unwanted.
+    exec(OPEN, ["-b", install.relaunch], { timeout: PROBE_TIMEOUT_MS });
+  },
+};
+
+export const darwinDefaultExec: DesktopExec = (file, args, options) => execFileSync(file, [...args], {
+  encoding: "utf-8",
+  stdio: ["ignore", "pipe", "ignore"],
+  timeout: options?.timeout ?? PROBE_TIMEOUT_MS,
+});