@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/service/guards.ts

@@ -2,14 +2,12 @@ import { execSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { getConfigDir, loadConfig } from "../config";
 import { withConfigMutationLockSync } from "../config/mutation-lock";
-import { hardenReusedServiceApiToken, readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { hardenReusedServiceApiToken, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
 import { randomBytes } from "node:crypto";
 import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
-import { diagnoseService } from "./diagnostics";
-import type { ServiceDiagnostic } from "./diagnostics";
 import { currentCodexHome, currentOpenCodexHome, resolveServiceState, serviceCodexHomeMatchesInstall, servicePathMatchesInstall } from "./state";
 import { resolveCodexSqliteHome } from "../codex/paths";
 import type { CodexHomeDeps } from "../codex/home";
@@ -76,20 +74,6 @@ export function assertServiceEnvironmentMatchesInstall(deps: CodexHomeDeps = {})
   }
 }
 
-/**
- * The `ocx` command a user should rerun for the service state they actually have.
- *
- * `installed` alone is not enough: `repairService()` refuses a Task-Scheduler-plus-WinSW
- * conflict outright, so recommending repair there names a command guaranteed to fail.
- * Install IS the valid conflict recovery, because `installWindows` removes the native
- * backend first. Exported so the guard tests the real selector rather than a copy of it.
- */
-export function serviceRetryCommand(
-  diag: Pick<ServiceDiagnostic, "installed" | "conflict"> = diagnoseService(),
-): string {
-  return diag.installed && !diag.conflict ? "ocx service repair" : "ocx service install";
-}
-
 /**
  * Refuse a management (admin) token as the data-plane secret.
  *
@@ -139,50 +123,6 @@ export function assertNotAdminToken(
   );
 }
 
-/**
- * Preflight for `service install` / `service repair` on the data-plane credential.
- *
- * It used to DEMAND `OPENCODEX_API_AUTH_TOKEN` for a non-loopback hostname, and it threw
- * even when `~/.opencodex/service-api-token` already held a perfectly good token. That is
- * the defect behind the incident this unit exists to close (#4236): an operator exported the
- * ADMIN token as OPENCODEX_API_AUTH_TOKEN because `install` asked for a token, the hub then
- * crash-looped on `assertNotAdminToken`, and `service repair` asked for the same env var
- * again — so the only remembered way to make the command proceed was the thing that broke it.
- *
- * Nobody should have to export a token by hand to run a hub. {@link writeServiceApiTokenFile}
- * provisions one, so the only conditions left that install cannot fix are an admin-token
- * collision in the environment and a token file that exists but cannot be used.
- */
-export function assertServiceAuthEnvironment(): void {
-  const config = loadConfig();
-  // Both collision checks come BEFORE the loopback short-circuit, because the launch wrapper
-  // exports the token file unconditionally (`buildServiceShellCommand` cats it whenever it
-  // exists, whatever the hostname): a management token in either source fences the whole
-  // management plane closed at boot, even on a loopback install that needs no admission
-  // secret. Returning early is what let that broken state through.
-  const present = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
-  if (present) assertNotAdminToken(present);
-  const state = readServiceApiTokenState();
-  // An existing FILE holding the admin token is the incident shape itself, and the first round
-  // only checked the env var — so install/repair reused it and the hub crash-looped at boot.
-  // On a machine connected to a hub this same file holds that hub's issued client key, which
-  // is never a management token, so the check is a no-op there.
-  if (state.kind === "present") assertNotAdminToken(state.token, process.env, "file");
-  if (isLoopbackHostname(config.hostname)) return;
-  if (present) return;
-  // Absent is fine — install/repair generates one below. `unsafe` is not: the writer refuses
-  // to replace a path it cannot vouch for, so say so here, where the operator can still act,
-  // instead of failing mid-install. Reached from `service repair` as well as `install`, so
-  // name a command that can actually succeed (see serviceRetryCommand).
-  if (state.kind !== "unsafe") return;
-  const diag = diagnoseService();
-  throw new Error(
-    `The data-plane token file cannot be used (${state.reason}): ${serviceApiTokenFilePath()}. `
-      + `Move it aside, then rerun \`${serviceRetryCommand(diag)}\`; the service provisions a `
-      + "fresh owner-only token and needs nothing from the environment.",
-  );
-}
-
 /** How the data-plane token the service will export was obtained. */
 export type ServiceApiTokenOrigin = "env" | "file" | "generated";
 

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

@@ -0,0 +1,112 @@
+/** Linux pidfd ownership for the opt-in sentinel. Loaded only on Linux. */
+import { dlopen, FFIType, read } from "bun:ffi";
+import type { TerminateResult } from "./health-sentinel-main";
+
+const ESRCH = 3;
+const ENOSYS = 38;
+// Syscalls from 424 onward share one number on every Linux architecture. Binding is limited to
+// x64/arm64 because the FFI signature below assumes their LP64 integer-register calling convention.
+const SYS_PIDFD_OPEN = 434;
+const SYS_PIDFD_SEND_SIGNAL = 424;
+
+type CallResult = { value: number; errno: number };
+export type PidfdSyscalls = {
+  open(pid: number): CallResult;
+  signal(fd: number, signal: number): CallResult;
+  close(fd: number): void;
+  dispose(): void;
+};
+export type ParentPidfd = { terminate(): TerminateResult; close(): void };
+export type ParentPidfdResult =
+  | { kind: "bound"; handle: ParentPidfd }
+  | { kind: "unsupported"; reason: string }
+  | { kind: "refused"; reason: string };
+
+function nativeSyscalls(): PidfdSyscalls {
+  const symbols = {
+    // syscall is variadic, but these syscalls use integer/pointer arguments only. All supplied
+    // slots are machine-word integers (including zero for siginfo and flags), on these LP64 ABIs.
+    syscall: { args: [FFIType.i64, FFIType.i64, FFIType.i64, FFIType.i64, FFIType.i64], returns: FFIType.i64 },
+    __errno_location: { args: [], returns: FFIType.ptr },
+    close: { args: [FFIType.i32], returns: FFIType.i32 },
+  } as const;
+  const load = (path: string) => dlopen(path, symbols);
+  let libc: ReturnType<typeof load>;
+  try {
+    libc = load("libc.so.6");
+  } catch {
+    // musl exports libc symbols through its loader; it has no glibc soname or pidfd wrappers.
+    libc = load(`/lib/ld-musl-${process.arch === "x64" ? "x86_64" : "aarch64"}.so.1`);
+  }
+  const call = (nr: number, a: number, b: number, c = 0, d = 0): CallResult => {
+    const value = Number(libc.symbols.syscall(nr, a, b, c, d));
+    return { value, errno: value === -1 ? read.i32(libc.symbols.__errno_location()!) : 0 };
+  };
+  return {
+    open: pid => call(SYS_PIDFD_OPEN, pid, 0),
+    signal: (fd, signal) => call(SYS_PIDFD_SEND_SIGNAL, fd, signal),
+    // Never retry close on Linux: even an EINTR has released the descriptor.
+    close: fd => { libc.symbols.close(fd); },
+    dispose: () => libc.close(),
+  };
+}
+
+/** Acquire before arming; reparenting during acquisition invalidates even a successfully opened fd. */
+export function openParentPidfd(
+  pid: number,
+  isParent: () => boolean,
+  options: { arch?: string; load?: () => PidfdSyscalls } = {},
+): ParentPidfdResult {
+  if (!isParent()) return { kind: "refused", reason: "the sentinel is not the watched process's child" };
+  const arch = options.arch ?? process.arch;
+  if (arch !== "x64" && arch !== "arm64") return { kind: "unsupported", reason: `pidfd syscall ABI is unsupported on ${arch}` };
+  let api: PidfdSyscalls;
+  try { api = (options.load ?? nativeSyscalls)(); }
+  catch { return { kind: "refused", reason: "Linux pidfd libc binding is unavailable" }; }
+  let fd: number | null = null;
+  let closed = false;
+  let signalled = false;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try { if (fd !== null) api.close(fd); } finally { api.dispose(); }
+  };
+  const refuse = (reason: string): ParentPidfdResult => { close(); return { kind: "refused", reason }; };
+  try {
+    const opened = api.open(pid);
+    if (opened.value < 0) {
+      close();
+      return opened.errno === ENOSYS
+        ? { kind: "unsupported", reason: "pidfd_open is unsupported by this kernel" }
+        : { kind: "refused", reason: `pidfd_open failed (errno ${opened.errno})` };
+    }
+    fd = opened.value;
+    if (!isParent()) return refuse("the watched parent exited during pidfd acquisition");
+    // Check both syscall support and permission before arming, without sending a signal.
+    const probe = api.signal(fd, 0);
+    if (probe.value < 0) {
+      close();
+      return probe.errno === ENOSYS
+        ? { kind: "unsupported", reason: "pidfd_send_signal is unsupported by this kernel" }
+        : { kind: "refused", reason: `pidfd signal check failed (errno ${probe.errno})` };
+    }
+    if (!isParent()) return refuse("the watched parent exited during pidfd verification");
+    return {
+      kind: "bound",
+      handle: {
+        close,
+        terminate: () => {
+          if (closed || signalled) return "not_target";
+          // A throwing binding must settle the recorded intent as "failed", like process.kill does.
+          let sent: CallResult;
+          try { sent = api.signal(fd!, 9); } catch { return "failed"; }
+          if (sent.value < 0) return sent.errno === ESRCH ? "not_target" : "failed";
+          signalled = true;
+          return "terminated";
+        },
+      },
+    };
+  } catch {
+    return refuse("Linux pidfd binding failed");
+  }
+}

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

@@ -12,11 +12,10 @@
  * - Windows reuses ids quickly, so the sentinel opens a handle on its parent at startup, accepts it
  *   only if that process was created before the sentinel, and terminates through the handle
  *   (health-sentinel-windows.ts). While the handle is open the id cannot be reused.
- * - POSIX allocates ids sequentially, and the sentinel's live `process.ppid` changes the moment
- *   its parent exits, before the exited parent can be reaped and its id freed. It is the last check
- *   before `kill`. Reuse inside that window needs the parent to exit, be reaped, and the id space to
- *   wrap completely (99,999 ids on macOS, `pid_max` on Linux) between two adjacent syscalls; that
- *   residual is accepted and documented in structure/ops/service-health-recovery.md.
+ * - Linux holds a pidfd after rechecking the live parent relationship, and signals that fd.
+ *   Only unsupported kernels/architectures retain the live-ppid fallback used by macOS.
+ * - macOS checks the live parent id immediately before SIGKILL; PID reuse between those two
+ *   syscalls remains a documented residual (structure/ops/service-health-recovery.md).
  *
  * SIGKILL rather than SIGTERM: a proxy whose event loop is stuck cannot run its own SIGTERM
  * handler, and systemd counts a SIGTERM death as a clean exit that `Restart=on-failure` does not
@@ -38,7 +37,7 @@ import {
   type HealthProbeOutcome,
   type HealthSentinelTiming,
 } from "./health-sentinel-policy";
-import { probeHealth, type HealthProbeTarget } from "./health-sentinel-probe";
+import { probeHealth, probeUrlHost, type HealthProbeTarget } from "./health-sentinel-probe";
 
 export const HEALTH_SENTINEL_ENV = {
   targetPid: "OCX_HEALTH_SENTINEL_TARGET_PID",
@@ -80,6 +79,8 @@ export type HealthSentinelDeps = {
   isTargetGone(): boolean;
   /** Bind to the target once at startup; a failure stands the sentinel down. */
   bindTarget(): { ok: true } | { ok: false; reason: string };
+  /** Release the process owner on every exit, refusal, cancellation or exception. */
+  closeTarget(): void;
   /** Terminate the bound target, re-proving it is still the target at the last moment. */
   terminateTarget(): TerminateResult;
   /** Run under the ownership mutation lease, released on return; "busy" when it could not be taken promptly. */
@@ -143,7 +144,17 @@ type Attempt =
   | { kind: "gone" }
   | { kind: "intent"; entry: RecoveryEntry };
 
+function matchesProbeTarget(runtime: SentinelRuntimeRecord | null, pid: number, target: HealthProbeTarget): boolean {
+  return runtime !== null && runtime.pid === pid && !runtime.sibling
+    && runtime.port === target.port && probeUrlHost(runtime.hostname) === target.hostname;
+}
+
 export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<HealthSentinelResult> {
+  try { return await observeHealthSentinel(deps); }
+  finally { deps.closeTarget(); }
+}
+
+async function observeHealthSentinel(deps: HealthSentinelDeps): Promise<HealthSentinelResult> {
   const timing: HealthSentinelTiming = { ...DEFAULT_HEALTH_SENTINEL_TIMING, ...deps.timing };
   const standDown = (reason: string): HealthSentinelResult => {
     deps.log(`standing down: ${reason} (pid ${deps.targetPid})`);
@@ -162,12 +173,18 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
     recoveryHistory: history,
     timing,
   });
+  let pinnedTarget: HealthProbeTarget | null = null;
   for (;;) {
     if (deps.isTargetGone()) return { outcome: "target_exited" };
     const runtime = deps.readRuntime();
     if (!runtime || runtime.pid !== deps.targetPid) return standDown("the runtime record no longer names the watched process");
     if (runtime.sibling) return standDown("the watched process is a sibling proxy");
-    const outcome = await raceGone(deps.probe({ hostname: runtime.hostname ?? "", port: runtime.port }, timing.probeTimeoutMs), exitSignal);
+    const hostname = probeUrlHost(runtime.hostname);
+    if (hostname === null) return standDown("the recorded bind address is not numeric; DNS names cannot authorize recovery");
+    const target: HealthProbeTarget = pinnedTarget ?? { hostname, port: runtime.port };
+    if (!matchesProbeTarget(runtime, deps.targetPid, target)) return standDown("the recorded probe endpoint changed");
+    pinnedTarget = target;
+    const outcome = await raceGone(deps.probe(target, timing.probeTimeoutMs), exitSignal);
     if (outcome === GONE) return { outcome: "target_exited" };
     const wasArmed = policy.state().armed;
     const decision = policy.observe(outcome);
@@ -178,7 +195,7 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
         // Everything that could have changed during the probe is re-read under the lease.
         if (deps.isTargetGone()) return { kind: "gone" };
         const current = deps.readRuntime();
-        if (!current || current.pid !== deps.targetPid || current.port !== runtime.port || current.sibling) {
+        if (!matchesProbeTarget(current, deps.targetPid, target)) {
           return { kind: "stand_down", reason: "the runtime record changed while the target was unresponsive" };
         }
         // Persist first: an attempted recovery must count toward the cap, and on Windows this
@@ -202,7 +219,10 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
         const { entry } = attempt;
         // The lease, history and log work above takes time. Re-check that the evidence is still
         // fresh right before the irreversible step: a proxy that recovered meanwhile must not be
-        // killed on old observations. A clock that ran backwards makes the evidence stale too.
+        // killed on old observations. A clock that ran backwards makes the evidence stale too. The
+        // final runtime-record read is included before the freshness check so time spent on it
+        // cannot authorize termination on stale observations.
+        const finalRuntime = deps.readRuntime();
         const evidenceAge = deps.now() - outcome.endedAt;
         if (evidenceAge < 0 || evidenceAge > timing.maxEvidenceAgeMs || deps.isTargetGone()) {
           settle({ ...entry, state: "skipped" });
@@ -211,6 +231,10 @@ export async function runHealthSentinel(deps: HealthSentinelDeps): Promise<Healt
           if (await raceGone(deps.sleep(policy.nextDelayMs()), exitSignal) === GONE) return { outcome: "target_exited" };
           continue;
         }
+        if (!matchesProbeTarget(finalRuntime, deps.targetPid, target)) {
+          settle({ ...entry, state: "skipped" });
+          return standDown("the recorded probe endpoint changed before termination");
+        }
         const result = deps.terminateTarget();
         if (result === "not_target") {
           settle({ ...entry, state: "skipped" });
@@ -329,6 +353,7 @@ export function readSentinelRuntime(path: string): SentinelRuntimeRecord | null
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
     const { pid, port, hostname } = parsed;
+    if (hostname !== undefined && typeof hostname !== "string") return null;
     if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return null;
     if (typeof port !== "number" || !Number.isSafeInteger(port) || port <= 0 || port > 65_535) return null;
     return { pid, port, ...(typeof hostname === "string" ? { hostname } : {}), sibling: parsed.siblingOfPort !== undefined };
@@ -388,59 +413,72 @@ export async function runHealthSentinelProcess(env: NodeJS.ProcessEnv = process.
     if (opened.ok) windowsHandle = opened.handle;
     else windowsBindFailure = opened.reason;
   }
+  let linuxHandle: import("./health-sentinel-linux").ParentPidfd | null = null;
+  let linuxBindFailure: string | null = null;
+  if (process.platform === "linux") {
+    const { openParentPidfd } = await import("./health-sentinel-linux");
+    const opened = openParentPidfd(targetPid, () => !gone && process.ppid === targetPid);
+    if (opened.kind === "bound") linuxHandle = opened.handle;
+    else if (opened.kind === "refused") linuxBindFailure = opened.reason;
+    else appendBoundedLog(logPath, `pidfd unavailable: ${opened.reason}; using live parent PID check`);
+  }
   const lag = startLagMonitor();
-  const result = await runHealthSentinel({
-    targetPid,
-    now: Date.now,
-    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
-    probe: async (target, timeoutMs) => {
-      lag.reset();
-      const outcome = await probeHealth(target, timeoutMs);
-      return outcome.kind === "timeout" ? { ...outcome, sentinelLagMs: lag.read() } : outcome;
-    },
-    readRuntime: () => readSentinelRuntime(runtimePath),
-    targetExited,
-    isTargetGone: () => gone || (windowsHandle?.exited() ?? false),
-    bindTarget: () => {
-      // POSIX: Bun reads the parent id live, and it stops naming the proxy once the proxy exits.
-      // Windows: it is the creating parent's id, so the handle below carries the identity.
-      if (process.ppid !== targetPid) return { ok: false, reason: "the sentinel is not the watched process's child" };
-      if (process.platform !== "win32") return { ok: true };
-      return windowsHandle ? { ok: true } : { ok: false, reason: windowsBindFailure ?? "the parent process cannot be opened" };
-    },
-    terminateTarget: () => {
-      if (process.platform === "win32") {
-        if (!windowsHandle) return "failed";
-        return windowsHandle.terminate(1) ? "terminated" : "failed";
-      }
-      if (gone || process.ppid !== targetPid) return "not_target";
-      try {
-        process.kill(targetPid, "SIGKILL");
-        return "terminated";
-      } catch {
-        return "failed";
-      }
-    },
-    withOwnershipLease: run => {
-      let lease: { release(): void };
-      try {
-        lease = acquireOwnershipMutationLease(statePaths, { waitMs: LEASE_WAIT_MS, processImage: () => null });
-      } catch {
-        return "busy";
-      }
-      try { return run(); } finally { lease.release(); }
-    },
-    readHistory: () => {
-      const entries = readRecoveryEntries(historyPath);
-      return entries === null ? null : countedRecoveryTimes(entries);
-    },
-    writeHistory: entry => writeRecoveryEntry(historyPath, entry),
-    log: line => appendBoundedLog(logPath, line),
-    timing: parseTimingOverride(env[HEALTH_SENTINEL_ENV.timing]),
-  });
-  lag.stop();
-  windowsHandle?.close();
-  void result;
+  try {
+    await runHealthSentinel({
+      targetPid,
+      now: Date.now,
+      sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+      probe: async (target, timeoutMs) => {
+        lag.reset();
+        const outcome = await probeHealth(target, timeoutMs);
+        return outcome.kind === "timeout" ? { ...outcome, sentinelLagMs: lag.read() } : outcome;
+      },
+      readRuntime: () => readSentinelRuntime(runtimePath),
+      targetExited,
+      closeTarget: () => { linuxHandle?.close(); windowsHandle?.close(); },
+      isTargetGone: () => gone || (windowsHandle?.exited() ?? false),
+      bindTarget: () => {
+        // POSIX: Bun reads the parent id live, and it stops naming the proxy once the proxy exits.
+        // Windows: it is the creating parent's id, so the handle below carries the identity.
+        if (process.ppid !== targetPid) return { ok: false, reason: "the sentinel is not the watched process's child" };
+        if (linuxBindFailure) return { ok: false, reason: linuxBindFailure };
+        if (process.platform !== "win32") return { ok: true };
+        return windowsHandle ? { ok: true } : { ok: false, reason: windowsBindFailure ?? "the parent process cannot be opened" };
+      },
+      terminateTarget: () => {
+        if (process.platform === "win32") {
+          if (!windowsHandle) return "failed";
+          return windowsHandle.terminate(1) ? "terminated" : "failed";
+        }
+        if (gone || process.ppid !== targetPid) return "not_target";
+        if (linuxHandle) return linuxHandle.terminate();
+        try {
+          process.kill(targetPid, "SIGKILL");
+          return "terminated";
+        } catch {
+          return "failed";
+        }
+      },
+      withOwnershipLease: run => {
+        let lease: { release(): void };
+        try {
+          lease = acquireOwnershipMutationLease(statePaths, { waitMs: LEASE_WAIT_MS, processImage: () => null });
+        } catch {
+          return "busy";
+        }
+        try { return run(); } finally { lease.release(); }
+      },
+      readHistory: () => {
+        const entries = readRecoveryEntries(historyPath);
+        return entries === null ? null : countedRecoveryTimes(entries);
+      },
+      writeHistory: entry => writeRecoveryEntry(historyPath, entry),
+      log: line => appendBoundedLog(logPath, linuxHandle && line.startsWith("watching pid ") ? `${line} (pidfd)` : line),
+      timing: parseTimingOverride(env[HEALTH_SENTINEL_ENV.timing]),
+    });
+  } finally {
+    lag.stop();
+  }
   return 0;
 }
 

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

@@ -7,6 +7,9 @@
  * response framing and an absolute deadline. Only the timing decides liveness; the body's `pid`
  * lets the policy tell the target from another process that took the port.
  */
+import { isIP } from "node:net";
+
+import { isWildcardHostname } from "../codex/loopback-target";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import type { HealthProbeOutcome } from "./health-sentinel-policy";
 
@@ -17,12 +20,24 @@ export type HealthProbeIo = {
   fetch?: (url: string, timeoutMs: number) => Promise<Response>;
 };
 
-/** The URL host to dial for a recorded listen hostname: wildcard binds answer on loopback. */
-export function probeUrlHost(hostname: string | undefined): string {
-  const value = (hostname ?? "").trim().replace(/^\[|\]$/g, "");
-  if (!value || value === "0.0.0.0" || value === "localhost") return "127.0.0.1";
-  if (value === "::") return "[::1]";
-  return value.includes(":") ? `[${value}]` : value;
+/**
+ * Numeric probe endpoint only; unknown DNS destinations cannot authorize recovery. Wildcard
+ * spellings use the server's own predicate (`*`, `0`, `00.0.0.000`, `::0`, ...), so every bind
+ * the server accepts as a wildcard is probed on loopback instead of standing the sentinel down.
+ */
+export function probeUrlHost(hostname: string | undefined): string | null {
+  let value = (hostname ?? "").trim();
+  if (isWildcardHostname(value)) return value.includes(":") ? "[::1]" : "127.0.0.1";
+  if (value.startsWith("[") || value.endsWith("]")) {
+    if (!value.startsWith("[") || !value.endsWith("]")) return null;
+    value = value.slice(1, -1);
+    if (isIP(value) !== 6) return null;
+  }
+  if (!value || value === "0.0.0.0" || /^localhost\.?$/i.test(value)) return "127.0.0.1";
+  if (isIP(value) === 4) return value;
+  if (isIP(value) !== 6 || value.includes("%")) return null;
+  const host = new URL(`http://[${value}]/`).hostname;
+  return host === "[::]" ? "[::1]" : host;
 }
 
 /** `pid` from a `/healthz` JSON body, or null when the body does not carry one. */
@@ -39,8 +54,10 @@ export async function probeHealth(target: HealthProbeTarget, timeoutMs: number,
   const now = io.now ?? Date.now;
   const fetchFn = io.fetch ?? ((url: string, deadlineMs: number) => directLocalHttpFetch(url, { headers: { accept: "application/json" } }, { timeoutMs: deadlineMs }));
   const startedAt = now();
+  const hostname = probeUrlHost(target.hostname);
+  if (hostname === null) return { kind: "error", startedAt, endedAt: now() };
   try {
-    const response = await fetchFn(`http://${probeUrlHost(target.hostname)}:${target.port}/healthz`, timeoutMs);
+    const response = await fetchFn(`http://${hostname}:${target.port}/healthz`, timeoutMs);
     // The framed body is already in memory; reading it cannot wait on the target.
     const body = await response.text().catch(() => "");
     return { kind: "answered", pid: healthzPid(body), startedAt, endedAt: now() };

package/src/service/health.ts

@@ -1,77 +1,18 @@
-import { win32 } from "node:path";
 import { loadConfig } from "../config";
-import { serviceApiTokenFilePath } from "../lib/service-secrets";
-import { PROXY_ENV_KEYS } from "../lib/proxy-env";
+import { resolveServiceListenPort } from "./definition";
 import { proxyIdentityAt } from "../server/proxy-liveness";
 import { launchdListenPort } from "./launchd";
 import { serviceLogPath } from "./state";
 import { systemdListenPort } from "./systemd";
 import { windowsListenPort, winswListenPort } from "./windows-ops";
 
-export function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
-/**
- * Listen port baked into service wrappers / WinSW XML.
- * Priority: explicit override → OCX_BAKE_PORT (update restart) → config.port → 10100.
- * `config.port === 0` means ephemeral for interactive start; services need a stable pin,
- * so treat 0 / invalid like unset (default 10100) instead of baking `--port 0`.
- */
-export function resolveServiceListenPort(override?: number): number {
-  if (typeof override === "number" && Number.isFinite(override) && override > 0 && override <= 65535) {
-    return Math.trunc(override);
-  }
-  const baked = process.env.OCX_BAKE_PORT?.trim();
-  if (baked && /^\d+$/.test(baked)) {
-    const n = Number(baked);
-    if (n > 0 && n <= 65535) return n;
-  }
-  const configured = loadConfig().port;
-  if (typeof configured === "number" && configured > 0 && configured <= 65535) return configured;
-  return 10100;
-}
-
-export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
-  const tokenFile = serviceApiTokenFilePath();
-  const args = cli ? `${shellQuote(cli)} start` : "start";
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
-}
-
-/**
- * The same command shape, launched through a stable `ocx` executable instead of an
- * explicit Bun + CLI pair. The token-file preamble is identical and deliberately shared
- * in form: the service still reads the token from disk at start and never carries it in
- * the unit.
- */
-export function buildServiceLauncherShellCommand(launcher: string, port = resolveServiceListenPort()): string {
-  const tokenFile = serviceApiTokenFilePath();
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(launcher)} start --port ${port}`;
-}
-
-/**
- * Shared tail parser for the baked `--port <n>`.
- *
- * Terminators cover all three artifact shapes: whitespace (batch wrapper, systemd
- * unit), `"` (systemd's quoted ExecStart), `<` (WinSW's `</arguments>`), and `&` (an
- * XML-escaped quote). Matched LAST because every artifact carries the Bun and CLI
- * paths ahead of the argument, and a path containing the literal must not shadow it.
- */
-export function parseBakedListenPort(read: () => string): number | null {
-  try {
-    const last = [...read().matchAll(/start --port (\d{1,5})(?:\s|"|&|<|$)/gm)].at(-1);
-    if (!last) return null;
-    const n = Number(last[1]);
-    return n > 0 && n <= 65535 ? n : null;
-  } catch {
-    return null;
-  }
-}
+export { resolveServiceListenPort };
+export { shellQuote, buildServiceShellCommand, buildServiceLauncherShellCommand, parseBakedListenPort, resolvedProxyEnv } from "./definition";
 
 /**
  * The listen port of the INSTALLED service artifact, falling back to the configured
- * one. Each reader returns null off its own platform, so the chain needs no platform
- * branch — and on Windows both return null, preserving today's behavior.
+ * one. This historical artifact chain can read retained files from another platform;
+ * platform-specific launchd command checks instead use only the plist and configured port.
  */
 export function installedServiceListenPort(): number {
   return launchdListenPort()
@@ -239,28 +180,3 @@ export async function reportServiceServing(
 export function serviceRepairCommand(): string {
   return "ocx service repair";
 }
-
-/**
- * Outbound proxy settings the installing shell had, resolved for baking into a service
- * definition.
- *
- * A service manager does not inherit the environment of the shell that installed it, and
- * `ExecStart=/bin/sh -lc` is dash on Ubuntu/WSL — login dash reads `.profile`, not
- * `.bashrc`, which is where proxy exports usually live. So a user who needs a proxy to
- * reach the upstream got a service that dialed direct: the socket was reset, the retry
- * budget drained, and the request surfaced as `502 Provider unreachable` (#2107). The
- * same install driven through `ocx codex-shim` worked, because that path spawns with
- * `{ ...process.env }`.
- *
- * Lower-case variants are honored because curl-style tooling sets them and the runtime's
- * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
- * upper-case name is baked, so a definition never carries two spellings of one setting.
- */
-export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
-  const resolved: { name: string; value: string }[] = [];
-  for (const key of PROXY_ENV_KEYS) {
-    const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
-    if (value) resolved.push({ name: key, value });
-  }
-  return resolved;
-}