@bitkyc08/opencodex 2.81.0 → 2.83.0

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

@@ -1,7 +1,7 @@
 /**
  * `ocx resolve` — the machine-readable runtime resolution surface for an embedding shell.
  *
- * D5 of devlog/_plan/260921_app_runtime_ownership/: the desktop shell must stop resolving
+ * D5 of devlog/_fin/260921_app_runtime_ownership/: the desktop shell must stop resolving
  * the config home, the port and liveness itself. The tuned probe budgets in
  * src/server/proxy-liveness.ts exist because a shell-side reimplementation answered
  * "nobody listening" twice and started duplicate proxies; this verb exposes that module's
@@ -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. */

package/src/cli/update-restart-service-record.ts

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, type BigIntStats } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { plistPath, resolveServiceOwnership, resolveServiceState, serviceStatePaths, type ServiceStateEvidence } from "../service/state";
+import { unitPath } from "../service/systemd";
+import { inspectInstallStateBytes } from "../service/install-state-contract.mjs";
+
+export interface UpdateRestartServiceRecord { schema: 1; digest: string }
+export interface UpdateRestartServiceRecordDeps {
+  platform?: NodeJS.Platform;
+  paths?: () => readonly string[];
+  definitionPath?: () => string;
+  open?: (path: string, flags: number) => number;
+  fstat?: (fd: number) => BigIntStats;
+  read?: (fd: number, buffer: Buffer, offset: number, length: number, position: number) => number;
+  lstat?: (path: string) => BigIntStats;
+}
+/** Maximum bytes per state candidate or platform definition: 1 MiB, including growth during read. */
+export const UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES = 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+const FAILURE = "update_restart_service_record_unverified";
+const hash = (bytes: string | Buffer) => createHash("sha256").update(bytes).digest("hex");
+const metadata = (stat: BigIntStats) => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.mode, stat.uid, stat.gid].map(String);
+const absent = (error: unknown) => !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
+
+// Canonicalize directories, never the record itself: a record symlink is a refusal.
+function canonicalPath(path: string): string {
+  const parent = dirname(path);
+  try { return join(realpathSync.native(parent), basename(path)); }
+  catch (error) {
+    if (!absent(error) || parent === path) throw new Error(FAILURE);
+    return join(canonicalPath(parent), basename(path));
+  }
+}
+
+function readBoundedRecord(fd: number, read: NonNullable<UpdateRestartServiceRecordDeps["read"]>): Buffer {
+  const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for (;;) {
+    // At the limit, a one-byte read distinguishes EOF from concurrent growth.
+    const length = Math.min(chunk.length, UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES - total + 1);
+    const count = read(fd, chunk, 0, length, total);
+    if (!Number.isInteger(count) || count < 0 || count > length) throw new Error(FAILURE);
+    if (count === 0) return Buffer.concat(chunks, total);
+    total += count;
+    if (total > UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES) throw new Error(FAILURE);
+    chunks.push(Buffer.from(chunk.subarray(0, count)));
+  }
+}
+
+/** Read all authority/mirror candidates and the platform definition as one frozen record. */
+export function captureUpdateRestartServiceRecord(deps: UpdateRestartServiceRecordDeps = {}) {
+  try {
+    const platform = deps.platform ?? process.platform;
+    const paths = (deps.paths ?? serviceStatePaths)();
+    const definition = platform === "darwin" ? (deps.definitionPath ?? plistPath)()
+      : platform === "linux" ? (deps.definitionPath ?? unitPath)() : undefined;
+    const statPath = deps.lstat ?? (path => lstatSync(path, { bigint: true }));
+    const captures = [...paths, ...(definition ? [definition] : [])].map((path, index) => {
+      const canonical = canonicalPath(path);
+      let before: BigIntStats;
+      try { before = statPath(path); }
+      catch (error) {
+        if (!absent(error)) throw error;
+        return { path, canonical, index, identity: null, bytes: undefined };
+      }
+      if (!before.isFile() || before.isSymbolicLink()) throw new Error(FAILURE);
+      const fd = (deps.open ?? openSync)(path, constants.O_RDONLY | (platform === "win32" ? 0 : constants.O_NOFOLLOW | constants.O_NONBLOCK));
+      try {
+        const statFd = deps.fstat ?? (handle => fstatSync(handle, { bigint: true }));
+        const opened = statFd(fd);
+        const identity = metadata(before);
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino
+          || opened.size < 0n || opened.size > BigInt(UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES)
+          || JSON.stringify(identity) !== JSON.stringify(metadata(opened))) throw new Error(FAILURE);
+        const bytes = readBoundedRecord(fd, deps.read ?? readSync);
+        const after = statFd(fd);
+        if (!after.isFile() || JSON.stringify(identity) !== JSON.stringify(metadata(after))
+          || BigInt(bytes.length) !== after.size) throw new Error(FAILURE);
+        return { path, canonical, index, identity, bytes };
+      } finally { closeSync(fd); }
+    });
+    // Pin path-to-descriptor identity after every read; also confirm each ENOENT again.
+    for (const entry of captures) {
+      let current: BigIntStats;
+      try { current = statPath(entry.path); }
+      catch (error) { if (entry.identity === null && absent(error)) continue; throw error; }
+      if (!current.isFile() || JSON.stringify(metadata(current)) !== JSON.stringify(entry.identity)
+        || canonicalPath(entry.path) !== entry.canonical) throw new Error(FAILURE);
+    }
+    const evidence: ServiceStateEvidence[] = captures.slice(0, paths.length).map(entry => {
+      if (!entry.bytes) return { path: entry.canonical, kind: "absent" };
+      const parsed = inspectInstallStateBytes(entry.canonical, () => entry.bytes!.toString("utf8"));
+      if (parsed.kind !== "valid") throw new Error(FAILURE);
+      return parsed as ServiceStateEvidence;
+    });
+    const state = resolveServiceState(evidence);
+    const owner = resolveServiceOwnership(evidence);
+    if (state.kind === "unknown" || owner.kind === "unknown") throw new Error(FAILURE);
+    const serviceRecord: UpdateRestartServiceRecord = { schema: 1, digest: hash(JSON.stringify({
+      platform, authority: paths.length - 1,
+      records: captures.map(entry => [entry.canonical, entry.index, entry.identity, entry.bytes ? hash(entry.bytes) : null]),
+    })) };
+    return { serviceRecord, state, owner };
+  } catch { throw new Error(FAILURE); }
+}
+
+/** Drift is terminal; never replace the transaction's original digest. */
+export function assertUpdateRestartServiceRecord(expected: UpdateRestartServiceRecord, deps: UpdateRestartServiceRecordDeps = {}) {
+  try {
+    const current = captureUpdateRestartServiceRecord(deps);
+    if (expected.schema !== 1 || current.serviceRecord.digest !== expected.digest) throw new Error(FAILURE);
+    return current;
+  } catch { throw new Error("update_restart_home_changed"); }
+}

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

@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { statSync, type Stats } from "node:fs";
+import { systemdUserBusEnvironment } from "../service/systemd";
+import { assertLiveServiceManagerAllowed } from "../service/guards";
+import { LABEL, TASK } from "../service/state";
+
+export type UpdateRestartSupervision = "inactive" | "active" | "unknown";
+export interface UpdateRestartSupervisorReply { status: number | null; stdout: string; stderr: string }
+export interface UpdateRestartSupervisionDeps {
+  platform?: NodeJS.Platform;
+  now?: () => number;
+  uid?: number;
+  stat?: (path: string) => Pick<Stats, "isFile" | "mode">;
+  environment?: NodeJS.ProcessEnv;
+  exists?: (path: string) => boolean;
+  run?: (command: string, args: string[], timeoutMs: number, environment: NodeJS.ProcessEnv) => UpdateRestartSupervisorReply;
+}
+const PROBE_TIMEOUT_MS = 2000;
+export const UPDATE_RESTART_SYSTEMD_ARGS = ["--user", "show", "-p", "LoadState", "-p", "ActiveState", "-p", "MainPID", "-p", "FragmentPath", "-p", "NeedDaemonReload", TASK];
+
+function run(command: string, args: string[], timeout: number, env: NodeJS.ProcessEnv): UpdateRestartSupervisorReply {
+  assertLiveServiceManagerAllowed("update restart supervision");
+  try {
+    return { status: 0, stdout: execFileSync(command, args, { encoding: "utf8", timeout, env,
+      killSignal: "SIGKILL", maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "pipe"] }), stderr: "" };
+  } catch (error) {
+    const failure = error as { status?: number | null; signal?: string; code?: string; stdout?: Buffer; stderr?: Buffer };
+    if (failure.signal || failure.code || !Number.isInteger(failure.status)) throw new Error("update_restart_supervision_unverified");
+    return { status: failure.status!, stdout: failure.stdout?.toString() ?? "", stderr: failure.stderr?.toString() ?? "" };
+  }
+}
+
+/** Ignore PATH; usr-merged systemctl symlinks may resolve to a regular trusted-location target. */
+export function resolveUpdateRestartSupervisor(deps: UpdateRestartSupervisionDeps = {}): string | null {
+  const platform = deps.platform ?? process.platform;
+  const paths = platform === "linux" ? ["/usr/bin/systemctl", "/bin/systemctl"] : platform === "darwin" ? ["/bin/launchctl"] : [];
+  for (const path of paths) {
+    try {
+      const stat = (deps.stat ?? statSync)(path);
+      if (stat.isFile() && (stat.mode & 0o002) === 0 && (stat.mode & 0o111) !== 0) return path;
+    } catch { /* Try the next trusted location; no PATH fallback. */ }
+  }
+  return null;
+}
+
+/** All manager evidence shares the transaction deadline, including the retained PID-bound probe. */
+export function runBoundedUpdateRestartSupervisor(command: string, args: string[], deadlineAt: number, deps: UpdateRestartSupervisionDeps = {}) {
+  const now = deps.now ?? Date.now;
+  const remaining = deadlineAt - now();
+  if (!Number.isFinite(remaining) || remaining <= 0) throw new Error("update_restart_supervision_unverified");
+  const environment = (deps.platform ?? process.platform) === "linux"
+    ? systemdUserBusEnvironment(deps.environment ?? process.env, { uid: deps.uid, exists: deps.exists })
+    : { ...(deps.environment ?? process.env) };
+  const result = (deps.run ?? run)(command, args, Math.min(PROBE_TIMEOUT_MS, remaining), environment);
+  if (now() >= deadlineAt) throw new Error("update_restart_supervision_unverified");
+  return result;
+}
+
+/** Registration presence is independent of liveness; only positive inactivity admits. */
+export function probeUpdateRestartSupervision(deadlineAt: number, deps: UpdateRestartSupervisionDeps = {}, command = resolveUpdateRestartSupervisor(deps)): UpdateRestartSupervision {
+  const platform = deps.platform ?? process.platform;
+  if (!command) return "unknown";
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 0;
+    const states = [`gui/${uid}/${LABEL}`, `user/${uid}/${LABEL}`].map(target => {
+      try {
+        const result = runBoundedUpdateRestartSupervisor(command, ["print", target], deadlineAt, deps);
+        return result.status === 112 || result.status === 113 ? "inactive" : result.status === 0 ? "active" : "unknown";
+      } catch { return "unknown"; }
+    });
+    return states.includes("unknown") ? "unknown" : states.includes("active") ? "active" : "inactive";
+  }
+  if (platform === "linux") {
+    try {
+      const result = runBoundedUpdateRestartSupervisor(command, UPDATE_RESTART_SYSTEMD_ARGS, deadlineAt, deps);
+      return classifyUpdateRestartSystemdSupervision(result);
+    } catch { return "unknown"; }
+  }
+  return "unknown";
+}
+
+/** The retained manager observation must satisfy the same positive-inactivity contract. */
+export function classifyUpdateRestartSystemdSupervision(result: UpdateRestartSupervisorReply): UpdateRestartSupervision {
+  if (result.status !== 0) return "unknown";
+  const fields = new Map<string, string>();
+  for (const line of result.stdout.trim().split(/\r?\n/)) {
+    const match = /^([A-Za-z]+)=(.*)$/.exec(line);
+    if (!match || fields.has(match[1]!)) return "unknown";
+    fields.set(match[1]!, match[2]!);
+  }
+  const pid = fields.get("MainPID");
+  if (!pid || !/^\d+$/.test(pid) || !Number.isSafeInteger(Number(pid))) return "unknown";
+  if (!["loaded", "not-found"].includes(fields.get("LoadState") ?? "")) return "unknown";
+  if (fields.get("ActiveState") === "inactive" && pid === "0") return "inactive";
+  return fields.get("ActiveState") === "active" || Number(pid) > 0 ? "active" : "unknown";
+}