@bitkyc08/opencodex 2.31.0 → 2.32.0

package/src/cli/usage-report.ts

@@ -0,0 +1,134 @@
+/**
+ * Human rendering for `ocx usage`.
+ *
+ * Kept out of `observe.ts` and away from the shared `summaryLines()` helper on
+ * purpose. `summaryLines()` is a generic depth-1 flattener shared with
+ * storage/memory/debug/claude-inbound/injection; it renders any array as
+ * "N item(s)", which is why every per-model and per-provider cost the server
+ * computes used to vanish before reaching the terminal. Deepening it would
+ * change five unrelated commands.
+ *
+ * Formatting follows the existing CLI house style: dynamic `padEnd` columns
+ * (as in `formatAccountTable`), plain text, no ANSI colour.
+ */
+
+interface CostRow {
+  provider: string;
+  model?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+}
+
+interface UsageReportInput {
+  range?: string;
+  surface?: string;
+  since?: number | null;
+  summary?: {
+    requests?: number;
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCostUsd?: number;
+    unpricedRequests?: number;
+    unmeteredRequests?: number;
+  };
+  models?: CostRow[];
+  providers?: CostRow[];
+  days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
+  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+}
+
+const MAX_MODEL_ROWS = 10;
+
+function count(value: number | undefined): string {
+  return (value ?? 0).toLocaleString("en-US");
+}
+
+/**
+ * Matches the dashboard's `~$` with four fraction digits. Estimates below a
+ * hundredth of a cent still read as a number rather than collapsing to $0.00,
+ * which matters when a single request is being inspected.
+ */
+function usd(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+  return `~$${value.toFixed(4)}`;
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+  const line = (cols: string[]): string => cols.map((c, i) => (c ?? "").padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)];
+}
+
+function describeScope(data: UsageReportInput): string {
+  const parts = [`Usage — ${data.range ?? "?"}`];
+  if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
+  if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.model) parts.push(`model=${data.filter.model}`);
+  return parts.join(", ");
+}
+
+export function formatUsageReport(data: UsageReportInput): string[] {
+  const summary = data.summary ?? {};
+  const lines: string[] = [describeScope(data), ""];
+
+  if (data.filter && !data.filter.matched) {
+    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+      .filter(Boolean).join(" and ");
+    lines.push(`No usage recorded for ${what} in this range.`);
+    lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
+    return lines;
+  }
+
+  const tokenSplit = [
+    summary.inputTokens !== undefined ? `in ${count(summary.inputTokens)}` : null,
+    summary.outputTokens !== undefined ? `out ${count(summary.outputTokens)}` : null,
+    summary.cachedInputTokens ? `cached ${count(summary.cachedInputTokens)}` : null,
+  ].filter(Boolean).join(" / ");
+
+  lines.push(`Requests   ${count(summary.requests)}`);
+  lines.push(`Tokens     ${count(summary.totalTokens)}${tokenSplit ? `  (${tokenSplit})` : ""}`);
+  lines.push(`Est. cost  ${usd(summary.estimatedCostUsd)}    API list-price equivalent (this range)`);
+
+  const unpriced = summary.unpricedRequests ?? 0;
+  const unmetered = summary.unmeteredRequests ?? 0;
+  if (unpriced > 0 || unmetered > 0) {
+    // Spelled out because a $0 total is ambiguous otherwise: it can mean "no
+    // spend" or "no price row matched", and those are very different answers.
+    lines.push(`           ${count(unpriced)} unpriced, ${count(unmetered)} unmetered excluded from ~$`);
+  }
+
+  const providers = (data.providers ?? []).filter(row => row.requests > 0);
+  if (providers.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      providers.map(row => [row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+  }
+
+  const models = (data.models ?? []).filter(row => row.requests > 0);
+  if (models.length > 0) {
+    lines.push("");
+    const shown = models.slice(0, MAX_MODEL_ROWS);
+    lines.push(...table(
+      ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+    if (models.length > shown.length) {
+      lines.push(`... ${models.length - shown.length} more (use --json)`);
+    }
+  }
+
+  if (data.filter?.comboOverlap) {
+    lines.push("");
+    lines.push("Some requests ran as combos, so per-model request counts can overlap. Cost does not.");
+  }
+
+  lines.push("");
+  lines.push("Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}

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

@@ -17,7 +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).";
+  "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).";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -505,6 +506,7 @@ export function formatStaleCodexAppServerWarning(
     `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`). "
     + "Active turns may be interrupted."
   );
 }

package/src/codex/catalog/parsing.ts

@@ -149,6 +149,9 @@ export const JAWCODE_CATALOG_AUGMENT_PROVIDERS = new Set(["opencode-go", "deepse
 export const ROUTED_MODEL_COMPATIBILITY_EXCLUSIONS = new Set([
   // Issue #82: Zen Go /models advertises HY3, but Console Go rejects it as outside the lite list.
   "opencode-go/hy3-preview",
+  // Issue #2330: OpenCode Go models absent from current documentation or returning terminal HTTP 400 errors.
+  "opencode-go/mimo-v2-omni",
+  "opencode-go/mimo-v2-pro",
 ]);
 
 export function isRoutedModelCompatibilityExcluded(slug: string): boolean {
@@ -191,6 +194,8 @@ export function shouldExposeRoutedModel(model: CatalogModel): boolean {
 }
 
 export function readCodexCatalogPath(): string {
+  const home = activeCodexHome();
+  if (home) return readCodexCatalogPathForHome(home);
   try {
     const configPath = activeCodexConfigPath();
     if (existsSync(configPath)) {
@@ -202,6 +207,19 @@ export function readCodexCatalogPath(): string {
   return activeDefaultCatalogPath();
 }
 
+/** Resolve the configured catalog without consulting ambient CODEX_HOME again. */
+export function readCodexCatalogPathForHome(codexHome: string): string {
+  try {
+    const configPath = join(codexHome, "config.toml");
+    if (existsSync(configPath)) {
+      const toml = readFileSync(configPath, "utf-8");
+      const path = readRootTomlString(toml, "model_catalog_json");
+      if (path) return resolve(codexHome, path);
+    }
+  } catch { /* ignore */ }
+  return join(codexHome, "opencodex-catalog.json");
+}
+
 export function parseCatalogJson(raw: string): RawCatalog | null {
   try {
     const cat = JSON.parse(raw);

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" };
+}

package/src/codex/history-job.ts

@@ -109,7 +109,8 @@ export type CodexHistoryJobOutcome =
   | { readonly kind: "skipped" }
   | { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
   | { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
-      readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason };
+      readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason;
+      readonly rows?: number; readonly files?: number };
 
 /**
  * Derive the durable history operation from admitted intent.
@@ -174,7 +175,14 @@ function isPlausibleWorkerResult(
         || message.reason === "desired_disabled" || message.reason === "desired_enabled";
     case "error":
       return typeof message.message === "string"
-        && (message.reason === undefined || message.reason === "busy" || message.reason === "permission");
+        && (message.rows === undefined || (Number.isSafeInteger(message.rows) && Number(message.rows) >= 0))
+        && (message.files === undefined || (Number.isSafeInteger(message.files) && Number(message.files) >= 0))
+        && ((message.rows === undefined && message.files === undefined)
+          || (message.rows !== undefined && message.files !== undefined))
+        && (message.reason === undefined
+          || message.reason === "busy"
+          || message.reason === "permission"
+          || message.reason === "integrity");
     default:
       return false;
   }
@@ -224,6 +232,7 @@ export function describeHistoryJobFailure(
     : surface === "recover-legacy"
       ? "the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command."
       : "the Codex app appears to be holding the history database. Close Codex and run `ocx restore` again.";
+  const busyStateText = "Codex history state is busy (database, backup manifest, or rollout file); this is not enough evidence to blame the Codex app. It is retried automatically while the proxy runs; run 'ocx doctor' before forcing another attempt.";
   if (outcome.kind === "blocked") {
     if (outcome.reason === "busy") return busyText;
     switch (outcome.reason) {
@@ -237,10 +246,22 @@ export function describeHistoryJobFailure(
         return "Codex integration is enabled, so the history operation was skipped.";
     }
   }
-  if (outcome.historyFailureReason === "busy") return busyText;
+  const partiallyChanged = (outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0;
+  if (partiallyChanged && outcome.historyFailureReason === "busy") {
+    return "Codex history metadata changed but did not converge because manifest finalization remained busy; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
+  }
+  if (partiallyChanged && outcome.historyFailureReason === "permission") {
+    return "Codex history metadata changed but did not converge because permission was denied while finalizing the manifest; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
+  }
+  if (outcome.historyFailureReason === "busy") return busyStateText;
   if (outcome.historyFailureReason === "permission") {
     return "permission was denied while writing Codex history; this is not a Codex app lock. Run 'ocx doctor'.";
   }
+  if (outcome.historyFailureReason === "integrity") {
+    return partiallyChanged
+      ? "the history backup or its restore target changed after a partial restore; the manifest was retained for review and safe retry. Run 'ocx doctor'."
+      : "the history backup or its restore target failed integrity checks; no unverified provider metadata was applied. Run 'ocx doctor'.";
+  }
   switch (outcome.reason) {
     case "worker-error":
       return `the history worker failed (${outcome.message}). Run 'ocx doctor'.`;
@@ -277,6 +298,9 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
       reason: "worker-error",
       message: redactWorkerMessage(result.message),
       ...(result.reason ? { historyFailureReason: result.reason } : {}),
+      ...(result.rows !== undefined && result.files !== undefined
+        ? { rows: result.rows, files: result.files }
+        : {}),
     };
   }
   return result.outcome === "skipped"
@@ -284,6 +308,11 @@ function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutco
     : { kind: "converged", rows: result.rows, files: result.files, ...(result.proof ? { proof: result.proof } : {}) };
 }
 
+/** Test seam for the parent-side Worker result classification contract. */
+export function classifyWorkerResultForTests(result: HistoryWorkerResult): CodexHistoryJobOutcome {
+  return classifyWorkerResult(result);
+}
+
 /**
  * Run one history unit in a Worker and join it before returning.
  *