@yansigit/opencodex 2.31.2 → 2.32.0

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

@@ -75,6 +75,7 @@ import { createAdmissionGate, ResourceAdmissionError, type AdmissionMetrics } fr
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, JAWCODE_CATALOG_AUGMENT_PROVIDERS, catalogModelSlug, shouldExposeRoutedModel } from "./parsing";
 import type { CatalogModel } from "./parsing";
+import { capsFromProvider, enrichCatalogModelMetadata, persistLiveModelMetadata, type LiveSnapshotRow } from "./model-metadata";
 import { disabledNativeSlugs, hasComboTargets, isNativeOpenAiCapabilityAliasModel, NATIVE_GPT56_MAX_INPUT_TOKENS, nativeContextLimits, nativeDefaultReasoningEffort, nativeInputModalities, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, nativeOpenAiSlugs, nativeParallelToolCalls, nativeReasoningEfforts } from "./metadata";
 import { deriveComboCatalogModel, normalizedOpenAiApiSignature, openAiApiCollisionWarnings, replaceLastComboCatalogOmissions, warnUncataloguedComboOnce } from "./aggregation";
 import type { ComboCatalogOmission } from "./aggregation";
@@ -662,9 +663,16 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
   const hintedWindow = discoveredWindow !== undefined
     ? (configuredCap !== undefined ? Math.min(discoveredWindow, configuredCap) : discoveredWindow)
     : (configuredCap ?? (providerCap !== undefined ? resolveUnknownRoutedContextWindow(providerCap) : undefined));
+  const capFilledMissingWindow = discoveredWindow === undefined && hintedWindow !== undefined;
   const hinted = {
     ...modelWithoutServiceTier,
     ...(hintedWindow !== undefined ? { contextWindow: hintedWindow } : {}),
+    ...(discoveredWindow !== undefined
+      ? { detectedContextWindow: model.detectedContextWindow ?? discoveredWindow }
+      : {}),
+    ...(capFilledMissingWindow && !model.metadataSource
+      ? { metadataSource: "config_fallback" as const }
+      : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
     ...(configuredMaxInput !== undefined
@@ -689,10 +697,26 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
     ...(prov.codexToolMode !== undefined ? { codexToolMode: prov.codexToolMode } : {}),
   };
   const capped = applyProviderContextCap(hinted.contextWindow, providerCap);
+  const detectedContextWindow = hinted.detectedContextWindow
+    ?? discoveredWindow;
+  const contextCapped = providerCap !== undefined
+    && typeof capped === "number"
+    && (
+      capped !== hinted.contextWindow
+      || (typeof detectedContextWindow === "number" && detectedContextWindow > capped)
+      || hinted.contextCapped === true
+    );
   if (providerCap !== undefined && capped !== hinted.contextWindow) {
-    return { ...hinted, contextWindow: capped, contextCap: providerCap, contextCapped: true };
+    return {
+      ...hinted,
+      contextWindow: capped,
+      contextCap: providerCap,
+      contextCapped,
+    };
   }
-  return providerCap !== undefined ? { ...hinted, contextCap: providerCap, contextCapped: false } : hinted;
+  return providerCap !== undefined
+    ? { ...hinted, contextCap: providerCap, contextCapped }
+    : hinted;
 }
 
 export function catalogHintsFromProviderConfig(name: string, prov: OcxProviderConfig, id: string, contextCap?: number): Partial<CatalogModel> {
@@ -1043,15 +1067,35 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
       item.context_size,
       item.max_model_len,
       item.max_context_length,
+      item.context_window,
+      item.max_context_window,
+      item.max_context_size,
+      item.n_ctx,
+      plainRecord(item.top_provider)?.max_context_length,
+      plainRecord(metadata?.top_provider)?.max_context_length,
       // llama.cpp reports the served context under `meta`: `n_ctx` is what the
       // server was actually started with, `n_ctx_train` the model's trained
       // maximum. Prefer the served value — routing must not promise a window the
       // running server will refuse. Both come LAST so no provider already
       // supplying a recognized field changes behavior (#1797).
       plainRecord(item.meta)?.n_ctx,
+      item.default_context_size,
       plainRecord(item.meta)?.n_ctx_train,
     );
-  const maxInputTokens = positiveSafeInteger(limits?.max_input_tokens, item.max_input_tokens);
+  const maxInputTokens = positiveSafeInteger(
+    limits?.max_input_tokens,
+    item.max_input_tokens,
+    item.max_input_length,
+    item.max_prompt_tokens,
+  );
+  // Output ceilings only. A top-level `max_tokens` is ambiguous (some catalogs
+  // use it as context) and generated jawcode `maxTokens` is output-only — never
+  // treat either as a context window.
+  const maxOutputTokens = positiveSafeInteger(
+    limits?.max_output_tokens,
+    item.max_output_tokens,
+    limits?.max_tokens,
+  );
   // Some OpenAI-compatible catalogs expose the selectable ladder under
   // `reasoning_parameters.efforts` instead of the older `reasoning_efforts` key.
   // Treat both as model metadata: otherwise a valid upstream capability disappears
@@ -1079,6 +1123,7 @@ export function catalogHintsFromModelsApiItem(providerName: string, item: Provid
   return {
     ...(contextWindow && contextWindow > 0 ? { contextWindow } : {}),
     ...(maxInputTokens && maxInputTokens > 0 ? { maxInputTokens } : {}),
+    ...(maxOutputTokens && maxOutputTokens > 0 ? { maxOutputTokens } : {}),
     ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
     ...(inputModalities ? { inputModalities } : {}),
     ...(capabilities ? { capabilities } : {}),
@@ -1283,9 +1328,13 @@ async function fetchProviderModelsWithAuth(
     const stale = getStaleCached(name);
     return observed(
       withConfiguredRetention(
-        stale
+        (stale
           ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
-          : failedDiscoveryConfigured,
+          : failedDiscoveryConfigured
+        ).map(model => enrichCatalogModelMetadata(model, {
+          liveFresh: false,
+          caps: capsFromProvider(prov, model.id, contextCap),
+        })),
       ),
       "degraded",
     );
@@ -1312,12 +1361,14 @@ async function fetchProviderModelsWithAuth(
     markModelsFetchFailure(name);
     markProviderDiscoveryFailed(name, failure);
     const stale = getStaleCached(name);
+    const fallbackModels = stale
+      ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
+      : failedDiscoveryConfigured;
     return {
-      models: withConfiguredRetention(
-        stale
-          ? withVertexDefaultSeed(applyConfigHintsToCachedModels(name, prov, stale, contextCap))
-          : failedDiscoveryConfigured,
-      ),
+      models: withConfiguredRetention(fallbackModels.map(model => enrichCatalogModelMetadata(model, {
+        liveFresh: false,
+        caps: capsFromProvider(prov, model.id, contextCap),
+      }))),
       fallback: stale ? "stale" : "configured",
       shouldLog,
     };
@@ -1384,19 +1435,40 @@ async function fetchProviderModelsWithAuth(
       return observed(models, "degraded");
     }
     if (antigravity) {
-      const live = antigravity.map(model => applyProviderConfigHints(name, prov, {
-        id: model.id,
-        provider: name,
-        // CCA only exposes a numeric thinking budget. Until the adapter owns an exact Codex
-        // effort-to-wire mapping for a newly discovered model, do not advertise a false ladder.
-        reasoningEfforts: [],
-        ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
-        ...(model.inputModalities ? { inputModalities: model.inputModalities } : {}),
-      }, contextCap));
+      const observedAt = new Date().toISOString();
+      const snapshotRows: LiveSnapshotRow[] = [];
+      const live = antigravity.map(model => {
+        const hints = {
+          // CCA only exposes a numeric thinking budget. Until the adapter owns an exact Codex
+          // effort-to-wire mapping for a newly discovered model, do not advertise a false ladder.
+          reasoningEfforts: [] as string[],
+          ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
+          ...(model.inputModalities ? { inputModalities: model.inputModalities } : {}),
+        };
+        if (model.contextWindow || model.inputModalities) {
+          snapshotRows.push({
+            id: model.id,
+            ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
+            ...(model.inputModalities ? { inputModalities: model.inputModalities } : {}),
+            observedAt,
+          });
+        }
+        const enriched = enrichCatalogModelMetadata({
+          id: model.id,
+          provider: name,
+          ...hints,
+          ...(model.contextWindow ? { metadataSource: "live" as const, metadataObservedAt: observedAt } : {}),
+        }, {
+          liveFresh: true,
+          caps: capsFromProvider(prov, model.id, contextCap),
+        });
+        return applyProviderConfigHints(name, prov, enriched, contextCap);
+      });
       const forCache = withConfiguredRetention(live, { retainComboTargets: false });
       if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
         return observed(withConfiguredRetention(configured), "degraded");
       }
+      persistLiveModelMetadata(name, snapshotRows, { writerGeneration: cacheGeneration, observedAt });
       registerAntigravityDiscoveredWireModels(prov.baseUrl, antigravity, {
         provider: name,
         cacheGeneration,
@@ -1421,22 +1493,30 @@ async function fetchProviderModelsWithAuth(
       return observed(models, "degraded");
     }
     const items = extracted.items;
+    const observedAt = new Date().toISOString();
+    const snapshotRows: LiveSnapshotRow[] = [];
     const live = items.map(m => {
       const ownedBy = boundedOwnedBy(m.owned_by);
-      return applyProviderConfigHints(name, prov, {
+      const hints = catalogHintsFromModelsApiItem(name, m);
+      const discovered = Boolean(hints.contextWindow || hints.maxInputTokens || hints.maxOutputTokens
+        || hints.inputModalities || hints.capabilities || hints.reasoningEfforts);
+      if (discovered) {
+        snapshotRows.push({ id: m.id, ...hints, observedAt });
+      }
+      const enriched = enrichCatalogModelMetadata({
         id: m.id,
         provider: name,
         ...(ownedBy ? { owned_by: ownedBy } : {}),
-        ...catalogHintsFromModelsApiItem(name, m),
-      }, contextCap);
+        ...hints,
+        ...(discovered ? { metadataSource: "live" as const, metadataObservedAt: observedAt } : {}),
+      }, {
+        liveFresh: true,
+        caps: capsFromProvider(prov, m.id, contextCap),
+      });
+      return applyProviderConfigHints(name, prov, enriched, contextCap);
     })
       .filter(m => shouldExposeProviderModel(name, m.id));
-    // Capture the count BEFORE the alias/configured augmentation below pushes extra rows into
-    // `live`; otherwise configured entries would be reported as discovered ones.
     const liveModelCount = live.length;
-    // Dated-release aliases + configured retention (compat allow-list, combo targets,
-    // Vertex default). Cache without combo retention so a later gather re-applies the
-    // current capture's retain set on read (warm-cache OCX-111 / #1308).
     const forCache = withConfiguredRetention(live, { retainComboTargets: false });
     const returned = withConfiguredRetention(forCache, { warnDrops: true });
     const droppedConfiguredIds = configured
@@ -1450,6 +1530,7 @@ async function fetchProviderModelsWithAuth(
     if (!setCached(name, forCache, Date.now(), cacheGeneration)) {
       return observed(withConfiguredRetention(configured), "degraded");
     }
+    persistLiveModelMetadata(name, snapshotRows, { writerGeneration: cacheGeneration, observedAt });
     markProviderDiscoveryOk(name, liveModelCount);
     return observed(returned, "authoritative");
   } catch (error) {
@@ -2035,7 +2116,14 @@ export function augmentRoutedModelsWithMetadata(
   providers?: Record<string, OcxProviderConfig>,
   caps?: Pick<OcxConfig, "providerContextCaps">,
 ): CatalogModel[] {
-  const out = [...models];
+  const out = models.map((model) => {
+    const provider = providers?.[model.provider];
+    const contextCap = caps ? providerContextCap(caps, model.provider) : undefined;
+    return enrichCatalogModelMetadata(model, {
+      liveFresh: model.metadataSource === "live" && model.metadataStale !== true,
+      caps: capsFromProvider(provider, model.id, contextCap),
+    });
+  });
   const seen = new Set(out.map(m => `${m.provider}/${m.id}`));
   for (const provider of providerNames) {
     if (!JAWCODE_CATALOG_AUGMENT_PROVIDERS.has(provider)) continue;
@@ -2054,10 +2142,13 @@ export function augmentRoutedModelsWithMetadata(
         ...(typeof meta.contextWindow === "number" && meta.contextWindow > 0 ? { contextWindow: meta.contextWindow } : {}),
         ...(Array.isArray(meta.input) && meta.input.length > 0 ? { inputModalities: [...meta.input] } : {}),
       };
-      out.push({
-        ...model,
-        ...(providers?.[provider] ? applyProviderConfigHints(provider, providers[provider], model, contextCap) : {}),
-      });
+      const hinted = providers?.[provider]
+        ? applyProviderConfigHints(provider, providers[provider], model, contextCap)
+        : model;
+      out.push(enrichCatalogModelMetadata(hinted, {
+        liveFresh: false,
+        caps: capsFromProvider(providers?.[provider], meta.id, contextCap),
+      }));
     }
   }
   return out;

package/src/codex/catalog/sync.ts

@@ -41,7 +41,7 @@ import {
 } from "../model-entitlements";
 
 
-import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readNativeBaseline } from "./parsing";
+import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readCodexCatalogPathForHome, 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, nativeContextLimits, observedAccountBoundNativeEntries, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi, shouldUpgradeToUpstreamEntry, SUPPORTED_NATIVE_OPENAI_SLUGS, upstreamNativeEntry, type NativeContextLimitsInput } from "./metadata";
 import {
@@ -1832,11 +1832,12 @@ export function invalidateCodexModelsCacheWithPermit(
     // The catalog-only sync override applies here too so an explicit refresh
     // keeps the cache consistent with the catalog it just wrote.
     if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return false;
-    const catalogPath = readCodexCatalogPath();
+    const catalogPath = readCodexCatalogPathForHome(owningCodexHome);
+    const cachePath = join(owningCodexHome, "models_cache.json");
     if (!existsSync(catalogPath)) return false;
     const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
     const models = catalog.models ?? catalog;
-    const currentCache = readCatalog(activeCodexModelsCachePath());
+    const currentCache = readCatalog(cachePath);
     const existingSlugs = new Set(models.flatMap((entry: RawEntry) =>
       typeof entry.slug === "string" ? [entry.slug] : []));
     const currentConfig = loadConfig();
@@ -1864,7 +1865,7 @@ export function invalidateCodexModelsCacheWithPermit(
       models: [...models, ...observedAccountModels],
     };
     replaceCodexModelsCache(permit, owningCodexHome, {
-      path: activeCodexModelsCachePath(),
+      path: cachePath,
       content: `${JSON.stringify(wrapper, null, 2)}\n`,
     });
     return true;

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

@@ -0,0 +1,342 @@
+/**
+ * Full restart of the Codex desktop app (the Electron shell), Windows only.
+ *
+ * `--restart-codex` deliberately signals only `codex app-server` /
+ * `codex-code-mode-host` processes: `isCodexAppServerCommandLine` requires a
+ * `codex` executable token, so the shell that owns the model picker is never a
+ * match. On macOS that is enough, because the respawned app-server re-emits
+ * `codex-app-server-initialized` and the renderer drops its cached
+ * `model/list`. On Windows MSIX it is not: externally terminating the child
+ * does not reliably re-emit that event in the surviving shell, so the picker
+ * keeps showing the old catalog until the app itself is restarted (#2292).
+ *
+ * This is therefore a SEPARATE opt-in flag rather than a widening of
+ * `--restart-codex`. Quitting the desktop app ends live conversations, which is
+ * a different consent from restarting a background helper, and the CLI contract
+ * for `--restart-codex` promises the narrow behavior.
+ *
+ * Everything here fails CLOSED: if the package cannot be identified, if a
+ * target is part of our own ancestry, or if any target survives termination,
+ * nothing is relaunched and the caller is told to restart manually. A stale
+ * picker is a much smaller problem than a wrongly killed process.
+ */
+import { resolveTrustedWindowsPowerShellExe, resolveTrustedWindowsTaskkillExe } from "../lib/windows-elevation";
+import { execFileSync } from "node:child_process";
+
+/** Bounded subprocess options. A hung Appx/CIM probe must never wedge `ocx sync`. */
+export interface DesktopAppExecOptions {
+  timeout?: number;
+  windowsHide?: boolean;
+}
+
+export interface DesktopAppRestartIo {
+  platform?: NodeJS.Platform;
+  /** Returns stdout. Options are part of the seam so the timeout is testable. */
+  execFile?: (file: string, args: readonly string[], options?: DesktopAppExecOptions) => string;
+  /** Process ancestry of the current process, innermost first. Used for the self-kill guard. */
+  ancestryPids?: () => number[];
+  isAlive?: (pid: number) => boolean;
+  sleep?: (ms: number) => void;
+  now?: () => number;
+}
+
+export type DesktopAppRestartReason =
+  | "windows_only"
+  | "package_discovery_failed"
+  | "no_targets"
+  | "self_ancestry"
+  | "targets_survived";
+
+export interface DesktopAppRestartResult {
+  attempted: boolean;
+  stopped: number[];
+  surviving: number[];
+  relaunch: "started" | "skipped";
+  reason?: DesktopAppRestartReason;
+}
+
+/** How long a graceful close is given before the forced pass. */
+const GRACEFUL_EXIT_TIMEOUT_MS = 15_000;
+/** How long a forced kill is given before the target counts as surviving. */
+const FORCED_EXIT_TIMEOUT_MS = 5_000;
+/** Every probe is bounded; PowerShell module loading is the slow part. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+interface DesktopPackage {
+  family: string;
+  installLocation: string;
+  aumid: string;
+}
+
+/**
+ * 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: NonNullable<DesktopAppRestartIo["execFile"]>): DesktopPackage | 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], {
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+  } 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 { family, installLocation, aumid };
+}
+
+interface DesktopProcess {
+  pid: number;
+  parentPid: number;
+  /** Win32_Process CreationDate. Guards against PID reuse across the wait window. */
+  createdAt: string;
+}
+
+/**
+ * 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.
+ */
+function listPackageProcesses(
+  exec: NonNullable<DesktopAppRestartIo["execFile"]>,
+  installLocation: string,
+): DesktopProcess[] {
+  const literal = installLocation.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'))\"",
+    "      }",
+    "    }",
+    "  }",
+  ].join(" ");
+  let stdout: string;
+  try {
+    stdout = exec(resolveTrustedWindowsPowerShellExe(), ["-NoProfile", "-NonInteractive", "-Command", script], {
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+  } catch {
+    return [];
+  }
+  const processes: DesktopProcess[] = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const createdAt = match[3]!;
+    if (Number.isSafeInteger(pid) && Number.isSafeInteger(parentPid)) {
+      processes.push({ pid, parentPid, createdAt });
+    }
+  }
+  return processes;
+}
+
+/**
+ * True when the PID still names the same process we verified. Between listing
+ * and signalling there is a graceful-close window, and a `taskkill /T /F` on a
+ * recycled PID would tear down an unrelated process tree.
+ */
+function stillSameProcess(
+  exec: NonNullable<DesktopAppRestartIo["execFile"]>,
+  installLocation: string,
+  target: DesktopProcess,
+): boolean {
+  const current = listPackageProcesses(exec, installLocation)
+    .find(p => p.pid === target.pid);
+  return current !== undefined && current.createdAt === target.createdAt;
+}
+
+/** Roots are the package processes whose parent is not itself in the package tree. */
+function rootProcesses(processes: readonly DesktopProcess[]): DesktopProcess[] {
+  const inTree = new Set(processes.map(p => p.pid));
+  return processes.filter(p => !inTree.has(p.parentPid));
+}
+
+/**
+ * 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: NonNullable<DesktopAppRestartIo["execFile"]>): number[] {
+  const chain: number[] = [process.pid];
+  let current = process.pid;
+  for (let hop = 0; hop < 16; hop++) {
+    let stdout: string;
+    try {
+      stdout = exec(resolveTrustedWindowsPowerShellExe(), [
+        "-NoProfile", "-NonInteractive", "-Command",
+        `$ErrorActionPreference='SilentlyContinue'; (Get-CimInstance Win32_Process -Filter "ProcessId=${current}").ParentProcessId`,
+      ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    } catch {
+      // An unreadable chain must not be read as "not our ancestor".
+      return [];
+    }
+    const parent = Number(stdout.trim());
+    if (!Number.isSafeInteger(parent) || parent <= 0 || chain.includes(parent)) break;
+    chain.push(parent);
+    current = parent;
+  }
+  return chain;
+}
+
+function defaultExecFile(file: string, args: readonly string[], options?: DesktopAppExecOptions): string {
+  return execFileSync(file, [...args], {
+    encoding: "utf-8",
+    timeout: options?.timeout ?? PROBE_TIMEOUT_MS,
+    windowsHide: options?.windowsHide ?? true,
+  });
+}
+
+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);
+}
+
+function waitForExit(
+  pid: number,
+  timeoutMs: number,
+  isAlive: (pid: number) => boolean,
+  sleep: (ms: number) => void,
+  now: () => number,
+): boolean {
+  const deadline = now() + timeoutMs;
+  while (now() < deadline) {
+    if (!isAlive(pid)) return true;
+    sleep(250);
+  }
+  return !isAlive(pid);
+}
+
+/**
+ * Stop every package-tree root gracefully, force the stragglers, then relaunch
+ * through the discovered AUMID. Returns without relaunching if anything
+ * survived, because launching a second shell beside a stuck one is worse than
+ * leaving the user to restart it.
+ */
+export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult {
+  const platform = io.platform ?? process.platform;
+  const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({
+    attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason,
+  });
+  if (platform !== "win32") return skipped("windows_only");
+
+  const exec = io.execFile ?? defaultExecFile;
+  const pkg = discoverPackage(exec);
+  if (!pkg) return skipped("package_discovery_failed");
+
+  const processes = listPackageProcesses(exec, pkg.installLocation);
+  const roots = rootProcesses(processes);
+  if (roots.length === 0) return skipped("no_targets");
+
+  const ancestryPids = io.ancestryPids ? io.ancestryPids() : windowsAncestryPids(exec);
+  if (ancestryPids.length === 0) {
+    // Fail closed: an unreadable ancestry chain cannot prove we are outside the
+    // tree we are about to terminate.
+    return skipped("self_ancestry");
+  }
+  const ancestry = new Set(ancestryPids);
+  if (processes.some(p => ancestry.has(p.pid))) {
+    // Terminating our own tree would kill this command mid-flight and leave the
+    // user with neither a restarted app nor an explanation.
+    return skipped("self_ancestry");
+  }
+
+  const isAlive = io.isAlive ?? defaultIsAlive;
+  const sleep = io.sleep ?? defaultSleep;
+  const now = io.now ?? (() => Date.now());
+  const stopped: number[] = [];
+  const surviving: number[] = [];
+
+  for (const root of roots) {
+    const pid = root.pid;
+    // Re-verify immediately before the graceful close: the listing is already
+    // one probe old.
+    if (!stillSameProcess(exec, pkg.installLocation, root)) {
+      stopped.push(pid);
+      continue;
+    }
+    try {
+      exec(resolveTrustedWindowsPowerShellExe(), [
+        "-NoProfile", "-NonInteractive", "-Command",
+        `$p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue; if ($p) { [void]$p.CloseMainWindow() }`,
+      ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    } catch {
+      /* a refused graceful close still gets the forced pass below */
+    }
+    if (waitForExit(pid, GRACEFUL_EXIT_TIMEOUT_MS, isAlive, sleep, now)) {
+      stopped.push(pid);
+      continue;
+    }
+    // The wait window is long enough for Windows to recycle a PID, and the next
+    // step is `/T /F` against a whole tree. Confirm the PID is still the process
+    // we verified, or leave it alone.
+    if (!stillSameProcess(exec, pkg.installLocation, root)) {
+      stopped.push(pid);
+      continue;
+    }
+    try {
+      exec(resolveTrustedWindowsTaskkillExe(), ["/PID", String(pid), "/T", "/F"], {
+        timeout: PROBE_TIMEOUT_MS, windowsHide: true,
+      });
+    } catch {
+      /* fall through to the liveness check: the process state decides, not the exit code */
+    }
+    if (waitForExit(pid, FORCED_EXIT_TIMEOUT_MS, isAlive, sleep, now)) stopped.push(pid);
+    else surviving.push(pid);
+  }
+
+  if (surviving.length > 0) {
+    return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" };
+  }
+
+  try {
+    exec(resolveTrustedWindowsPowerShellExe(), [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Start-Process 'shell:AppsFolder\\${pkg.aumid}'`,
+    ], { timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+  } catch {
+    return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" };
+  }
+  return { attempted: true, stopped, surviving, relaunch: "started" };
+}