@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/service/desktop-startup.ts

@@ -1,18 +1,24 @@
 import { execFileSync } from "node:child_process";
-import { accessSync, constants, readFileSync, realpathSync } from "node:fs";
+import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { readPid } from "../config/process-state";
 import { resolveServiceOwnership, sameServiceOwnershipSubject, type ServiceOwnershipResolution } from "./state";
-import { inspectDesktopSupervision, processIdentity, procfs, type ProcReader } from "./desktop-supervision.mjs";
+import { inspectDesktopSupervision, processIdentity, procfs, type DesktopSupervisionDeps, type ProcReader } from "./desktop-supervision.mjs";
 
 export interface DesktopStartupDiagnostic {
   /** Durable desktop claim; failed supervision does not release ownership. */
   owned: boolean;
   loginEnabled: boolean;
+  /** Verified enabled macOS registration; absence means registration is not credited. */
+  loginRegistration?: "loaded" | "registered-not-loaded";
   running: boolean;
   viable: boolean;
-  /** Live parentage when no durable claim exists; never converts supervision into ownership. */
+  /**
+   * Proven live parentage; never converts supervision into ownership. macOS and Linux report it
+   * only without a durable claim. Windows also reports it beside a durable Desktop claim, because
+   * older Windows runtimes never published a Desktop diagnostic that status could defer to.
+   */
   supervisor?: { supervisorPid: number; runtimePid: number; app: string };
 }
 
@@ -21,6 +27,14 @@ export function deriveDesktopStartup(facts: Omit<DesktopStartupDiagnostic, "viab
   return { ...facts, viable: (facts.owned || facts.supervisor !== undefined) && facts.loginEnabled && facts.running };
 }
 
+export function desktopLoginStatusSummary(desktop: DesktopStartupDiagnostic): string {
+  if (!desktop.loginEnabled) return "Desktop Start at Login: not registered, disabled, or could not be verified.";
+  if (desktop.loginRegistration === "registered-not-loaded") {
+    return "Desktop Start at Login: registered and enabled for next login; not loaded in this session.";
+  }
+  return `Desktop Start at Login: enabled${desktop.loginRegistration === "loaded" ? " and loaded in this session" : ""}.`;
+}
+
 function run(command: string, args: string[]): string {
   return execFileSync(command, args, { encoding: "utf8", timeout: 750, maxBuffer: 128 * 1024, stdio: ["ignore", "pipe", "pipe"] }).trim();
 }
@@ -35,12 +49,16 @@ interface DesktopStartupDeps {
   run?: typeof run;
   env?: NodeJS.ProcessEnv;
   proc?: ProcReader;
+  windowsProcesses?: DesktopSupervisionDeps["windowsProcesses"];
+  now?: () => number;
+  /** The Desktop's own install id (Tauri app_config_dir); null when unreadable. */
+  readWindowsInstallId?: () => string | null;
 }
 
 /** Cheap ownership-only snapshot: no launchd/process probes on the server request path. */
 export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopStartupDiagnostic | undefined {
   const platform = deps.platform ?? process.platform;
-  if (platform !== "darwin" && platform !== "linux") return undefined;
+  if (platform !== "darwin" && platform !== "linux" && platform !== "win32") return undefined;
   const owner = (deps.ownership ?? resolveServiceOwnership)();
   return owner.kind === "owned" && owner.ownership.owner === "desktop"
     ? deriveDesktopStartup({ owned: true, loginEnabled: false, running: false }) : undefined;
@@ -49,33 +67,85 @@ export function desktopStartupOwnership(deps: DesktopStartupDeps = {}): DesktopS
 function macLoginRegistration(deps: DesktopStartupDeps) {
   const execute = deps.run ?? run;
   const path = join(deps.home ?? homedir(), "Library", "LaunchAgents", "OpenCodex.plist");
-  const plist = JSON.parse(execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]));
-  const args = plist.ProgramArguments;
-  if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
-    || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
-    || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
-    || (plist.Program !== undefined && plist.Program !== args[0])) return null;
-  const app = realpathSync(args[0]);
-  const proxy = realpathSync(join(dirname(app), "ocx"));
-  accessSync(app, constants.X_OK);
-  accessSync(proxy, constants.X_OK);
   const domain = `gui/${deps.uid ?? process.getuid!()}`;
-  const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
-  const loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]);
+  const identity = (file: string) => {
+    const stat = lstatSync(file, { bigint: true });
+    return [stat.dev, stat.ino, stat.size, stat.mode, stat.mtimeNs, stat.ctimeNs].map(String).join(":");
+  };
+  const capture = () => {
+    const registrationPath = realpathSync(path);
+    const plistIdentity = identity(path), targetIdentity = identity(registrationPath);
+    const definition = execute("/usr/bin/plutil", ["-convert", "json", "-o", "-", path]);
+    const plist = JSON.parse(definition);
+    const args = plist.ProgramArguments;
+    if (plist.Label !== "OpenCodex" || plist.RunAtLoad !== true || !Array.isArray(args)
+      || args.length !== 2 || args[1] !== "--autostart" || typeof args[0] !== "string"
+      || !args[0].endsWith("/Contents/MacOS/opencodex-desktop")
+      || (plist.Program !== undefined && plist.Program !== args[0])
+      || (plist.Disabled !== undefined && typeof plist.Disabled !== "boolean")) return null;
+    const app = realpathSync(args[0]);
+    const proxy = realpathSync(join(dirname(app), "ocx"));
+    accessSync(app, constants.X_OK);
+    accessSync(proxy, constants.X_OK);
+    const appIdentity = identity(app), proxyIdentity = identity(proxy);
+    const disabled = execute("/bin/launchctl", ["print-disabled", domain]);
+    const mentions = disabled.match(/"OpenCodex"/g)?.length ?? 0;
+    const override = /"OpenCodex"\s*=>\s*(enabled|false|disabled|true)(?=\s*(?:\r?\n|[,;}]|$))/.exec(disabled)?.[1];
+    const loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
+      && (mentions === 0 ? plist.Disabled !== true : mentions === 1 && (override === "enabled" || override === "false"));
+    if (registrationPath !== realpathSync(path) || plistIdentity !== identity(path) || targetIdentity !== identity(registrationPath)
+      || app !== realpathSync(args[0]) || proxy !== realpathSync(join(dirname(app), "ocx"))
+      || appIdentity !== identity(app) || proxyIdentity !== identity(proxy)) return null;
+    return { app, proxy, loginEnabled, registrationPath, plistIdentity, targetIdentity, definition, appIdentity, proxyIdentity, disabled };
+  };
+  const first = capture();
+  if (!first) return null;
+  const { app, proxy } = first;
+  if (!first.loginEnabled) return { app, proxy, loginEnabled: false };
+  let loaded: string;
+  try { loaded = execute("/bin/launchctl", ["print", `${domain}/OpenCodex`]); }
+  catch (error) {
+    // execFileSync's specific service-not-found result is absence, not a failed probe.
+    // Timeout, permission denial, missing tools and another domain remain unverified.
+    const failure = error as { status?: number; stderr?: unknown; signal?: unknown; code?: unknown } | null;
+    const stderr = typeof failure?.stderr === "string" ? failure.stderr
+      : Buffer.isBuffer(failure?.stderr) ? failure.stderr.toString("utf8") : "";
+    const message = `Could not find service "OpenCodex" in domain for user gui: ${domain.slice(4)}`;
+    const missing = failure?.status === 113 && !failure.signal && !failure.code
+      && [message, `Bad request.\n${message}`].includes(stderr.trim());
+    if (!missing) throw error;
+    // The absent job supplies no durable registration evidence. Re-read the entire
+    // registration and enabled state; replacement or ambiguity revokes login credit.
+    const final = capture();
+    if (!final || JSON.stringify(first) !== JSON.stringify(final)) return { app, proxy, loginEnabled: false };
+    return { app, proxy, loginEnabled: true, loginRegistration: "registered-not-loaded" as const };
+  }
   const program = /^\s*program = (.+)$/m.exec(loaded)?.[1];
   const loadedPath = /^\s*path = (.+)$/m.exec(loaded)?.[1];
-  const loginEnabled = /^\s*disabled services = \{[\s\S]*\}\s*$/.test(disabled)
-    && !/"OpenCodex"\s*=>\s*(?:disabled|true)/.test(disabled)
-    && program !== undefined && realpathSync(program) === app
-    && loadedPath !== undefined && realpathSync(loadedPath) === realpathSync(path);
-  return { app, proxy, loginEnabled };
+  const loginEnabled = program !== undefined && realpathSync(program) === app
+    && loadedPath !== undefined && realpathSync(loadedPath) === first.registrationPath;
+  return { app, proxy, loginEnabled, ...(loginEnabled ? { loginRegistration: "loaded" as const } : {}) };
+}
+
+type DesktopLoginFacts = Pick<DesktopStartupDiagnostic, "loginEnabled" | "loginRegistration">;
+
+/**
+ * Start at Login credit for one Desktop app copy. The tray's Start at Login item ports this
+ * judgment (desktop/src-tauri/src/login_registration.rs); both run the cases in
+ * tests/fixtures/desktop-login-registration-cases.json. Throws when evidence is unreadable.
+ */
+export function macLoginFactsFor(app: string, deps: DesktopStartupDeps): DesktopLoginFacts {
+  const login = macLoginRegistration(deps);
+  return login !== null && login.app === app
+    ? { loginEnabled: login.loginEnabled, ...(login.loginRegistration ? { loginRegistration: login.loginRegistration } : {}) }
+    : { loginEnabled: false };
 }
 
-function diagnoseSupervisedStartup(deps: DesktopStartupDeps, ownerRevision: number, loginFor: (app: string) => boolean): DesktopStartupDiagnostic | undefined {
+function diagnoseSupervisedStartup(deps: DesktopStartupDeps, ownerRevision: number, loginFor: (app: string) => DesktopLoginFacts): DesktopStartupDiagnostic | undefined {
   const evidence = inspectDesktopSupervision(deps);
   if (evidence.kind !== "desktop") return undefined;
-  let loginEnabled = false;
-  try { loginEnabled = loginFor(evidence.app); }
+  let login: DesktopLoginFacts = { loginEnabled: false };
+  try { login = loginFor(evidence.app); }
   catch { /* Login failure revokes restart viability, not the observed live supervisor. */ }
   if ((deps.ownership ?? resolveServiceOwnership)().kind !== "none") return undefined;
   // Login probes can outlive the runtime or its parent; only the same live chain gets credit.
@@ -86,7 +156,7 @@ function diagnoseSupervisedStartup(deps: DesktopStartupDeps, ownerRevision: numb
   const finalOwner = (deps.ownership ?? resolveServiceOwnership)();
   if (finalOwner.kind !== "none" || finalOwner.revision !== ownerRevision) return undefined;
   const { supervisorPid, runtimePid, app } = evidence;
-  return deriveDesktopStartup({ owned: false, loginEnabled, running: true, supervisor: { supervisorPid, runtimePid, app } });
+  return deriveDesktopStartup({ owned: false, ...login, running: true, supervisor: { supervisorPid, runtimePid, app } });
 }
 
 /** Read-only macOS desktop ownership, login registration and live parent/child checks. */
@@ -94,12 +164,9 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
   if ((deps.platform ?? process.platform) !== "darwin") return undefined;
   const ownership = deps.ownership ?? resolveServiceOwnership;
   const owner = ownership();
-  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => {
-    const login = macLoginRegistration(deps);
-    return login !== null && login.app === app && login.loginEnabled;
-  });
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, app => macLoginFactsFor(app, deps));
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
-  const facts = { owned: true, loginEnabled: false, running: false };
+  const facts: Omit<DesktopStartupDiagnostic, "viable"> = { owned: true, loginEnabled: false, running: false };
   const execute = deps.run ?? run;
   const pidReader = deps.readPid ?? readPid;
   try {
@@ -110,6 +177,7 @@ export function diagnoseMacDesktopStartup(deps: DesktopStartupDeps = {}): Deskto
     if (!login) return deriveDesktopStartup(facts);
     const { app, proxy } = login;
     facts.loginEnabled = login.loginEnabled;
+    if (login.loginRegistration) facts.loginRegistration = login.loginRegistration;
     const pid = pidReader();
     if (pid !== null) {
       const child = processIdentity(pid, execute);
@@ -156,10 +224,10 @@ export function diagnoseLinuxDesktopStartup(deps: DesktopStartupDeps = {}): Desk
     const configured = (deps.env ?? process.env).XDG_CONFIG_HOME;
     const config = configured && isAbsolute(configured) ? configured : join(home, ".config");
     // auto-launch's HOME entry must remain inside the session's XDG autostart search path.
-    if (resolve(config) !== resolve(home, ".config")) return false;
+    if (resolve(config) !== resolve(home, ".config")) return { loginEnabled: false };
     const entry = readFileSync(join(home, ".config", "autostart", "OpenCodex.desktop"), "utf8");
     const login = linuxLoginApp(entry);
-    return login !== null && realpathSync(login) === app;
+    return { loginEnabled: login !== null && realpathSync(login) === app };
   });
   if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
   const facts = { owned: true, loginEnabled: false, running: false };
@@ -212,5 +280,50 @@ export function diagnoseLinuxDesktopStartup(deps: DesktopStartupDeps = {}): Desk
 
 /** Platform dispatch for the full (probing) desktop startup diagnostic. */
 export function diagnoseDesktopStartup(deps: DesktopStartupDeps = {}): DesktopStartupDiagnostic | undefined {
-  return (deps.platform ?? process.platform) === "linux" ? diagnoseLinuxDesktopStartup(deps) : diagnoseMacDesktopStartup(deps);
+  const platform = deps.platform ?? process.platform;
+  if (platform === "linux") return diagnoseLinuxDesktopStartup(deps);
+  if (platform === "win32") return diagnoseWindowsDesktopStartup(deps);
+  return diagnoseMacDesktopStartup(deps);
+}
+
+/** Tauri resolves app_config_dir to the roaming AppData folder plus the bundle identifier. */
+function readWindowsInstallId(env: NodeJS.ProcessEnv): string | null {
+  const appData = env.APPDATA;
+  if (!appData || !/^[A-Za-z]:[\\/]/.test(appData)) return null;
+  try {
+    return readFileSync(win32.join(appData, "com.opencodex.desktop", "install-id"), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read-only Windows desktop ownership and live parent/child checks. Windows Start at Login is
+ * not verified, so it is never credited and Desktop never reads as startup protection here;
+ * the diagnostic still names the supervisor so status and doctor stop recommending service repairs.
+ */
+export function diagnoseWindowsDesktopStartup(deps: DesktopStartupDeps = {}): DesktopStartupDiagnostic | undefined {
+  if ((deps.platform ?? process.platform) !== "win32") return undefined;
+  const ownership = deps.ownership ?? resolveServiceOwnership;
+  const owner = ownership();
+  if (owner.kind === "none") return diagnoseSupervisedStartup(deps, owner.revision, () => ({ loginEnabled: false }));
+  if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return undefined;
+  const facts = { owned: true, loginEnabled: false, running: false };
+  try {
+    const installId = deps.readWindowsInstallId ? deps.readWindowsInstallId() : readWindowsInstallId(deps.env ?? process.env);
+    if (installId !== owner.ownership.installId) return deriveDesktopStartup(facts);
+    const evidence = inspectDesktopSupervision(deps);
+    if (evidence.kind !== "desktop") return deriveDesktopStartup(facts);
+    // Only the same live chain, read again after the claim, earns running and the supervisor.
+    const final = inspectDesktopSupervision({ ...deps, targetPid: evidence.runtimePid });
+    const current = ownership();
+    if (final.kind !== "desktop" || final.runtimePid !== evidence.runtimePid
+      || final.supervisorPid !== evidence.supervisorPid || final.app !== evidence.app
+      || current.kind === "unknown" || !sameServiceOwnershipSubject(owner, current)) return deriveDesktopStartup(facts);
+    const { supervisorPid, runtimePid, app } = final;
+    return deriveDesktopStartup({ ...facts, running: true, supervisor: { supervisorPid, runtimePid, app } });
+  } catch {
+    // Unreadable evidence never grants running or releases the claim.
+    return deriveDesktopStartup(facts);
+  }
 }

package/src/service/desktop-supervision.d.mts

@@ -9,18 +9,44 @@ export interface ProcReader {
   parent(pid: number): number;
 }
 
+/** One Win32_Process row; `created` is UTC ticks as a decimal string (exceeds 2^53). */
+export interface WindowsProcessRow {
+  pid: number;
+  parent: number;
+  exe: string | null;
+  session: number;
+  created: string;
+}
+
+export interface WindowsProcessPair {
+  child: WindowsProcessRow | null;
+  parent: WindowsProcessRow | null;
+}
+
+export interface WindowsProcessReadOptions {
+  /** Called with the parent image before row validation, so partial Desktop evidence keeps its veto. */
+  onExecutable?: (path: string) => void;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+}
+
 export interface DesktopSupervisionDeps {
   targetPid?: number;
   platform?: NodeJS.Platform;
-  run?: (command: string, args: string[]) => string;
+  run?: (command: string, args: string[], timeoutMs?: number) => string;
   proc?: ProcReader;
   readPid?: () => number | null;
   readRuntimePortPid?: () => number | null;
+  windowsProcesses?: (pid: number, options: Pick<WindowsProcessReadOptions, "onExecutable" | "timeoutMs">) => WindowsProcessPair | null;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
 }
 
 export function desktopSupervisionPaths(): { pid: string; runtimePort: string };
 export const procfs: ProcReader;
 export function processIdentity(pid: number, execute?: DesktopSupervisionDeps["run"], onExecutable?: (path: string) => void):
   { parent: number; executable: string } | null;
+export function windowsPowerShellPath(env?: NodeJS.ProcessEnv): string;
+export function windowsProcessPair(pid: number, execute?: DesktopSupervisionDeps["run"], options?: WindowsProcessReadOptions): WindowsProcessPair;
 export function inspectDesktopSupervision(deps?: DesktopSupervisionDeps): SupervisionEvidence;
 export function createSupervisionLatch(): { observe(evidence: SupervisionEvidence): boolean };

package/src/service/desktop-supervision.mjs

@@ -1,12 +1,12 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve, win32 } from "node:path";
 
 // Node >=18 also imports this module from bin/ocx.mjs; do not import TS or Bun APIs.
-function run(command, args) {
+function run(command, args, timeout = 750) {
   return execFileSync(command, args, {
-    encoding: "utf8", timeout: 750, maxBuffer: 128 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8", timeout, maxBuffer: 128 * 1024, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
   }).trim();
 }
 
@@ -69,17 +69,92 @@ export function processIdentity(pid, execute = run, onExecutable) {
   return { parent: Number(row[1]), executable: realpathSync(row[2]) };
 }
 
+/**
+ * Windows has no ps or procfs that Node can read, so one bounded Win32_Process read
+ * answers the runtime row and its parent's row. Each inspection shares one budget
+ * across its two snapshots; the startup diagnostic runs two inspections, and both
+ * must fit the 15 s Windows startup probe (src/codex/autostart-health.ts).
+ */
+const WINDOWS_INSPECTION_BUDGET_MS = 6_000;
+const WINDOWS_ACQUISITION_TIMEOUT_MS = 3_000;
+const WINDOWS_MIN_ACQUISITION_MS = 250;
+const WINDOWS_DESKTOP_IMAGE = "opencodex-desktop.exe";
+
+/** Mirrors src/update/npm-invocation.mjs: plain ESM cannot reach the FFI system-directory resolver. */
+export function windowsPowerShellPath(env = process.env) {
+  const root = env.SystemRoot ?? env.windir;
+  const base = root && /^[A-Za-z]:\\/.test(root.replaceAll("/", "\\")) ? root : "C:\\Windows";
+  return win32.join(base, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+
+function windowsProcessScript(pid) {
+  // pid is a validated safe integer; it only ever reaches a numeric WQL filter.
+  return [
+    "$ErrorActionPreference='Stop'",
+    "function Row($p) { if ($null -eq $p) { return $null }; [ordered]@{ pid=[string]$p.ProcessId; parent=[string]$p.ParentProcessId; exe=$p.ExecutablePath; session=[string]$p.SessionId; created=$(if ($p.CreationDate) { [string]$p.CreationDate.ToUniversalTime().Ticks } else { $null }) } }",
+    `$c=Get-CimInstance -ClassName Win32_Process -Filter 'ProcessId=${pid}'`,
+    "$p=$null",
+    "if ($c -and [uint32]$c.ParentProcessId -gt 0) { $p=Get-CimInstance -ClassName Win32_Process -Filter ('ProcessId=' + [uint32]$c.ParentProcessId) }",
+    "[ordered]@{ child=(Row $c); parent=(Row $p) } | ConvertTo-Json -Compress",
+  ].join("; ");
+}
+
+function windowsInteger(value) {
+  const text = typeof value === "number" || typeof value === "string" ? String(value) : "";
+  if (!/^\d{1,10}$/.test(text)) throw new Error("invalid process field");
+  return Number(text);
+}
+
+function windowsRow(row) {
+  if (row === null || row === undefined) return null;
+  if (typeof row !== "object" || Array.isArray(row)) throw new Error("invalid process row");
+  // Ticks exceed 2^53; they stay decimal strings and are compared as BigInt.
+  if (typeof row.created !== "string" || !/^\d{1,20}$/.test(row.created)) throw new Error("invalid creation time");
+  if (row.exe !== null && row.exe !== undefined && typeof row.exe !== "string") throw new Error("invalid image");
+  return {
+    pid: windowsInteger(row.pid), parent: windowsInteger(row.parent), exe: row.exe ?? null,
+    session: windowsInteger(row.session), created: row.created,
+  };
+}
+
+/** One bounded Win32_Process read of a process and its parent. */
+export function windowsProcessPair(pid, execute = run, options = {}) {
+  if (!validPid(pid)) throw new Error("invalid pid");
+  const output = execute(windowsPowerShellPath(options.env), [
+    "-NoProfile", "-NoLogo", "-NonInteractive", "-Command", windowsProcessScript(pid),
+  ], options.timeoutMs ?? WINDOWS_ACQUISITION_TIMEOUT_MS);
+  const raw = JSON.parse(output);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid process pair");
+  // A Desktop parent seen before a later field fails validation must keep its veto.
+  if (raw.parent && typeof raw.parent === "object" && typeof raw.parent.exe === "string") options.onExecutable?.(raw.parent.exe);
+  return { child: windowsRow(raw.child), parent: windowsRow(raw.parent) };
+}
+
+/** Only a drive-absolute image proves an install directory; UNC, device and relative forms do not. */
+function windowsImage(path) {
+  if (typeof path !== "string") return null;
+  const text = path.replaceAll("/", "\\");
+  return /^[A-Za-z]:\\[^\\]/.test(text) ? win32.normalize(text) : null;
+}
+
 /** Live supervision is evidence, never a durable ownership claim. */
 export function inspectDesktopSupervision(deps = {}) {
   const platform = deps.platform ?? process.platform;
-  if (platform !== "darwin" && platform !== "linux") return { kind: "unsupported" };
+  if (platform !== "darwin" && platform !== "linux" && platform !== "win32") return { kind: "unsupported" };
   let desktopSeen = false;
   const unknown = reason => ({ kind: "unknown", reason, desktopSeen });
-  const seen = executable => { if (basename(executable) === "opencodex-desktop") desktopSeen = true; };
+  const seen = executable => {
+    const name = platform === "win32" ? win32.basename(executable).toLowerCase() : basename(executable);
+    if (name === (platform === "win32" ? WINDOWS_DESKTOP_IMAGE : "opencodex-desktop")) desktopSeen = true;
+  };
   const readPid = deps.readPid ?? readPidFile;
   const readPortPid = deps.readRuntimePortPid ?? readRuntimePortPid;
   const proc = deps.proc ?? procfs;
   const execute = deps.run ?? run;
+  const now = deps.now ?? Date.now;
+  const deadline = now() + WINDOWS_INSPECTION_BUDGET_MS;
+  const readWindowsPair = deps.windowsProcesses
+    ?? ((pid, options) => windowsProcessPair(pid, execute, { ...options, env: deps.env }));
   function identity(pid, parent = false) {
     if (platform === "darwin") return processIdentity(pid, execute, parent ? seen : undefined);
     const executable = proc.exe(pid);
@@ -88,6 +163,33 @@ export function inspectDesktopSupervision(deps = {}) {
     if (!Number.isSafeInteger(parentPid) || parentPid < 0) throw new Error("invalid parent pid");
     return { parent: parentPid, executable: realpathSync(executable) };
   }
+  function windowsCapture(pidFile, portPid, runtimePid) {
+    // Windows has no reaped-parent signal to fall back on, so both runtime records must agree.
+    if (pidFile === null || portPid === null) return { error: "pid-record-missing" };
+    const remaining = deadline - now();
+    if (remaining < WINDOWS_MIN_ACQUISITION_MS) return { error: "probe-timeout" };
+    const pair = readWindowsPair(runtimePid, {
+      onExecutable: seen, timeoutMs: Math.min(WINDOWS_ACQUISITION_TIMEOUT_MS, remaining),
+    });
+    const child = pair?.child ?? null;
+    const parent = pair?.parent ?? null;
+    if (!child) return { error: "process-missing" };
+    if (child.pid !== runtimePid) return { error: "probe-failed" };
+    if (!parent) return { error: "parent-missing" };
+    if (parent.pid !== child.parent) return { error: "probe-failed" };
+    const app = windowsImage(parent.exe);
+    const proxy = windowsImage(child.exe);
+    if (!app || !proxy) return { error: "image-unqualified" };
+    const snapshot = { pidFile, portPid, runtimePid, child, parent };
+    // A reused parent PID belongs to a process created after the runtime it claims to supervise;
+    // its image proves nothing about the real parent, so it cannot answer "none" either.
+    if (BigInt(parent.created) >= BigInt(child.created)) return { error: "creation-order" };
+    if (win32.basename(app).toLowerCase() !== WINDOWS_DESKTOP_IMAGE) return { ...snapshot, kind: "none" };
+    seen(app);
+    if (proxy.toLowerCase() !== win32.join(win32.dirname(app), "ocx.exe").toLowerCase()) return { error: "proxy-mismatch" };
+    if (child.session !== parent.session) return { error: "session-mismatch" };
+    return { ...snapshot, kind: "desktop", app, proxy };
+  }
   function capture() {
     const pidFile = readPid();
     const portPid = readPortPid();
@@ -95,6 +197,10 @@ export function inspectDesktopSupervision(deps = {}) {
     if (pids.some(pid => !validPid(pid))) return { error: "invalid-pid" };
     if (pids.some(pid => pid !== pids[0])) return { error: "pid-mismatch" };
     const runtimePid = pids[0] ?? null;
+    if (platform === "win32") {
+      // Missing records are never positive absence on Windows: they could clear a Desktop veto.
+      return runtimePid === null ? { error: "pid-record-missing" } : windowsCapture(pidFile, portPid, runtimePid);
+    }
     const child = runtimePid !== null ? identity(runtimePid) : null;
     const parent = child && child.parent > 1 ? identity(child.parent, true) : null;
     const snapshot = { pidFile, portPid, runtimePid, child, parent };

package/src/service/health-sentinel-launch.ts

@@ -0,0 +1,176 @@
+/**
+ * Start the opt-in service health sentinel beside a managed service proxy (#6671).
+ *
+ * The sentinel (health-sentinel-main.ts) is a separate process with its own event loop. It asks
+ * this proxy's `/healthz` and, if the proxy stays alive but stops answering, terminates it so the
+ * service manager restarts it. This module decides whether to start one, starts it, and stops it
+ * on shutdown. It never blocks startup: spawning is synchronous and fire-and-forget, and every
+ * failure is logged and ignored.
+ *
+ * Only a managed service child gets a sentinel. A foreground `ocx start` has nobody to restart it,
+ * a desktop sidecar has the app's own supervisor, and a sibling proxy is not the service.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { OcxConfig } from "../types";
+import { serviceHealthRecoveryEnabled } from "../config/feature-flags";
+import { getConfigDir } from "../config/paths";
+import { getRuntimePortPath, readRuntimePort } from "../config/process-state";
+import { isManagedServiceEnvironment } from "../config/serving-runtimes";
+import { didRunDrainStartHooks, registerDrainStartHook, registerOptionalShutdownHook } from "../lib/optional-shutdown-hooks";
+import { isStandaloneBinary } from "../lib/standalone";
+import { HEALTH_SENTINEL_ENV, readRecoveryEntries, type RecoveryEntry } from "./health-sentinel-main";
+import { serviceStatePaths } from "./state";
+
+/** Private argv the compiled binary handles before CLI dispatch (src/cli/index.ts). */
+export const HEALTH_SENTINEL_STANDALONE_ARG = "__health-sentinel";
+export const HEALTH_SENTINEL_HISTORY_FILE = "service-health-recovery.json";
+export const HEALTH_SENTINEL_LOG_FILE = "service-health-sentinel.log";
+/** A recovery this recent is announced by the replacement's first log lines. */
+const RECENT_RECOVERY_NOTICE_MS = 15 * 60_000;
+
+/** Variables the sentinel may inherit. Credentials and proxy settings are deliberately absent. */
+const INHERITED_ENV = [
+  "PATH", "Path", "SystemRoot", "SYSTEMROOT", "windir", "WINDIR", "SystemDrive", "ComSpec",
+  "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "LOCALAPPDATA", "APPDATA", "LANG", "TZ",
+] as const;
+
+export type HealthSentinelLaunchInput = {
+  enabled: boolean;
+  managedService: boolean;
+  standalone: boolean;
+  sibling: boolean;
+  execPath: string;
+  entryPath: string;
+  entryExists: boolean;
+};
+
+export type HealthSentinelLaunchDecision =
+  | { launch: true; argv: string[] }
+  /** `reason` is null when the feature is simply off, so nothing is logged. */
+  | { launch: false; reason: string | null };
+
+export function decideHealthSentinelLaunch(input: HealthSentinelLaunchInput): HealthSentinelLaunchDecision {
+  if (!input.enabled) return { launch: false, reason: null };
+  if (!input.managedService) return { launch: false, reason: "this proxy is not running as the managed service" };
+  if (input.sibling) return { launch: false, reason: "this proxy is a sibling of the service" };
+  if (input.standalone) return { launch: true, argv: [input.execPath, HEALTH_SENTINEL_STANDALONE_ARG] };
+  if (!input.entryExists) return { launch: false, reason: "the sentinel entry is missing from this installation" };
+  return { launch: true, argv: [input.execPath, input.entryPath] };
+}
+
+export function healthSentinelEnvironment(
+  parent: NodeJS.ProcessEnv,
+  paths: { targetPid: number; runtimePath: string; historyPath: string; logPath: string; statePaths: readonly string[] },
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of INHERITED_ENV) {
+    const value = parent[key];
+    if (value !== undefined) env[key] = value;
+  }
+  env[HEALTH_SENTINEL_ENV.targetPid] = String(paths.targetPid);
+  env[HEALTH_SENTINEL_ENV.runtimePath] = paths.runtimePath;
+  env[HEALTH_SENTINEL_ENV.historyPath] = paths.historyPath;
+  env[HEALTH_SENTINEL_ENV.logPath] = paths.logPath;
+  env[HEALTH_SENTINEL_ENV.statePaths] = JSON.stringify(paths.statePaths);
+  const timing = parent[HEALTH_SENTINEL_ENV.timing];
+  if (timing !== undefined) env[HEALTH_SENTINEL_ENV.timing] = timing;
+  return env;
+}
+
+/** The line a replacement prints when the sentinel recently terminated its predecessor. */
+export function recentRecoveryNotice(entries: readonly RecoveryEntry[], selfPid: number, now: number): string | null {
+  const latest = entries.at(-1);
+  if (!latest || latest.pid === selfPid || latest.state === "skipped" || latest.state === "failed") return null;
+  if (now - latest.at < 0 || now - latest.at > RECENT_RECOVERY_NOTICE_MS) return null;
+  const seconds = Math.round((now - latest.at) / 1000);
+  const what = latest.state === "terminated" ? "terminated" : "tried to terminate";
+  return `⚠️  The service health sentinel ${what} the previous proxy (pid ${latest.pid}) ${seconds}s ago because it stopped answering /healthz. Requests it held were not replayed and may already have reached the upstream.`;
+}
+
+type SpawnedSentinel = { pid: number; stdin: unknown; kill(): void; unref(): void };
+
+export type HealthSentinelHandle = { pid: number; stop(): void };
+
+let active: { child: SpawnedSentinel; detachHooks: () => void } | null = null;
+
+export function startServiceHealthSentinel(
+  config: Pick<OcxConfig, "serviceHealthRecovery">,
+  deps: {
+    env?: NodeJS.ProcessEnv;
+    spawn?: (argv: string[], env: Record<string, string>) => SpawnedSentinel;
+    log?: (line: string) => void;
+    now?: () => number;
+  } = {},
+): HealthSentinelHandle | null {
+  const env = deps.env ?? process.env;
+  const log = deps.log ?? ((line: string) => console.log(line));
+  const enabled = serviceHealthRecoveryEnabled(config);
+  if (!enabled) return null;
+  // A drain that already began (a stop or restart during startup) must not gain a sentinel.
+  if (didRunDrainStartHooks()) return null;
+  const configDir = getConfigDir();
+  const historyPath = join(configDir, HEALTH_SENTINEL_HISTORY_FILE);
+  const notice = recentRecoveryNotice(readRecoveryEntries(historyPath) ?? [], process.pid, (deps.now ?? Date.now)());
+  if (notice) log(notice);
+  const entryPath = fileURLToPath(new URL("./health-sentinel-main.ts", import.meta.url));
+  const runtime = readRuntimePort(process.pid);
+  const decision = decideHealthSentinelLaunch({
+    enabled,
+    managedService: isManagedServiceEnvironment(env),
+    standalone: isStandaloneBinary(),
+    sibling: runtime?.siblingOfPort !== undefined,
+    execPath: process.execPath,
+    entryPath,
+    entryExists: existsSync(entryPath),
+  });
+  if (!decision.launch) {
+    if (decision.reason) log(`service health recovery is enabled but not started: ${decision.reason}`);
+    return null;
+  }
+  stopServiceHealthSentinel();
+  const childEnv = healthSentinelEnvironment(env, {
+    targetPid: process.pid,
+    runtimePath: getRuntimePortPath(),
+    historyPath,
+    logPath: join(configDir, HEALTH_SENTINEL_LOG_FILE),
+    statePaths: serviceStatePaths(),
+  });
+  let child: SpawnedSentinel;
+  try {
+    child = (deps.spawn ?? ((argv, childEnvironment) => Bun.spawn(argv, {
+      // The sentinel's stdin is this process's lifeline: it sees EOF when this process exits.
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+      env: childEnvironment,
+      windowsHide: true,
+    })))(decision.argv, childEnv);
+  } catch (error) {
+    log(`service health recovery could not start its sentinel: ${error instanceof Error ? error.name : "error"}`);
+    return null;
+  }
+  child.unref();
+  // Keep the subprocess and its stdin sink referenced for this process's lifetime.
+  const handle = { child, detachHooks: () => {} };
+  active = handle;
+  // Withdraw as soon as any drain begins: a deliberate stop whose drain stalls must stay a stop.
+  const detachDrain = registerDrainStartHook("service-health-sentinel", stopServiceHealthSentinel);
+  const detachShutdown = registerOptionalShutdownHook("service-health-sentinel", stopServiceHealthSentinel);
+  handle.detachHooks = () => { detachDrain(); detachShutdown(); };
+  log(`service health recovery: sentinel pid ${child.pid} watches this proxy (pid ${process.pid})`);
+  return { pid: child.pid, stop: stopServiceHealthSentinel };
+}
+
+/** Stop the sentinel before a deliberate shutdown so it never judges a draining process. */
+export function stopServiceHealthSentinel(): void {
+  const current = active;
+  if (!current) return;
+  active = null;
+  current.detachHooks();
+  try { current.child.kill(); } catch { /* already gone */ }
+  const sink = current.child.stdin as { end?: () => unknown } | null;
+  try { sink?.end?.(); } catch { /* already closed */ }
+}