@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/server/search.ts

@@ -11,20 +11,30 @@
 import { formatErrorResponse } from "../bridge";
 import {
   CodexAccountCooldownError,
+  codexMainProfileDrainingResponse,
   cooldownErrorResponse,
   CodexAuthContextError,
+  CodexMainProfileDrainingError,
   CodexPoolAuthenticationError,
   CodexThreadAffinityExpiredError,
 } from "../codex/auth-context";
+import { codexAccountNamespaceForModel } from "../codex/account-namespace-match";
 import { formatCodexProviderForLog } from "../codex/routing";
 import { signalWithTimeout } from "../lib/abort";
 import { sidecarEnter } from "../lib/sidecar-tracker";
 import type { OcxConfig } from "../types";
-import { listOpenAiForwardSidecarCandidates, resolveFirstUsableOpenAiSidecar } from "../providers/openai-sidecar";
+import {
+  listOpenAiForwardSidecarCandidates,
+  resolveFirstUsableOpenAiSidecar,
+  type ExactOpenAiSidecarAccount,
+} from "../providers/openai-sidecar";
+import { routeModel } from "../router";
 import { readJsonRequestBody } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
 import type { RequestLogContext } from "./request-log";
 import { codexLogAccountId, decodeRequestErrorResponse } from "./responses";
+import type { AdmissionLease } from "../lib/admission";
+import { codexAccountSelectionForTurn } from "./lifecycle";
 
 /**
  * Default TOTAL deadline for one search relay. alpha/search is non-streaming JSON — response
@@ -40,6 +50,7 @@ export async function handleSearch(
   req: Request,
   config: OcxConfig,
   logCtx: RequestLogContext,
+  turnAdmissionLease?: AdmissionLease,
 ): Promise<Response> {
   try { validateForwardAdmissionCredential(req.headers, config); }
   catch (err) {
@@ -55,6 +66,32 @@ export async function handleSearch(
   const model = (body as { model?: unknown } | null)?.model;
   if (typeof model === "string" && model) logCtx.model = model;
 
+  let exactAccount: ExactOpenAiSidecarAccount | undefined;
+  let relayBody = body;
+  const accountNamespace = typeof model === "string"
+    ? codexAccountNamespaceForModel(config.codexAccountNamespaces, model)
+    : undefined;
+  if (accountNamespace && typeof model === "string") {
+    try {
+      const route = routeModel(config, model);
+      if (!route.codexAccountId || route.codexAccountNamespace !== accountNamespace) {
+        return formatErrorResponse(400, "invalid_request_error", "Invalid Codex account-qualified search model");
+      }
+      exactAccount = { accountId: route.codexAccountId, modelId: route.modelId };
+      logCtx.provider = `${route.providerName}-${accountNamespace}`;
+      logCtx.routeDecision = route.routeDecision;
+      // The ChatGPT search endpoint only understands the native model slug. The
+      // account namespace is proxy routing syntax and must not cross the wire.
+      relayBody = { ...(body as Record<string, unknown>), model: route.modelId };
+    } catch (err) {
+      return formatErrorResponse(
+        400,
+        "invalid_request_error",
+        err instanceof Error ? err.message : "Invalid Codex account-qualified search model",
+      );
+    }
+  }
+
   const candidates = listOpenAiForwardSidecarCandidates(config);
   if (candidates.length === 0) {
     return formatErrorResponse(
@@ -67,7 +104,10 @@ export async function handleSearch(
 
   let upstream: Awaited<ReturnType<typeof resolveFirstUsableOpenAiSidecar>>;
   try {
-    upstream = await resolveFirstUsableOpenAiSidecar(candidates, req.headers, config);
+    upstream = await resolveFirstUsableOpenAiSidecar(candidates, req.headers, config, {
+      exactAccount,
+      beginCodexAccountSelection: codexAccountSelectionForTurn(turnAdmissionLease),
+    });
     if (!upstream) {
       return formatErrorResponse(
         401,
@@ -75,16 +115,21 @@ export async function handleSearch(
         "web search relay needs ChatGPT auth (Authorization header)",
       );
     }
-    logCtx.provider = formatCodexProviderForLog(upstream.providerName, codexLogAccountId(upstream.authContext), config);
+    logCtx.provider = accountNamespace
+      ? `${upstream.providerName}-${accountNamespace}`
+      : formatCodexProviderForLog(upstream.providerName, codexLogAccountId(upstream.authContext), config);
   } catch (err) {
     if (err instanceof CodexAccountCooldownError) {
-      return cooldownErrorResponse(err);
+      return cooldownErrorResponse(err, Date.now(), accountNamespace);
     }
+    if (err instanceof CodexMainProfileDrainingError) return codexMainProfileDrainingResponse();
     if (err instanceof CodexThreadAffinityExpiredError) {
       return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
     }
     if (err instanceof CodexAuthContextError) {
-      const safeAccountLabel = formatCodexProviderForLog("openai", err.accountId, config);
+      const safeAccountLabel = accountNamespace
+        ? `openai-${accountNamespace}`
+        : formatCodexProviderForLog("openai", err.accountId, config);
       console.error(`[search] Pool account ${safeAccountLabel} token failed; reauthentication required`);
       return formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication");
     }
@@ -103,7 +148,7 @@ export async function handleSearch(
     const upstreamResponse = await fetch(url, {
       method: "POST",
       headers,
-      body: JSON.stringify(body),
+      body: JSON.stringify(relayBody),
       signal: linkedSignal.signal,
     });
     const payload = await upstreamResponse.arrayBuffer();

package/src/server/sse-payload-rewrite.ts

@@ -9,6 +9,56 @@ import type { TranslatorBudget } from "../lib/translator-budget";
 
 export type SsePayloadRewrite = (payload: string) => string;
 
+/**
+ * Block-level SSE rewrite: maps one complete SSE event block (without its
+ * blank-line delimiter) to zero or more replacement blocks. This is the
+ * contract lifecycle repair needs: injecting missing canonical events
+ * (#893) is impossible in the one-payload-in/one-payload-out model.
+ *
+ * `dispose` releases any retained state (budget-charged collectors) when the
+ * relay tears down — terminal, EOF, cancel, or error. Relays call it exactly
+ * once per teardown path.
+ */
+export type SseBlockRewrite = ((block: string) => readonly string[]) & {
+  dispose?: () => void;
+};
+
+/** Adapt a payload rewrite to the block contract (replace only on change). */
+export function payloadRewriteAsBlockRewrite(rewrite: SsePayloadRewrite): SseBlockRewrite {
+  return (block) => {
+    const payload = sseDataPayload(block);
+    if (payload === null) return [block];
+    const rewritten = rewrite(payload);
+    return rewritten !== payload ? [replaceSseDataPayload(block, rewritten)] : [block];
+  };
+}
+
+/** Chain block rewrites: every block stage N emits feeds stage N+1. */
+export function composeSseBlockRewrites(...rewrites: SseBlockRewrite[]): SseBlockRewrite {
+  const active = rewrites.filter(Boolean);
+  if (active.length === 0) return Object.assign((block: string) => [block], {});
+  const composed: SseBlockRewrite = (block: string) => {
+    let blocks: readonly string[] = [block];
+    for (const rewrite of active) {
+      const next: string[] = [];
+      for (const current of blocks) next.push(...rewrite(current));
+      blocks = next;
+    }
+    return blocks;
+  };
+  // Child disposal is part of the contract: one idempotent disposer for the
+  // whole chain, so relay teardown never leaks a nested collector.
+  let disposed = false;
+  composed.dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    for (const rewrite of active) {
+      try { rewrite.dispose?.(); } catch { /* teardown must not throw */ }
+    }
+  };
+  return composed;
+}
+
 /** Split one complete SSE event block while retaining its original blank-line delimiter. */
 export function nextSseBlock(buffer: string): { block: string; delimiter: string; rest: string } | null {
   const match = buffer.match(/\r?\n\r?\n/);
@@ -69,12 +119,34 @@ export function relaySseWithPayloadRewrite(
   body: ReadableStream<Uint8Array>,
   rewrite: SsePayloadRewrite,
   translatorBudget: TranslatorBudget,
+): ReadableStream<Uint8Array> {
+  return relaySseWithBlockRewrite(body, payloadRewriteAsBlockRewrite(rewrite), translatorBudget);
+}
+
+/**
+ * Relay an SSE body through a single JS pull wrapper, applying a block-level
+ * rewrite that may emit zero or more blocks per upstream event (lifecycle
+ * event injection, #893). The original stream's delimiter style is preserved
+ * for every emitted block.
+ */
+export function relaySseWithBlockRewrite(
+  body: ReadableStream<Uint8Array>,
+  rewrite: SseBlockRewrite,
+  translatorBudget: TranslatorBudget,
 ): ReadableStream<Uint8Array> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
   let buffer = "";
   let bufferBytes = 0;
+  // Relays have several independent teardown paths; disposal is exactly once.
+  let disposed = false;
+  let cancelled = false;
+  const disposeRewrite = (): void => {
+    if (disposed) return;
+    disposed = true;
+    try { rewrite.dispose?.(); } catch { /* teardown must not throw */ }
+  };
 
   const appendBuffer = (fragment: string): void => {
     if (!fragment) return;
@@ -130,20 +202,18 @@ export function relaySseWithPayloadRewrite(
     let next: { block: string; delimiter: string; rest: string } | null;
     while ((next = nextSseBlock(buffer))) {
       replaceBuffer(next.rest);
-      const payload = sseDataPayload(next.block);
-      const rewrittenPayload = payload ? rewrite(payload) : undefined;
-      const block = payload && rewrittenPayload !== undefined && rewrittenPayload !== payload
-        ? replaceSseDataPayload(next.block, rewrittenPayload)
-        : next.block;
-      enqueueText(controller, block + next.delimiter);
+      for (const outBlock of rewrite(next.block)) {
+        enqueueText(controller, outBlock + next.delimiter);
+      }
     }
     if (flushFinal && buffer.length > 0) {
-      const payload = sseDataPayload(buffer);
-      const rewrittenPayload = payload ? rewrite(payload) : undefined;
-      const block = payload && rewrittenPayload !== undefined && rewrittenPayload !== payload
-        ? replaceSseDataPayload(buffer, rewrittenPayload)
-        : buffer;
-      enqueueText(controller, block);
+      const tailBlocks = rewrite(buffer);
+      // A trailing fragment has no delimiter of its own; multiple emitted
+      // blocks must still be framed as separate events (#893 review).
+      const tailDelimiter = buffer.includes("\r\n") ? "\r\n\r\n" : "\n\n";
+      for (let i = 0; i < tailBlocks.length; i++) {
+        enqueueText(controller, tailBlocks[i]! + (i < tailBlocks.length - 1 ? tailDelimiter : ""));
+      }
       releaseBuffer();
     }
   };
@@ -152,10 +222,14 @@ export function relaySseWithPayloadRewrite(
     async pull(controller) {
       try {
         const { done, value } = await reader.read();
+        // A cancel raced this pending read: never feed the rewriter again
+        // after its disposal (#893 review).
+        if (cancelled) return;
         if (done) {
           appendBuffer(decoder.decode());
           emitProcessedBlocks(controller, true);
           releaseBuffer();
+          disposeRewrite();
           controller.close();
           return;
         }
@@ -163,12 +237,15 @@ export function relaySseWithPayloadRewrite(
         emitProcessedBlocks(controller);
       } catch (error) {
         releaseBuffer();
+        disposeRewrite();
         try { await reader.cancel(error); } catch { /* already closed */ }
         controller.error(error);
       }
     },
     cancel(reason) {
+      cancelled = true;
       releaseBuffer();
+      disposeRewrite();
       reader.cancel(reason).catch(() => {});
     },
   });

package/src/server/startup-health-cache.ts

@@ -23,9 +23,14 @@ export function markStartupHealthDiagnosticStale(value: StartupHealth): StartupH
     rebootSafe: false,
     protection: "none",
     diagnosticStale: true,
+    // Mirror deriveStartupHealth's choice: an already-registered service is refreshed in
+    // place. Hardcoding installService here silently undid that for every stale-cache
+    // read, which is the path the dashboard hits while a probe is revalidating.
     recommendedCommand: value.routingKind === "custom-local" || value.routingKind === "unknown"
       ? value.commands.restoreNative
-      : value.commands.installService,
+      : value.serviceInstalled && !value.serviceConflict
+        ? value.commands.repairService
+        : value.commands.installService,
   };
 }
 
@@ -72,6 +77,7 @@ function runProbe(config: Pick<OcxConfig, "codexAutoStart">): Promise<StartupHea
                   : truncateRetainedUtf8(parsed.recommendedCommand, MAX_DIAGNOSTIC_VALUE_BYTES),
                 commands: {
                   installService: truncateRetainedUtf8(parsed.commands.installService, MAX_DIAGNOSTIC_VALUE_BYTES),
+                  repairService: truncateRetainedUtf8(parsed.commands.repairService, MAX_DIAGNOSTIC_VALUE_BYTES),
                   installShim: truncateRetainedUtf8(parsed.commands.installShim, MAX_DIAGNOSTIC_VALUE_BYTES),
                   restoreNative: truncateRetainedUtf8(parsed.commands.restoreNative, MAX_DIAGNOSTIC_VALUE_BYTES),
                 },

package/src/server/ws-bridge.ts

@@ -1,10 +1,11 @@
 import type { ServerWebSocket } from "bun";
+import { responsesJsonEventSequence } from "./responses-json-events";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import type { CodexAuthContext } from "../codex/auth-context";
 import { headersForCodexAuthContext } from "../codex/auth-context";
 import type { ResponsesTerminalStatus } from "../bridge";
 import type { DataPlaneAdmission } from "./auth-cors";
-import type { AdmissionReservation } from "../lib/admission";
+import type { AdmissionLease, AdmissionReservation } from "../lib/admission";
 
 const OPEN = 1;
 type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
@@ -39,6 +40,12 @@ export interface WsData {
   liveUpstreamHeaders?: Record<string, string>;
   livePending?: Array<string | Buffer>;
   liveOpened?: boolean;
+  /** Once teardown starts, ignore new client frames until the upstream closes. */
+  liveClosing?: boolean;
+  /** Schedules one bounded close retry without surrendering native-main ownership. */
+  liveCloseFallback?: ReturnType<typeof setTimeout>;
+  /** Turn/account ownership retained for the complete sideband socket lifetime. */
+  liveTurnAdmissionLease?: AdmissionLease;
   admissionLease?: AdmissionReservation<ServerWebSocket<WsData>>;
 }
 
@@ -301,25 +308,12 @@ export function sendResponsesJsonAsEvents(
     }
     sendTextFrame(ws, text);
   };
-  const output = Array.isArray(response.output) ? response.output : [];
-  sendObservedFrame({
-    type: "response.created",
-    response: { ...response, status: "in_progress", output: [] },
-  });
-  output.forEach((item, outputIndex) => {
-    sendObservedFrame({
-      type: "response.output_item.done",
-      output_index: outputIndex,
-      item,
-    });
-  });
   const finalStatus = response.status === "failed" || response.status === "incomplete"
     ? response.status
     : "completed";
-  sendObservedFrame({
-    type: `response.${finalStatus}` as "response.completed" | "response.failed" | "response.incomplete",
-    response: { ...response, status: finalStatus },
-  });
+  for (const frame of responsesJsonEventSequence(response)) {
+    sendObservedFrame(frame);
+  }
   onTerminal?.(finalStatus);
 }
 

package/src/service-manager-probe.ts

@@ -0,0 +1,297 @@
+/**
+ * What the service manager says about this machine, read-only and fail-closed.
+ *
+ * The question this answers is NOT "is a job loaded". Installation writes the
+ * definition BEFORE the state file (`service.ts` install paths) and embeds
+ * `CODEX_HOME`/`OPENCODEX_HOME` inside it, so an interrupted reinstall leaves a
+ * valid state file for one home beside an installed definition for another. A
+ * probe that only asked about registration would call that owned. On macOS it is
+ * worse: a logged-out user has the plist on disk with no GUI domain at all, so
+ * registration reports nothing while a foreign definition sits right there.
+ *
+ * So the probe reads the DEFINITION, parses the homes out of it, and reports
+ * what it saw. Comparing those homes is the caller's job — a probe that returned
+ * a verdict would be deciding ownership from half the evidence.
+ *
+ * Every command here is read-only and bounded. The user's proxy runs under a
+ * service manager while this executes; a probe that could start, stop or reload
+ * anything is not a probe. An unbounded one is not much better, since a wedged
+ * manager would hold the event loop.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Short: this runs inside admission, and a slow answer is the same as none. */
+export const SERVICE_PROBE_TIMEOUT_MS = 2_000;
+
+export type ServiceManagerBackend = "launchd" | "systemd" | "scheduler" | "winsw";
+
+export interface ServiceManagerClaim {
+  readonly backend: ServiceManagerBackend;
+  readonly definitionPath: string;
+  /**
+   * The homes the definition names. `null` means the definition deliberately
+   * omits that key, which is different from naming a different one: an install
+   * that ran without `CODEX_HOME` set writes no such key at all.
+   */
+  readonly homes: {
+    readonly codexHome: string | null;
+    readonly opencodexHome: string | null;
+  };
+  readonly registration: "present" | "absent";
+}
+
+export type ServiceManagerInstallation =
+  | { readonly kind: "absent" }
+  | { readonly kind: "present"; readonly claims: readonly ServiceManagerClaim[] }
+  | { readonly kind: "conflict"; readonly claims: readonly ServiceManagerClaim[] }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+/** Injected so a test can observe the EXACT argv production emits. */
+export interface ProbeRunner {
+  (file: string, args: readonly string[]): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    spawnFailed: boolean;
+  };
+}
+
+export const defaultProbeRunner: ProbeRunner = (file, args) => {
+  const result = spawnSync(file, [...args], {
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: SERVICE_PROBE_TIMEOUT_MS,
+  });
+  return {
+    status: result.status,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? ""),
+    // `signal` is SIGTERM when the timeout fired; a spawn failure sets `error`.
+    timedOut: result.signal !== null && result.error === undefined,
+    spawnFailed: result.error !== undefined,
+  };
+};
+
+export interface ProbeDeps {
+  readonly run?: ProbeRunner;
+  readonly platform?: NodeJS.Platform;
+  readonly uid?: number;
+  readonly home?: string;
+}
+
+const LABEL = "com.opencodex.proxy";
+const TASK = "opencodex-proxy";
+
+/**
+ * `launchctl print` exits 113 for a service that is not there and 112 when the
+ * domain itself cannot be reached — measured against nonexistent targets rather
+ * than assumed. Only 113 is an answer; everything else is a failure to ask.
+ */
+const LAUNCHCTL_NO_SUCH_SERVICE = 113;
+/**
+ * 112 is an answer about the DOMAIN, not the label.
+ *
+ * Measured on macOS 27.0: querying a domain with no service name at all still
+ * returns it, and a domain that does not exist cannot be running one of our
+ * jobs. Treating it as "could not ask" would refuse every write on a fresh
+ * headless Mac — no GUI domain, and no installation either.
+ */
+const LAUNCHCTL_NO_SUCH_DOMAIN = 112;
+
+/**
+ * Residue on disk, distinguished from a path that could not be read.
+ *
+ * `existsSync` answers "no" for a dangling symlink and for a path whose parent
+ * denies traversal. Both are residue, not absence — only ENOENT is absence.
+ */
+function artifactPresence(path: string): "present" | "absent" | "unreadable" {
+  try {
+    lstatSync(path);
+    return "present";
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "ENOENT" ? "absent" : "unreadable";
+  }
+}
+
+function unknown(reason: string): ServiceManagerInstallation {
+  return { kind: "unknown", reason };
+}
+
+/** Pull `<key>NAME</key><string>VALUE</string>` out of a plist body. */
+function plistEnvValue(body: string, key: string): string | null {
+  const match = body.match(
+    new RegExp(`<key>\\s*${key}\\s*</key>\\s*<string>([^<]*)</string>`),
+  );
+  return match ? match[1] : null;
+}
+
+/** Pull `Environment="NAME=VALUE"` (quoted or bare) out of a systemd unit. */
+function unitEnvValue(body: string, key: string): string | null {
+  for (const line of body.split("\n")) {
+    const match = line.match(new RegExp(`^\\s*Environment=\\s*"?${key}=([^"\\n]*)"?\\s*$`));
+    if (match) return match[1];
+  }
+  return null;
+}
+
+function inspectLaunchd(deps: Required<Pick<ProbeDeps, "run" | "uid" | "home">>): ServiceManagerInstallation {
+  const definitionPath = join(deps.home, "Library", "LaunchAgents", `${LABEL}.plist`);
+
+  /*
+   * BOTH domains, because they are independent and hold separate service sets.
+   * Measured on macOS 27.0: the shipped agent answers 0 under `gui/<uid>` and
+   * 113 under `user/<uid>`. Asking only one leaves the other free to hold a job
+   * this probe would then call absent.
+   */
+  let registration: "present" | "absent" = "absent";
+  let unreachableDomains = 0;
+  for (const domain of [`gui/${deps.uid}`, `user/${deps.uid}`]) {
+    const printed = deps.run("/bin/launchctl", ["print", `${domain}/${LABEL}`]);
+    if (printed.spawnFailed || printed.timedOut) {
+      return unknown(`launchctl could not be asked: ${printed.timedOut ? "timed out" : printed.stderr.trim()}`);
+    }
+    if (printed.status === 0) { registration = "present"; break; }
+    if (printed.status === LAUNCHCTL_NO_SUCH_SERVICE) continue;
+    if (printed.status === LAUNCHCTL_NO_SUCH_DOMAIN) { unreachableDomains += 1; continue; }
+    return unknown(`launchctl print exited ${String(printed.status)}: ${printed.stderr.trim()}`);
+  }
+
+  const definition = artifactPresence(definitionPath);
+  if (definition === "absent") {
+    // No file. A registration without one means launchd holds a definition whose
+    // file is gone — real, and not something to resolve unattended.
+    if (registration === "present") {
+      return unknown("launchd has a job loaded but its plist is missing");
+    }
+    /*
+     * Nothing staged, and every domain either answered "no such service" or does
+     * not exist. 112 is an answer ABOUT THE DOMAIN and is label-independent —
+     * querying a domain with no service name at all returns it — so an
+     * unreachable domain cannot be hiding a job of ours. Calling this `unknown`
+     * instead would refuse every write on a fresh headless Mac, which has no
+     * GUI domain and no installation either.
+     */
+    void unreachableDomains;
+    return { kind: "absent" };
+  }
+
+  let body: string;
+  try {
+    body = readFileSync(definitionPath, "utf-8");
+  } catch (error) {
+    // Present-but-unreadable cannot supply homes, and `present` without homes
+    // would compare equal to nothing and read as agreement.
+    return unknown(`the launchd plist exists but could not be read: ${String(error)}`);
+  }
+
+  return {
+    kind: "present",
+    claims: [{
+      backend: "launchd",
+      definitionPath,
+      homes: {
+        codexHome: plistEnvValue(body, "CODEX_HOME"),
+        opencodexHome: plistEnvValue(body, "OPENCODEX_HOME"),
+      },
+      registration,
+    }],
+  };
+}
+
+function systemdProperty(out: string, key: string): string | null {
+  for (const line of out.split("\n")) {
+    const match = line.match(new RegExp(`^${key}=(.*)$`));
+    if (match) return match[1].trim();
+  }
+  return null;
+}
+
+function inspectSystemd(deps: Required<Pick<ProbeDeps, "run" | "home">>): ServiceManagerInstallation {
+  const definitionPath = join(deps.home, ".config", "systemd", "user", `${TASK}.service`);
+
+  /*
+   * All four properties in one call. LoadState alone is not enough — it is
+   * orthogonal to ActiveState — and neither says whether the LOADED bytes match
+   * the file. NeedDaemonReload is that signal, and this repository already
+   * documents it as the systemd analogue of launchd's stale plist.
+   */
+  const shown = deps.run("systemctl", [
+    "--user", "show", TASK,
+    "-p", "LoadState", "-p", "ActiveState", "-p", "FragmentPath", "-p", "NeedDaemonReload",
+  ]);
+  if (shown.spawnFailed || shown.timedOut) {
+    return unknown(`systemctl could not be asked: ${shown.timedOut ? "timed out" : shown.stderr.trim()}`);
+  }
+  if (shown.status !== 0) {
+    // A missing unit still exits ZERO and says not-found; a non-zero status means
+    // the question never reached the bus.
+    return unknown(`systemctl show exited ${String(shown.status)}: ${shown.stderr.trim()}`);
+  }
+
+  const loadState = systemdProperty(shown.stdout, "LoadState");
+  const activeState = systemdProperty(shown.stdout, "ActiveState");
+  const fragmentPath = systemdProperty(shown.stdout, "FragmentPath");
+  const needReload = systemdProperty(shown.stdout, "NeedDaemonReload");
+  if (loadState === null || activeState === null || needReload === null) {
+    return unknown("systemctl show did not report the properties it was asked for");
+  }
+  if (needReload === "yes") {
+    return unknown("systemd has a stale definition loaded; it needs daemon-reload");
+  }
+
+  const registration: "present" | "absent" =
+    loadState === "not-found" && activeState === "inactive" && !fragmentPath ? "absent" : "present";
+
+  if (artifactPresence(definitionPath) === "absent") {
+    return registration === "absent"
+      ? { kind: "absent" }
+      : unknown("systemd knows this unit but its file is missing");
+  }
+
+  let body: string;
+  try {
+    body = readFileSync(definitionPath, "utf-8");
+  } catch (error) {
+    return unknown(`the systemd unit exists but could not be read: ${String(error)}`);
+  }
+
+  return {
+    kind: "present",
+    claims: [{
+      backend: "systemd",
+      definitionPath,
+      homes: {
+        codexHome: unitEnvValue(body, "CODEX_HOME"),
+        opencodexHome: unitEnvValue(body, "OPENCODEX_HOME"),
+      },
+      registration,
+    }],
+  };
+}
+
+/**
+ * Windows is deferred to its own phase and reports `unknown` until then.
+ *
+ * Not an oversight: the definition there is a chain, not a file. The task XML
+ * names only the launcher, and the homes live in the batch wrapper it eventually
+ * runs — a probe that parsed the XML and stopped would find no homes and read
+ * that as agreement. Reporting `unknown` refuses unattended convergence on
+ * Windows, which is the safe direction while the chain walk is unwritten.
+ */
+function inspectWindows(): ServiceManagerInstallation {
+  return unknown("the Windows definition chain is not inspected yet");
+}
+
+export function inspectServiceManagerInstallation(deps: ProbeDeps = {}): ServiceManagerInstallation {
+  const platform = deps.platform ?? process.platform;
+  const run = deps.run ?? defaultProbeRunner;
+  const home = deps.home ?? homedir();
+  if (platform === "darwin") return inspectLaunchd({ run, uid: deps.uid ?? process.getuid?.() ?? 0, home });
+  if (platform === "linux") return inspectSystemd({ run, home });
+  if (platform === "win32") return inspectWindows();
+  return unknown(`no service manager probe for platform ${platform}`);
+}