@bitkyc08/opencodex 2.81.0 → 2.82.0

package/src/cli/dispatch.ts

@@ -37,6 +37,8 @@ import { parseStopApproval, type StopApproval } from "./stop-approval";
 import type { ResolveArgs } from "./resolve";
 import type { ClientConnectionState } from "../client/state";
 import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { desktopStopNotice } from "./desktop-runtime-guidance";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -51,6 +53,7 @@ export interface CliDispatchDeps {
   spawnDetached: (argv: readonly string[]) => void;
   handleStart: () => Promise<void>;
   handleStop: (approval?: StopApproval) => Promise<StopOutcome>;
+  inspectDesktopSupervision?: typeof inspectDesktopSupervision;
   handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
   handleResolve: (args: ResolveArgs) => Promise<number>;
   handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
@@ -112,6 +115,8 @@ const commandRunners: Record<string, CommandRunner> = {
     // re-start the proxy immediately, so warning there would contradict the next line.
     const warning = "⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
     if (!parsed.json) {
+      const notice = desktopStopNotice((deps.inspectDesktopSupervision ?? inspectDesktopSupervision)());
+      if (notice) console.error(notice);
       // handleStop returns the structured outcome now; an object is always truthy, so
       // the warning must key on .ok — otherwise a failed stop would still claim downtime.
       if ((await deps.handleStop()).ok) console.log(warning);

package/src/cli/doctor.ts

@@ -7,11 +7,13 @@
  * it never sets proxy env, relocates state dirs, mutates quota, or changes
  * networking. See devlog/_plan/260630_wsl-account-autoswitch/30_*.
  */
+import { cliCommandDoctorChecks, collectCliPathDiagnostics } from "./cli-path-diagnostics";
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
 import { fetchLiveStartupHealth, probeUncleanExitState, selectStatusStartupHealth } from "./status";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -1324,6 +1326,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
   }
 
+  console.log("\nocx command selection");
+  for (const check of cliCommandDoctorChecks(collectCliPathDiagnostics())) {
+    console.log(`  ${check.level === "OK" ? "ok " : "!! "} ${check.message}`);
+    if (check.level === "FAIL") recordDoctorFailure();
+  }
+
   // Runs without the proxy on purpose: the worst accumulation happens when the proxy will
   // not start, which is exactly when the in-process periodic reclaim never ticks.
   const reclaimTemps = args.includes(RECLAIM_RESPONSE_TEMPS_FLAG);
@@ -1379,7 +1387,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
   });
   const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
-  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig));
+  const { startup } = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig),
+    live?.pid != null ? () => inspectDesktopSupervision({ targetPid: live.pid! }) : undefined, live?.pid);
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
@@ -1685,8 +1694,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
   const noProxy = currentProxyEnv.every(p => !p.present) && !configuredProxy.present;
   if (!startup.rebootSafe) {
-    const command = startup.recommendedCommand ?? startup.commands.restoreNative;
-    hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    if (startup.recommendedAction || startup.desktop?.supervisor) {
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. ${startup.recommendedAction ?? "Reopen OpenCodex and check Start at Login."}`);
+    } else {
+      const command = startup.recommendedCommand ?? startup.commands.restoreNative;
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    }
   }
   if (anyDrvfs) {
     hints.push("State dir is on a Windows-mounted (/mnt) drive. Prefer the Linux home (~) under WSL for token/lock reliability.");

package/src/cli/index.ts

@@ -8,6 +8,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { currentServingCommand, deferServiceChildToNewerRuntime, markDelegatedServiceReady, recordServingRuntime } from "../config/serving-runtimes";
 import { packageVersion } from "../lib/package-version";
+import { codexHomeIsAbsent } from "../codex/codex-home-owner";
+import { getCodexHome } from "../codex/paths";
 import { admitUpdateRestartChild } from "./update-restart-child";
 import { UpdateRestartRequired } from "./update-restart-candidate";
 import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
@@ -75,7 +77,7 @@ import {
   pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
+import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, runtimeSupervisorLine, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDownAsync, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 import { parseStartOptions, StartArgsError } from "./start-args";
@@ -85,11 +87,11 @@ import {
   recheckRestartFailedStart, reobserveRestartReplacement,
   restartStartOutcome,
   waitForProxyReplacement,
-  runProxyRestart,
   runTrayProxyStart,
   type ProxyRestartLive,
   type ProxyRestartStartOutcome,
 } from "./tray-proxy";
+import { duplicateRuntimeMessage, runDesktopAwareProxyRestart } from "./desktop-runtime-guidance";
 import { reportRestartFailure } from "./restart-failure";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
@@ -329,7 +331,7 @@ async function chooseListenPort(
         throw new StartCommandExit(serviceStayOutExitCode());
       }
       if (decision === "refuse-live-proxy") {
-        console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
+        console.error(duplicateRuntimeMessage(holder?.pid, preferred));
         throw new StartCommandExit(1);
       }
       if (decision === "refuse-unidentified-holder") {
@@ -444,7 +446,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       process.exit(serviceStayOutExitCode());
     }
     if (decision === "refuse" || decision === "await-parent") {
-      console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+      console.error(duplicateRuntimeMessage(owner.live.pid ?? owner.pidSnapshot, owner.live.port));
       process.exit(1);
     }
     // Sibling path. The new instance takes over this home's ocx.pid / runtime-port.json while
@@ -654,10 +656,12 @@ async function handleStart(options: { block?: boolean } = {}) {
     removeRuntimePort(process.pid);
     if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
       try {
-        const restored = restoreNativeCodex();
-        if (!restored.success) {
-          cleanupSucceeded = false;
-          console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+        if (!codexHomeIsAbsent(getCodexHome())) {
+          const restored = restoreNativeCodex();
+          if (!restored.success) {
+            cleanupSucceeded = false;
+            console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+          }
         }
       } catch (error) {
         cleanupSucceeded = false;
@@ -928,7 +932,7 @@ async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {
   const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
-  const result = await runProxyRestart({
+  const result = await runDesktopAwareProxyRestart({
     findLive: () => discoverStableProxyForRestart({
       findLive: () => findLiveProxy({ deadlineAt, attempts: 2, acceptPackageTreeFenced: true }),
       expired: () => Date.now() >= deadlineAt,
@@ -1785,6 +1789,7 @@ async function handleStatus() {
   console.log(`   Config: ${status.json.paths.config}${local}`);
   console.log(`   PID file: ${status.json.paths.pid}${local}`);
   console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
+  if (runtimeSupervisorLine(status.json.startup)) console.log(`   ${runtimeSupervisorLine(status.json.startup)}`);
   console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}${local}`);
   // On a client this is the local default, which routing does not use — the hub applies its own.
   console.log(`   Default provider: ${status.json.defaultProvider}${local}`);

package/src/cli/integration-aside-sync.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redactUserPath } from "../lib/redact";
 import type { RefusalReason } from "../integrations/mutation-plan";
+import { ASIDE_SYNC_EMPTY_LINES } from "./aside-profile-recovery";
 import { refreshAsideProfilesThroughServer } from "./aside-profiles";
 import { runCatalogAction } from "./catalog-command-result";
 import { CliUsageError, RuntimeApiError, printData, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
@@ -56,7 +57,7 @@ export function handleIntegrationAsideSync(argv: string[], deps: AsideSyncCliDep
     const parsed = resultsSchema.safeParse(outcomes);
     if (!parsed.success) throw new Error("Invalid Aside synchronization outcome");
     const results = parsed.data;
-    const lines = results.length === 0 ? ["No eligible Aside profiles to synchronize. Check integration status and profile sync preferences."]
+    const lines = results.length === 0 ? [...ASIDE_SYNC_EMPTY_LINES]
       : results.flatMap(row => [
         `Aside profile ${row.profileId}: ${row.ok ? row.changed ? "updated" : "unchanged" : "failed"}.`,
         ...(row.reason ? [row.reason] : []),

package/src/cli/integrations.ts

@@ -13,13 +13,14 @@ import {
   type RuntimeApiDeps,
 } from "./runtime-api";
 import { clientIntegrationPath, validateAsideProfile } from "./integration-input";
+import { asideProfileRecoveryLines } from "./aside-profile-recovery";
 import type { IntegrationClientId } from "../integrations/registry";
 
 const CLAUDE_USAGE = `Usage:
   ocx claude config [status] [--json]
   ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>]
       [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>]
-      [--compact-window <tokens|default>] [--inject-agents <on|off>]
+      [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>]
       [--small-fast-model <id|->] [--model-map <from=to,from=to|->]
       [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->]
       [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]
@@ -75,6 +76,7 @@ export async function handleClaudeConfigCommand(argv: string[], deps: RuntimeApi
     const fastMode = takeBooleanOption(args, "--fast-mode");
     const autoContext = takeBooleanOption(args, "--auto-context");
     const compact = takeOption(args, "--compact-window");
+    const accounting = takeOption(args, "--context-accounting");
     const injectAgents = takeBooleanOption(args, "--inject-agents");
     const smallFastModel = takeOption(args, "--small-fast-model");
     const modelMap = takeOption(args, "--model-map");
@@ -97,6 +99,11 @@ export async function handleClaudeConfigCommand(argv: string[], deps: RuntimeApi
         body.autoCompactWindow = value;
       }
     }
+    if (accounting !== undefined) {
+      const value = accounting.toLowerCase();
+      if (value !== "1m" && value !== "200k") throw new CliUsageError("--context-accounting must be 1m or 200k", CLAUDE_USAGE);
+      body.contextAccounting = value;
+    }
     if (injectAgents !== undefined) body.injectAgents = injectAgents;
     if (smallFastModel !== undefined) body.smallFastModel = smallFastModel === "-" ? "" : smallFastModel;
     if (modelMap !== undefined) body.modelMap = parseMap(modelMap);
@@ -194,7 +201,10 @@ function raycastBlock(result: unknown): RaycastStatusBlock | null {
  */
 function singleClientStatusLines(result: unknown): string[] {
   const raycast = raycastBlock(result);
-  if (!raycast) return summaryLines(result);
+  if (!raycast) {
+    const aside = (result as { clientId?: unknown } | null)?.clientId === "aside";
+    return [...summaryLines(result), ...(aside ? asideProfileRecoveryLines([result]) : [])];
+  }
   const rest = Object.fromEntries(Object.entries(result as Record<string, unknown>).filter(([key]) => key !== "raycast"));
   const lines = [...summaryLines(rest), `plan: ${raycast.plan}`];
   if (!raycast.aiDirPresent) {
@@ -252,7 +262,10 @@ export async function handleClientIntegrationCommand(
       const profiles = (result as { profiles?: Array<Record<string, unknown>> }).profiles;
       printData(result, wantsJson, profiles
         ? profiles.length > 0
-          ? profiles.map(row => `${String(row.profileId)}  ${String(row.name ?? "Aside")}: ${row.enabled ? "on" : "off"} (${String(row.state)})${row.current ? " [current]" : ""}`)
+          ? [
+            ...profiles.map(row => `${String(row.profileId)}  ${String(row.name ?? "Aside")}: ${row.enabled ? "on" : "off"} (${String(row.state)})${row.current ? " [current]" : ""}`),
+            ...asideProfileRecoveryLines(profiles),
+          ]
           : [String((result as { error?: string }).error ?? "No Aside profiles found.")]
         : rows
         /*

package/src/cli/resolve.ts

@@ -59,6 +59,7 @@ import {
 } from "../service/ownership-compatibility";
 import { observeManagingClis } from "../service/managing-cli";
 import { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION } from "../service/install-state-contract.mjs";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
 import { computeVersionSkew, type VersionSkew } from "./version-skew";
 
 /** Wire version of the resolve document. Bump only on an incompatible shape change. */
@@ -123,6 +124,12 @@ export interface ResolveJson {
    * takeover. Additive within ocx-resolve/1; older shells ignore it and read as unknown.
    */
   versionSkew?: VersionSkew;
+  supervisor?: {
+    kind: "desktop" | "none" | "unknown" | "unsupported";
+    supervisorPid?: number;
+    runtimePid?: number;
+    app?: string;
+  };
 }
 
 export type ResolveTakeover =
@@ -160,6 +167,7 @@ export interface ResolveIo {
   observeManagers?: (
     state: ServiceInstallState | null,
   ) => Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
+  inspectSupervision?: typeof inspectDesktopSupervision;
   stdout?: { log: (s: string) => void };
   stderr?: { error: (s: string) => void };
 }
@@ -187,6 +195,7 @@ export function buildResolveJson(
   cliVersion: string,
   ownership: ServiceOwnershipResolution,
   takeover: ResolveTakeover,
+  supervision?: ReturnType<typeof inspectDesktopSupervision>,
 ): ResolveJson {
   const configured = config.port ?? RESOLVE_DEFAULT_PORT;
   return {
@@ -199,6 +208,9 @@ export function buildResolveJson(
       source: live ? live.source : "config",
     },
     liveness: livenessJson(live),
+    ...(live && supervision ? { supervisor: supervision.kind === "desktop"
+      ? { kind: supervision.kind, supervisorPid: supervision.supervisorPid, runtimePid: supervision.runtimePid, app: supervision.app }
+      : { kind: supervision.kind } } : {}),
     ownership,
     takeover,
     // A proven absence has nothing to skew against; the field is omitted there rather
@@ -216,7 +228,8 @@ function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): v
   if (live.status === "live") {
     const pidText = live.pid === null ? "unknown" : String(live.pid);
     const versionText = live.version ?? "unknown version";
-    stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}.`);
+    const supervisor = json.supervisor?.kind === "desktop" ? `; supervisor: desktop (pid ${json.supervisor.supervisorPid})` : "";
+    stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}${supervisor}.`);
   } else {
     stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
   }
@@ -353,7 +366,17 @@ export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise
       };
     }
   }
-  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion(), ownership, takeover);
+  let supervision: ReturnType<typeof inspectDesktopSupervision> | undefined;
+  if (live) {
+    try {
+      supervision = live.pid === null ? { kind: "unknown", reason: "pid-unavailable", desktopSeen: false }
+        : (io.inspectSupervision ?? inspectDesktopSupervision)({ targetPid: live.pid });
+    } catch {
+      // Supervision is independent evidence; its failure cannot invalidate established liveness.
+      supervision = { kind: "unknown", reason: "probe-failed", desktopSeen: false };
+    }
+  }
+  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion(), ownership, takeover, supervision);
   if (args.json) stdout.log(JSON.stringify(json));
   else reportHuman(json, stdout);
   return 0;

package/src/cli/root.ts

@@ -1,6 +1,6 @@
 /**
- * CLI head: version/help early exits, `ocx ready` pre-parse, and the bounded
- * Codex-shim auto-restore preflight, in that order (Phase 1 of the CLI
+ * CLI head: version/help early exits, ready/resolve pre-parse, lifecycle version
+ * notice, then bounded Codex-shim auto-restore preflight (Phase 1 of the CLI
  * deepening — moved out of src/cli/index.ts).
  *
  * `parseCliHead` is pure (no I/O, no process access) so the ordering and the
@@ -16,6 +16,7 @@ import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 import { findCommand } from "./registry";
 import { printUnknownCommand } from "./help-recovery";
 import { noteCredentialArgv, redactSecretArgs } from "./secret-args";
+import { maybeNoticeVersionSkew } from "./version-skew-notice";
 
 export interface CliHead {
   kind: "version" | "help" | "ready" | "resolve" | "command";
@@ -141,6 +142,7 @@ export async function runCli(argv: string[]): Promise<CliHead> {
         console.error(uninstallError);
         process.exit(2);
       }
+      await maybeNoticeVersionSkew(head.command, head.args);
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
   }

package/src/cli/status.ts

@@ -1,3 +1,4 @@
+import { collectCliPathDiagnostics, formatCliStatusHealthLabel, type CliPathDiagnostics } from "./cli-path-diagnostics";
 import type { CodexMainAccountPolicyHealth } from "../oauth/health";
 import { durableBunRuntime } from "../lib/bun-runtime";
 import { existsSync, readFileSync } from "node:fs";
@@ -7,6 +8,7 @@ import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../cod
 import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
 import { collectStartupHealth, startupHealthReadBudgetMs, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
 import { missingOwnedCatalogPath } from "../codex/inject/config-toml";
@@ -215,6 +217,8 @@ export type CliStatusJson = {
    * ignores the key is unaffected, and `proxyVersion` is null when nothing is live.
    */
   versionSkew: VersionSkew;
+  cliCommand: CliPathDiagnostics;
+  startupSource: "live" | "local" | "local-supervision-override";
 };
 
 export type CliStatusView = {
@@ -259,12 +263,28 @@ export async function fetchLiveStartupHealth(
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
   const row = payload as Record<string, unknown>;
   if (row.status !== "native" && row.status !== "protected" && row.status !== "at-risk") return null;
-  if (row.protection !== "service" && row.protection !== "shim" && row.protection !== "none") return null;
+  if (row.protection !== "service" && row.protection !== "desktop" && row.protection !== "shim" && row.protection !== "none") return null;
   if (row.routingKind !== "native" && row.routingKind !== "opencodex-local"
     && row.routingKind !== "custom-local" && row.routingKind !== "custom-remote" && row.routingKind !== "unknown") return null;
   if (row.shimCoverage !== "full" && row.shimCoverage !== "cli-only" && row.shimCoverage !== "none") return null;
   if (typeof row.platform !== "string") return null;
   if (row.recommendedCommand !== null && typeof row.recommendedCommand !== "string") return null;
+  if (row.recommendedAction !== undefined && row.recommendedAction !== null
+    && (typeof row.recommendedAction !== "string" || row.recommendedAction.length > 512)) return null;
+  if (row.desktop !== undefined) {
+    if (!row.desktop || typeof row.desktop !== "object" || Array.isArray(row.desktop)) return null;
+    const desktop = row.desktop as Record<string, unknown>;
+    for (const key of ["owned", "loginEnabled", "running", "viable"] as const) {
+      if (typeof desktop[key] !== "boolean") return null;
+    }
+    if (desktop.supervisor !== undefined) {
+      if (!desktop.supervisor || typeof desktop.supervisor !== "object" || Array.isArray(desktop.supervisor)) return null;
+      const supervisor = desktop.supervisor as Record<string, unknown>;
+      if (typeof supervisor.supervisorPid !== "number" || !Number.isFinite(supervisor.supervisorPid)
+        || typeof supervisor.runtimePid !== "number" || !Number.isFinite(supervisor.runtimePid)
+        || typeof supervisor.app !== "string") return null;
+    }
+  }
   if (!row.commands || typeof row.commands !== "object" || Array.isArray(row.commands)) return null;
   for (const key of ["installService", "repairService", "installShim", "restoreNative"] as const) {
     if (typeof (row.commands as Record<string, unknown>)[key] !== "string") return null;
@@ -286,12 +306,36 @@ export async function fetchLiveStartupHealth(
   return payload as StartupHealth;
 }
 
-/** Prefer an attested live verdict and evaluate the local fallback only when live state is absent. */
+/** Older runtimes cannot report supervision; only that missing capability permits a local override. */
 export function selectStatusStartupHealth(
   liveStartup: StartupHealth | null,
   fallback: () => StartupHealth,
-): StartupHealth {
-  return liveStartup ?? fallback();
+  supervision?: () => ReturnType<typeof inspectDesktopSupervision>,
+  livePid?: number | null,
+): { startup: StartupHealth; startupSource: CliStatusJson["startupSource"] } {
+  if (!liveStartup) return { startup: fallback(), startupSource: "local" };
+  if (liveStartup.desktop === undefined && supervision) {
+    let evidence: ReturnType<typeof inspectDesktopSupervision> | undefined;
+    try { evidence = supervision(); }
+    catch { /* Failed optional evidence cannot replace an attested live verdict. */ }
+    if (evidence?.kind === "desktop" && evidence.runtimePid === livePid) {
+      const local = fallback();
+      const supervisor = local.desktop?.supervisor;
+      // The local probe runs later; it must still describe the same unowned process pair.
+      if (local.desktop?.owned === false && supervisor
+        && supervisor.runtimePid === evidence.runtimePid && supervisor.supervisorPid === evidence.supervisorPid) {
+        return { startup: local, startupSource: "local-supervision-override" };
+      }
+    }
+  }
+  return { startup: liveStartup, startupSource: "live" };
+}
+
+export function runtimeSupervisorLine(startup: StartupHealth): string | null {
+  const supervisor = startup.desktop?.supervisor;
+  return supervisor
+    ? `Runtime supervisor: OpenCodex Desktop (pid ${supervisor.supervisorPid}, ${supervisor.app}); durable owner: ${startup.desktop?.owned ? "desktop" : "none"}`
+    : null;
 }
 
 /** Build the service summary from the same startup source that `ocx status` selected. */
@@ -299,18 +343,23 @@ export function statusServiceSummary(
   liveStartup: StartupHealth | null,
   service: Pick<ReturnType<typeof diagnoseService>, "installed" | "summary">,
   live: boolean,
+  // Which verdict was selected. A live proxy can still be described by the local reading when
+  // the runtime predates supervision reporting, so the label follows the verdict, not liveness.
+  startupSource?: CliStatusJson["startupSource"],
 ): string {
-  if (liveStartup) {
+  if (live && liveStartup) {
+    const supervisor = liveStartup.desktop?.supervisor ? "OpenCodex Desktop supervises the running proxy; " : "";
     if (liveStartup.protection === "service" && liveStartup.serviceViable) {
-      return `running under the live managed service (logs: ${serviceLogPath()})`;
+      return `${supervisor}running under the live managed service (logs: ${serviceLogPath()})`;
     }
     const state = [
       liveStartup.serviceInstalled ? "installed" : "absent",
       liveStartup.serviceRunning ? "running" : "not running",
       liveStartup.serviceViable ? "viable" : "not viable",
     ].join(", ");
-    const action = liveStartup.recommendedCommand ? `; run '${liveStartup.recommendedCommand}'` : "";
-    return `live startup reports service ${state}${action} (logs: ${serviceLogPath()})`;
+    const action = !liveStartup.desktop?.supervisor && liveStartup.recommendedCommand ? `; run '${liveStartup.recommendedCommand}'` : "";
+    const label = (startupSource ?? (live ? "live" : "local")) === "live" ? "live" : "local";
+    return `${supervisor}${label} startup reports service ${state}${action} (logs: ${serviceLogPath()})`;
   }
   return service.installed && !live
     ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'`
@@ -680,6 +729,7 @@ export function missingCodexCatalogLines(missingCatalogPath: string | null): str
 
 /** `mainAccountPolicy`: only `--json` asks; the human report reads the same accounts once via OAuth health. */
 export async function collectStatus(options: { mainAccountPolicy?: boolean } = {}): Promise<CliStatusView> {
+  const cliCommand = collectCliPathDiagnostics();
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;
   const claudeDesktop = {
@@ -757,14 +807,14 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
   // A service can be registered and still not serve: the manager reports the job
   // either way. When the identity-probed live proxy provides an attested startup verdict,
   // prefer it over a shell-local service-manager probe that lacks the service environment.
-  const serviceSummary = statusServiceSummary(liveStartup, service, Boolean(live));
   const codexShim = diagnoseCodexShim();
   const codexShimSummary = codexShim.summary;
-  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(config, {
+  const { startup, startupSource } = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(config, {
     service,
     shim: codexShim,
     routingKind: getCodexRoutingKind(),
-  }));
+  }), live?.pid != null ? () => inspectDesktopSupervision({ targetPid: live.pid! }) : undefined, live?.pid);
+  const serviceSummary = statusServiceSummary(startup, service, Boolean(live), startupSource);
   const codexPlugins = diagnoseCodexBundledPlugins();
   const lastClamp = loadLastEffortClamp();
   const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime);
@@ -869,7 +919,7 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
 
   return {
     proxyLabel,
-    healthLabel: health.label,
+    healthLabel: formatCliStatusHealthLabel(health.label, cliCommand, remoteHub.connected),
     json: {
       ...(mainAccountHardLock ? { mainAccountHardLock } : {}),
       schemaVersion: 1,
@@ -932,6 +982,8 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
       // fact about this install, not about the Codex runtime, and filing it there would
       // print it under the wrong heading (#2701).
       versionSkew,
+      cliCommand,
+      startupSource,
     },
   };
 }

package/src/cli/update-restart-child.ts

@@ -16,7 +16,8 @@ function parseMarker(raw: string): UpdateRestartChildMarker {
   if (!value || !Number.isSafeInteger(value.deadlineAt) || !Number.isInteger(value.port)
     || typeof value.hostname !== "string" || value.port < 1 || value.port > 65535 || typeof value.version !== "string"
     || value.version === "0.0.0" || !parseStrictSemver(value.version) || !value.home
-    || !Number.isSafeInteger(value.home.revision)) throw new Error("update_restart_child_marker_invalid");
+    || !Number.isSafeInteger(value.home.revision) || value.home.serviceRecord?.schema !== 1
+    || typeof value.home.serviceRecord.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.home.serviceRecord.digest)) throw new Error("update_restart_child_marker_invalid");
   for (const directory of [value.home.config, value.home.codex]) {
     // Windows reports 64-bit NTFS file ids (MFT sequence in the high 16 bits) as doubles above
     // 2^53. Parent and child read them through the same stat API, so any finite integer is a
@@ -56,7 +57,7 @@ export function admitUpdateRestartChild(argv: string[], io: UpdateRestartChildIo
     if (now() >= marker.deadlineAt) throw new Error("update_restart_deadline_expired");
     const bindHost = (host: string) => !host.trim() || /^localhost\.?$/i.test(host.trim()) ? "127.0.0.1" : host.trim();
     if (port !== marker.port || bindHost(hostname) !== bindHost(marker.hostname) || (io.version ?? packageVersion)() !== marker.version) throw new Error("update_restart_child_identity_changed");
-    (io.checkHome ?? assertUpdateRestartHome)(marker.home);
+    (io.checkHome ?? (home => assertUpdateRestartHome(home, marker.deadlineAt)))(marker.home);
     (io.checkState ?? (expected => {
       assertUpdateRestartConfiguration(expected.hostname);
       const current = readRuntimePort();
@@ -65,6 +66,7 @@ export function admitUpdateRestartChild(argv: string[], io: UpdateRestartChildIo
         throw new Error("update_restart_competing_runtime");
       }
     }))(marker);
+    if (now() >= marker.deadlineAt) throw new Error("update_restart_deadline_expired");
   };
   check();
   const lease = (io.acquire ?? (waitMs => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs })))(Math.min(2000, marker.deadlineAt - now()));

package/src/cli/update-restart-home.ts

@@ -2,12 +2,15 @@ import { realpathSync, statSync } from "node:fs";
 import { readClientConnectionState } from "../client/state";
 import { readConfigDiagnostics } from "../config/diagnostics";
 import { getConfigDir } from "../config/paths";
-import { currentCodexHome, resolveServiceOwnership, resolveServiceState } from "../service/state";
+import { currentCodexHome } from "../service/state";
+import { captureUpdateRestartServiceRecord, type UpdateRestartServiceRecord, type UpdateRestartServiceRecordDeps } from "./update-restart-service-record";
+import { probeUpdateRestartSupervision, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
 export interface UpdateRestartHome {
   config: { path: string; dev: number; ino: number };
   codex: { path: string; dev: number; ino: number };
   revision: number;
+  serviceRecord: UpdateRestartServiceRecord;
 }
 
 function physicalDirectory(path: string): UpdateRestartHome["config"] {
@@ -17,17 +20,32 @@ function physicalDirectory(path: string): UpdateRestartHome["config"] {
   return { path: canonical, dev: stat.dev, ino: stat.ino };
 }
 
-/** Only an unclaimed standalone home is eligible for this narrow update path. */
-export function readUpdateRestartHome(): UpdateRestartHome {
-  const state = resolveServiceState();
-  const owner = resolveServiceOwnership();
-  if (state.kind !== "none" || owner.kind !== "none") throw new Error("update_restart_owner_unverified");
-  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision };
+export interface UpdateRestartHomeDeps {
+  record?: UpdateRestartServiceRecordDeps;
+  supervision?: UpdateRestartSupervisionDeps;
 }
 
-export function assertUpdateRestartHome(expected: UpdateRestartHome): void {
-  const current = readUpdateRestartHome();
-  if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("update_restart_home_changed");
+/** Capture eligibility from the same bytes that supply the frozen fingerprint. */
+export function readUpdateRestartHome(deps: UpdateRestartHomeDeps = {}): UpdateRestartHome {
+  const { serviceRecord, state, owner } = captureUpdateRestartServiceRecord(deps.record);
+  const platform = deps.record?.platform ?? process.platform;
+  if (owner.kind !== "none" || (state.kind === "state" && platform !== "darwin" && platform !== "linux")) {
+    throw new Error("update_restart_owner_unverified");
+  }
+  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision, serviceRecord };
+}
+
+export function assertUpdateRestartHome(expected: UpdateRestartHome, deadlineAt = Date.now() + 2000, deps: UpdateRestartHomeDeps = {}): void {
+  try {
+    const current = readUpdateRestartHome(deps);
+    if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("changed");
+  } catch { throw new Error("update_restart_home_changed"); }
+  if (probeUpdateRestartSupervision(deadlineAt, deps.supervision) !== "inactive") throw new Error("update_restart_supervision_unverified");
+  // Manager commands may yield to an external writer even though this guard is synchronous.
+  try {
+    if (JSON.stringify(readUpdateRestartHome(deps)) !== JSON.stringify(expected)) throw new Error("changed");
+  } catch { throw new Error("update_restart_home_changed"); }
+  if ((deps.supervision?.now ?? Date.now)() >= deadlineAt) throw new Error("update_restart_deadline_expired");
 }
 
 /** Read-only eligibility shared by parent pre-stop and child admission. */