@bitkyc08/opencodex 2.83.0 → 2.86.0

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 */ }
+}