@bitkyc08/opencodex 2.52.0 → 2.53.0-preview.20260913

package/src/service/diagnostics.ts

@@ -0,0 +1,340 @@
+import { existsSync } from "node:fs";
+import { statusWinswRaw, winswStatusSummary } from "../lib/winsw";
+import { cachedCurrentWindowsIdentity, resolveCurrentWindowsPrincipal, WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS } from "../lib/windows-user-principal";
+import { sh } from "./guards";
+import { installedServiceListenPort, confirmServiceServing } from "./health";
+import { expectedLaunchdCommand, launchdJobMatchesPlist, probeLaunchdLoadState } from "./launchd";
+import type { LaunchdLoadProbe } from "./launchd";
+import { plistPath, windowsServiceScriptPath, windowsLauncherVbsPath, windowsTaskXmlPath, readServiceInstallState } from "./state";
+import type { ServiceBackend } from "./state";
+import { unitPath, isSystemd } from "./systemd";
+import { statusWindowsXml } from "./windows-ops";
+import { cachedWindowsTaskUserIds, taskXmlSection, taskXmlWithoutCommentsAndCdata, taskXmlElementCount, readWindowsSchedulerXmlState } from "./windows-taskxml";
+import type { ExpectedWindowsTaskUserId } from "./windows-taskxml";
+import { join, win32 } from "node:path";
+import { WINSW_VERSION } from "../lib/winsw";
+import { serviceRepairCommand } from "./health";
+import { LABEL, TASK, serviceLogPath } from "./state";
+
+/**
+ * Warn when the paths baked into installed service assets no longer exist (npm prefix
+ * moved, nvm switch, reinstall) — the service manager would restart-loop on a dead path
+ * while `schtasks`/`launchctl` still report "installed".
+ */
+export function bakedServicePathsDiagnostic(): string | null {
+  const state = readServiceInstallState();
+  // A launcher install runs the launcher, not the baked pair, so the pair's existence says
+  // nothing about whether the service can start. Judging the recorded launcher is both
+  // necessary (a deleted launcher IS stale) and sufficient (a replaced version directory
+  // is not, which is exactly what #2898 made routine).
+  if (state?.launcherPath) {
+    if (existsSync(state.launcherPath)) return null;
+    return `STALE baked paths (missing: ${state.launcherPath}) — run 'ocx service repair' to re-bake`;
+  }
+  if (!state?.bunPath || !state?.cliPath) return null;
+  const missing = [state.bunPath, state.cliPath].filter(path => !existsSync(path));
+  if (missing.length === 0) return null;
+  return `STALE baked paths (missing: ${missing.join(", ")}) — run 'ocx service repair' to re-bake`;
+}
+
+export function serviceDiagnosticsSummary(): string {
+  const stale = bakedServicePathsDiagnostic();
+  return stale ? `${stale}; logs: ${serviceLogPath()}` : `logs: ${serviceLogPath()}`;
+}
+
+export interface ServiceDiagnostic {
+  supported: boolean;
+  installed: boolean;
+  enabled: boolean;
+  running: boolean;
+  viable: boolean;
+  startable: boolean;
+  stale: boolean;
+  conflict: boolean;
+  backend: ServiceBackend | "launchd" | "systemd" | null;
+  summary: string;
+}
+
+/** Windows tray may restart a healthy-but-stopped native service; stale/conflicting installs remain blocked. */
+export function serviceStartableFromTray(service: ServiceDiagnostic): boolean {
+  return service.startable && !service.stale && !service.conflict;
+}
+
+export interface WindowsTaskDiagnosticIdentityDeps {
+  currentIdentity?: () => Readonly<{ sid: string; name: string }> | null;
+  resolvePrincipal?: (timeoutMs: number) => string;
+}
+
+/**
+ * Resolve the effective account only when the registered task carries an explicit unprefixed
+ * trigger scope. Empty/unscoped tasks do not need identity and must not pay a repeated sync
+ * lookup timeout; prefixed scopes remain unreadable and fail closed in the XML validator.
+ */
+export function resolveWindowsTaskDiagnosticUserId(
+  schedulerXml: string,
+  deps: WindowsTaskDiagnosticIdentityDeps = {},
+): readonly string[] | null {
+  const currentIdentity = deps.currentIdentity ?? cachedCurrentWindowsIdentity;
+  const cached = currentIdentity();
+  if (cached) return [cached.sid, cached.name];
+
+  const scrubbed = taskXmlWithoutCommentsAndCdata(schedulerXml);
+  const triggers = taskXmlSection(scrubbed, "Triggers");
+  if (taskXmlElementCount(triggers, "UserId") === 0) return null;
+
+  try {
+    (deps.resolvePrincipal ?? resolveCurrentWindowsPrincipal)(WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS);
+  } catch {
+    return null;
+  }
+  const resolved = currentIdentity();
+  return resolved ? [resolved.sid, resolved.name] : null;
+}
+
+export interface WindowsServiceDiagnosticInputs {
+  /**
+   * Raw `schtasks /query /xml` output; empty when no task is registered. Passed as
+   * XML rather than pre-computed booleans so every caller reads the document through
+   * readWindowsSchedulerXmlState() — a second, stricter reading elsewhere would
+   * silently reintroduce the stale-status false positive (#432).
+   */
+  schedulerXml: string;
+  /** Resolved effective account for explicit scheduler trigger scopes; null means unknown. */
+  schedulerExpectedUserId?: ExpectedWindowsTaskUserId | null;
+  /** Whether the on-disk service assets exist. A filesystem concern, not an XML one. */
+  schedulerAssetsPresent: boolean;
+  nativeStatus: "started" | "stopped" | "nonexistent" | "unknown";
+  recordedBackend: ServiceBackend | null;
+  staleBakedPaths: boolean;
+  nativeRepairAssetsOnly: boolean;
+  diagnostics: string;
+}
+
+export function deriveWindowsServiceDiagnostic(inputs: WindowsServiceDiagnosticInputs): ServiceDiagnostic {
+  const expectedUserId = inputs.schedulerExpectedUserId === undefined
+    ? cachedWindowsTaskUserIds()
+    : inputs.schedulerExpectedUserId;
+  const schedulerState = readWindowsSchedulerXmlState(
+    inputs.schedulerXml,
+    undefined,
+    undefined,
+    expectedUserId,
+  );
+  const schedulerInstalled = schedulerState.installed;
+  const schedulerEnabled = schedulerState.enabled;
+  const schedulerAssetsHealthy = inputs.schedulerAssetsPresent && schedulerState.registrationHealthy;
+  const nativeInstalled = inputs.nativeStatus !== "nonexistent";
+  const conflict = schedulerInstalled && nativeInstalled;
+  const backendStateMismatch = schedulerInstalled
+    ? inputs.recordedBackend !== "scheduler"
+    : nativeInstalled && inputs.recordedBackend !== "native";
+  const stale = inputs.staleBakedPaths
+    || (schedulerInstalled && !schedulerAssetsHealthy)
+    || backendStateMismatch
+    || (inputs.nativeStatus === "nonexistent" && inputs.nativeRepairAssetsOnly);
+  const backend = schedulerInstalled ? "scheduler" : nativeInstalled ? "native" : null;
+  const enabled = schedulerInstalled ? schedulerEnabled : inputs.nativeStatus === "started";
+  const running = nativeInstalled ? inputs.nativeStatus === "started" : schedulerInstalled && schedulerEnabled;
+  const viable = !conflict && !stale
+    && (schedulerInstalled ? schedulerEnabled && schedulerAssetsHealthy : inputs.nativeStatus === "started");
+  const startable = !conflict && !stale
+    && (schedulerInstalled
+      ? schedulerEnabled && schedulerAssetsHealthy
+      : inputs.nativeStatus === "started" || inputs.nativeStatus === "stopped");
+  const detail = conflict
+    ? "CONFLICT: Task Scheduler and native WinSW are both present — run 'ocx service uninstall' then reinstall one"
+    : stale
+      ? "stale or missing service assets — run 'ocx service repair'"
+      : schedulerInstalled
+        ? schedulerEnabled ? "Task Scheduler enabled" : "Task Scheduler disabled"
+        : nativeInstalled
+          ? `native (WinSW ${WINSW_VERSION}): ${inputs.nativeStatus}`
+          : "not installed";
+  const summary = backend ? `installed, ${detail} (${inputs.diagnostics})` : `not installed (${inputs.diagnostics})`;
+  return {
+    supported: true,
+    installed: schedulerInstalled || nativeInstalled,
+    enabled,
+    running,
+    viable,
+    startable,
+    stale,
+    conflict,
+    backend,
+    summary,
+  };
+}
+
+/** Bind the live Windows identity to a scheduler snapshot before deriving service health. */
+export function deriveWindowsServiceDiagnosticForCurrentUser(
+  inputs: Omit<WindowsServiceDiagnosticInputs, "schedulerExpectedUserId">,
+  identityDeps: WindowsTaskDiagnosticIdentityDeps = {},
+): ServiceDiagnostic {
+  return deriveWindowsServiceDiagnostic({
+    ...inputs,
+    schedulerExpectedUserId: resolveWindowsTaskDiagnosticUserId(inputs.schedulerXml, identityDeps),
+  });
+}
+
+export interface LaunchdServiceDiagnosticInputs {
+  installed: boolean;
+  stale: boolean;
+  load: LaunchdLoadProbe;
+  diagnostics: string;
+}
+
+/**
+ * Turn the launchd tri-state into a {@link ServiceDiagnostic}. Pure, so the four states
+ * are testable without a live launchd.
+ *
+ * `unknown` is the one that used to do damage. The old probe collapsed "launchctl could
+ * not be asked" into "not loaded", which printed `installed, not loaded` for a serving hub
+ * and recommended `ocx service repair` — the command that evicts the job (#4236). So:
+ *
+ * - the summary says the state could not be verified and names NO repair command, and
+ * - `viable` stays true, because `isServiceViable() === false` is what makes
+ *   `src/update/index.ts` and `src/update/job.ts` treat a successful repair as a dead
+ *   supervisor and start a competing proxy on the service's own port. A failed probe is
+ *   not evidence against the service; `startable` is likewise left alone so the tray can
+ *   still hand a start to `ocx service start`, which no-ops on an already-loaded job.
+ *
+ * `loaded-stale` keeps the viability the `launchctl list` era gave it (loaded ⇒ viable, so
+ * the update fallback behaves as before), and only the summary is upgraded — the operator
+ * is told the live job came from an older plist, which is the one case where `repair` is
+ * exactly right.
+ */
+export function deriveLaunchdServiceDiagnostic(inputs: LaunchdServiceDiagnosticInputs): ServiceDiagnostic {
+  const { installed, stale, load, diagnostics } = inputs;
+  const loaded = load.state === "loaded-current" || load.state === "loaded-stale";
+  const running = installed && loaded;
+  const verified = load.state !== "unknown";
+  const viable = installed && !stale && (loaded || !verified);
+  const summary = !installed ? `not installed (${diagnostics})`
+    : stale ? `installed, but stale (launchd; ${diagnostics})`
+      : load.state === "loaded-current" ? `installed and loaded (launchd; ${diagnostics})`
+        : load.state === "loaded-stale"
+          ? `installed and loaded from an OLDER plist (launchd; ${diagnostics})`
+          : load.state === "unknown"
+            ? `installed; launchd state could not be verified — ${load.detail ?? "launchctl could not be asked"} (launchd; ${diagnostics})`
+            : `installed, not loaded (launchd; ${diagnostics})`;
+  return {
+    supported: true,
+    installed,
+    enabled: running,
+    running,
+    viable,
+    startable: installed && !stale,
+    stale,
+    conflict: false,
+    backend: "launchd",
+    summary,
+  };
+}
+
+/**
+ * Fail-closed restart diagnostic. Presence alone is never enough: conflicting
+ * managers, stale baked paths, disabled registrations, and unknown/stopped
+ * native managers cannot claim that Codex will reconnect after a reboot.
+ */
+export function diagnoseService(): ServiceDiagnostic {
+  const diagnostics = serviceDiagnosticsSummary();
+  if (process.platform === "darwin") {
+    const installed = existsSync(plistPath());
+    const stale = installed && bakedServicePathsDiagnostic() !== null;
+    return deriveLaunchdServiceDiagnostic({
+      installed,
+      stale,
+      load: installed ? probeLaunchdLoadState() : { state: "not-loaded" },
+      diagnostics,
+    });
+  }
+  if (process.platform === "win32") {
+    const schedulerXml = statusWindowsXml();
+    const schedulerAssetsPresent = [windowsServiceScriptPath(), windowsLauncherVbsPath(), windowsTaskXmlPath()]
+      .every(existsSync);
+    const nativeStatus = statusWinswRaw();
+    const installState = readServiceInstallState();
+    const recordedBackend: ServiceBackend | null = !installState
+      ? null
+      : installState.backend === "native" ? "native" : "scheduler";
+    return deriveWindowsServiceDiagnosticForCurrentUser({
+      schedulerXml,
+      schedulerAssetsPresent,
+      nativeStatus,
+      recordedBackend,
+      staleBakedPaths: bakedServicePathsDiagnostic() !== null,
+      nativeRepairAssetsOnly: Boolean(winswStatusSummary()),
+      diagnostics,
+    });
+  }
+  if (process.platform === "linux") {
+    if (existsSync("/.dockerenv")) return { supported: false, installed: false, enabled: false, running: false, viable: false, startable: false, stale: false, conflict: false, backend: null, summary: "unsupported in Docker" };
+    if (!isSystemd()) return { supported: false, installed: false, enabled: false, running: false, viable: false, startable: false, stale: false, conflict: false, backend: null, summary: "unsupported: systemd not found" };
+    const installed = existsSync(unitPath());
+    const enabled = installed && (() => { try { return sh(`systemctl --user is-enabled ${TASK}`) === "enabled"; } catch { return false; } })();
+    const running = installed && (() => { try { return sh(`systemctl --user is-active ${TASK}`) === "active"; } catch { return false; } })();
+    const stale = installed && bakedServicePathsDiagnostic() !== null;
+    const viable = installed && enabled && running && !stale;
+    const summary = !installed ? `not installed (${diagnostics})`
+      : stale ? `installed, but stale (systemd user; ${diagnostics})`
+        : viable ? `installed, enabled and running (systemd user; ${diagnostics})`
+          : `installed, but ${!enabled ? "disabled" : "not running"} (systemd user; ${diagnostics})`;
+    return { supported: true, installed, enabled, running, viable, startable: installed && !stale, stale, conflict: false, backend: "systemd", summary };
+  }
+  return { supported: false, installed: false, enabled: false, running: false, viable: false, startable: false, stale: false, conflict: false, backend: null, summary: `unsupported on ${process.platform}` };
+}
+
+export function serviceStatusSummary(): string {
+  return diagnoseService().summary;
+}
+
+/**
+ * Status a human can act on: registration state, whether a proxy actually answers,
+ * and — when it does not — whether launchd is running the plist we have on disk.
+ *
+ * `launchctl list` membership cannot distinguish "serving", "bootstrapped from an
+ * older plist", and "loaded but never bound"; the reported failure was the middle
+ * one presented as the first.
+ *
+ * Resolves the port through `confirmServiceServing`, i.e. the same
+ * `installedServiceListenPort()` path install/start/repair use, so those surfaces can
+ * never disagree about one service. The budget is short (2 probes) because this is a
+ * status read, not a post-install wait.
+ */
+export async function serviceStatusReport(
+  deps: {
+    diagnose?: () => ServiceDiagnostic;
+    serving?: () => Promise<{ ok: boolean; port: number }>;
+    matchesPlist?: () => { loaded: boolean; matchesPlist: boolean };
+  } = {},
+): Promise<string> {
+  const diag = (deps.diagnose ?? diagnoseService)();
+  if (!diag.installed) return `❌ ${diag.summary}`;
+
+  const serving = await (deps.serving ?? (() => confirmServiceServing({ timeoutMs: 1_500 })))();
+  if (serving.ok) return `✅ ${diag.summary}\n   Serving on port ${serving.port}.`;
+
+  // The dep is consulted FIRST; the platform check only guards the default. Wrapping
+  // the whole expression in a darwin check would discard an injected seam on
+  // Linux/Windows and make the stale-plist case untestable there.
+  const stalePlist = deps.matchesPlist?.() ?? (process.platform === "darwin"
+    ? (() => {
+        // Pass the INSTALLED port explicitly: the default third argument is
+        // resolveServiceListenPort(), which reads OCX_BAKE_PORT/config.port, so after
+        // a config edit the expected string would never match and every run would
+        // print a false "OLDER plist".
+        return launchdJobMatchesPlist(expectedLaunchdCommand(installedServiceListenPort()));
+      })()
+    : null);
+  const staleLine = stalePlist && stalePlist.loaded && !stalePlist.matchesPlist
+    ? "   launchd is running an OLDER plist than the one on disk.\n"
+      + `   Fix:    launchctl bootout gui/$(id -u)/${LABEL} && ocx service repair\n`
+    : "";
+
+  return `⚠️  ${diag.summary}\n`
+    + `   Registered, but no proxy is answering on port ${serving.port}.\n`
+    + staleLine
+    + `   Log:    ${serviceLogPath()}\n`
+    + `   Repair: ${serviceRepairCommand()}\n`
+    + "   Meanwhile: ocx start           (serves in the foreground)";
+}

package/src/service/guards.ts

@@ -0,0 +1,303 @@
+import { execSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { getConfigDir, loadConfig } from "../config";
+import { readServiceApiTokenState, 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, normalizePathForCompare, readServiceInstallState } from "./state";
+import { win32 } from "node:path";
+
+/**
+ * The service was installed under a different CODEX_HOME/OPENCODEX_HOME, so this process may not
+ * touch it. Distinct from "stop failed": the manager was never even contacted, which means the
+ * installed service is still live and shared state (native Codex config, the Grok fence) must be
+ * left alone — tearing it down would strip config out from under a running service.
+ */
+export class ServiceOwnershipError extends Error {
+  readonly code = "service-ownership-mismatch" as const;
+}
+
+export function isServiceOwnershipError(err: unknown): err is ServiceOwnershipError {
+  return err instanceof ServiceOwnershipError;
+}
+
+/**
+ * True when no installed service exists, or the installed one belongs to THIS
+ * CODEX_HOME/OPENCODEX_HOME. Callers use it to decide whether they may tear down shared state
+ * (native Codex config, the Grok fence) that a foreign service would still be relying on.
+ */
+export function serviceEnvironmentOwnedHere(): boolean {
+  try {
+    assertServiceEnvironmentMatchesInstall();
+    return true;
+  } catch (err) {
+    if (isServiceOwnershipError(err)) return false;
+    return true; // unrelated failure: fall back to the previous behavior rather than wedging
+  }
+}
+
+export function assertServiceEnvironmentMatchesInstall(): void {
+  const state = readServiceInstallState();
+  if (!state) return;
+  const actualCodexHome = currentCodexHome();
+  const expected = normalizePathForCompare(state.codexHome);
+  const actual = normalizePathForCompare(actualCodexHome);
+  if (expected !== actual) {
+    throw new ServiceOwnershipError(
+      `Service was installed with CODEX_HOME=${state.codexHome}, but current CODEX_HOME=${actualCodexHome}. ` +
+        "Run the service command from the same Codex home so native Codex restore updates the correct config.",
+    );
+  }
+  const expectedOpenCodexHome = normalizePathForCompare(state.opencodexHome);
+  const actualOpenCodexHome = normalizePathForCompare(currentOpenCodexHome());
+  if (expectedOpenCodexHome !== actualOpenCodexHome) {
+    throw new ServiceOwnershipError(
+      `Service was installed with OPENCODEX_HOME=${state.opencodexHome}, but current OPENCODEX_HOME=${currentOpenCodexHome()}. ` +
+        "Run the service command from the same OpenCodex home so service state and secrets match.",
+    );
+  }
+}
+
+function isLoopbackHostname(hostname: string | undefined): boolean {
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
+  return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+
+/**
+ * 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.
+ *
+ * The service exports the contents of the service token file as
+ * `OPENCODEX_API_AUTH_TOKEN` before starting the proxy. When that value is the admin
+ * token, the server treats the management credential as a data-plane admission secret
+ * and fails the ENTIRE management plane closed at boot, so every `/api/*` request
+ * returns 503 — even on a loopback install that never needed a data-plane secret.
+ * Exporting the admin token in the CLI cannot recover it, because the fence is decided
+ * server-side at startup (#2696).
+ *
+ * Nothing in this codebase puts an admin token in that env var; it arrives from the
+ * installing shell. This function is the chokepoint that should refuse it rather than
+ * writing a file that produces a broken service. Comparison is the same helper doctor
+ * uses: minted `ocx_admin_…` prefix, or byte-equal to configuredAdminToken (env or file).
+ *
+ * `source` selects the remedy, not the rule. The token can also arrive from an EXISTING
+ * `service-api-token` that install/repair reuses, and there `unset` is meaningless advice —
+ * the fix is to delete the file so a data-plane token is generated.
+ */
+export function assertNotAdminToken(
+  token: string,
+  env: NodeJS.ProcessEnv = process.env,
+  source: "env" | "file" = "env",
+): void {
+  if (!tokenCollidesWithAdmin(token, env)) return;
+  if (source === "file") {
+    // The file branch of `writeServiceApiTokenFile` used to skip this check entirely, so a
+    // hand-pasted admin token already on disk (pre-#2696, or the exact #4236 incident) was
+    // silently reused: `ocx status` said `present (file)` and the hub crash-looped at boot.
+    // The remedy is NOT `unset` -- there is nothing in the environment to unset.
+    throw new Error(
+      `${serviceApiTokenFilePath()} holds a management (admin) token, not a data-plane token. `
+        + "The service exports that file as the data-plane secret, which fences the whole management "
+        + "API closed and makes every ocx management command fail with 503, so the hub crash-loops at "
+        + `boot. Delete the file (rm ${serviceApiTokenFilePath()}), then rerun \`ocx service repair\` `
+        + "(or `ocx service install` when the service is not installed yet): a fresh owner-only "
+        + "data-plane token is generated and nothing needs to be exported by hand.",
+    );
+  }
+  throw new Error(
+    "OPENCODEX_API_AUTH_TOKEN holds a management (admin) token. The service exports it "
+      + "as the data-plane secret, which fences the whole management API closed and makes "
+      + "every ocx management command fail with 503. Run `unset OPENCODEX_API_AUTH_TOKEN` "
+      + "and rerun: nothing needs to be exported by hand, because the service provisions "
+      + `its own owner-only data-plane token at ${serviceApiTokenFilePath()}.`,
+  );
+}
+
+/**
+ * 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";
+
+export interface ProvisionedServiceApiToken {
+  path: string;
+  origin: ServiceApiTokenOrigin;
+}
+
+function persistServiceApiToken(token: string): string {
+  const path = serviceApiTokenFilePath();
+  const dir = getConfigDir();
+  recordOwnedConfigPath(dir, path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform === "win32") hardenSecretDir(dir, { required: true });
+  writeFileSync(path, `${token}\n`, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  if (process.platform === "win32") hardenSecretPath(path, { required: true });
+  return path;
+}
+
+/**
+ * Put a usable data-plane token on disk for the service to read at launch, and say where.
+ *
+ * EVERY backend funnels through here — launchd, systemd, the Windows scheduler wrapper and
+ * WinSW native — because the launch wrapper's only source of the secret is this file
+ * (`buildServiceShellCommand` cats it into the environment; WinSW reads it through
+ * `OCX_API_TOKEN_FILE`). One chokepoint is also what makes the admin-token refusal
+ * unskippable (#2696).
+ *
+ * Precedence, in order:
+ *  1. `OPENCODEX_API_AUTH_TOKEN` from the installing shell — still refused outright when it is
+ *     an admin token. An operator who deliberately exports a key keeps full control of it.
+ *  2. An existing owner-only `service-api-token`. Reusing it is what makes `repair`, a
+ *     reinstall and a restart idempotent; regenerating would silently invalidate every client
+ *     key-exchange already performed against the old value.
+ *  3. 32 fresh random bytes, hex. This is the branch that removes the manual step: a hub
+ *     install on a non-loopback hostname provisions its own secret.
+ *
+ * A loopback install with no env token gets nothing: admission is not required there, so
+ * creating a credential would be inventing a secret nobody asked for — and on a machine
+ * connected to a hub the same file holds that hub's issued client key, which must not be
+ * overwritten by a local install.
+ *
+ * The PATH is logged; the value never is, and never reaches argv, a unit file or a plist.
+ */
+export function writeServiceApiTokenFile(): ProvisionedServiceApiToken | null {
+  const token = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (token) {
+    // Last line of defence: every install/repair path funnels through here, so a
+    // collision cannot reach disk regardless of which caller ran (#2696).
+    assertNotAdminToken(token);
+    const path = persistServiceApiToken(token);
+    console.log(`🔐 Data-plane token taken from OPENCODEX_API_AUTH_TOKEN and stored at ${path} (owner-only).`);
+    return { path, origin: "env" };
+  }
+  if (isLoopbackHostname(loadConfig().hostname)) return null;
+  const existing = readServiceApiTokenState();
+  if (existing.kind === "present") {
+    // The collision check is NOT only for the env branch. A file that already holds the admin
+    // token -- hand-pasted before #2696, or written by the very incident this unit closes --
+    // was silently accepted here, so `ocx status` reported `present (file)` and the hub
+    // crash-looped at boot with no command pointing at the cause.
+    const path = serviceApiTokenFilePath();
+    assertNotAdminToken(existing.token, process.env, "file");
+    // `readServiceApiTokenState` accepts any bounded regular file, so a reused token may well
+    // be group- or world-readable. Tighten it on the way through rather than claiming
+    // "owner-only" about a mode nobody checked; best-effort, since a non-owner cannot chmod
+    // and failing the install over it would be worse than the loose mode.
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (process.platform === "win32") hardenSecretPath(path, { required: false });
+    // No log line: repair/restart hit this on every run and an unconditional notice about a
+    // credential file trains operators to ignore the one that matters.
+    return { path, origin: "file" };
+  }
+  if (existing.kind === "unsafe") throw new Error(`${existing.reason}: ${serviceApiTokenFilePath()}`);
+  const path = persistServiceApiToken(randomBytes(32).toString("hex"));
+  console.log(`🔐 Provisioned an owner-only data-plane token at ${path}; nothing needs to be exported by hand.`);
+  console.log("   Remote machines get their own per-client key — run 'ocx hub invite' instead of copying this file.");
+  return { path, origin: "generated" };
+}
+
+export function sh(cmd: string): string {
+  assertLiveServiceManagerAllowed(cmd);
+  return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+/**
+ * Service-manager invocations that only observe. Everything else changes a job that
+ * launchd or the systemd user manager is running right now.
+ */
+const READ_ONLY_SERVICE_MANAGER = new RegExp(
+  "^(?:launchctl\\s+(?:list|print|print-disabled|blame|managerpid|manageruid)\\b"
+  + "|systemctl\\s+(?:--user\\s+)?(?:show|show-environment|status|is-active|is-enabled|is-failed|cat|list-units|list-unit-files|--version)\\b)",
+);
+
+const SERVICE_MANAGER_COMMAND = /^(?:launchctl|systemctl)\b/;
+
+/**
+ * Refuse to mutate a live service manager from an armed test process.
+ *
+ * The test preload isolates HOME, OPENCODEX_HOME and CODEX_HOME, and that is enough for
+ * anything addressed by path. It is not enough here. `systemctl --user stop
+ * opencodex-proxy.service` is addressed by job NAME and talks to the user manager that is
+ * already running, so it stops the proxy the developer is actually using no matter what
+ * HOME says. `launchctl bootout gui/<uid>/com.opencodex.proxy` has the same shape.
+ *
+ * Windows already had this guard: `querySchtasks` refuses every non-query call while the
+ * test-home guard is armed, after a partially-faked test replaced a real scheduled task
+ * with a launcher inside a temporary test home. macOS and Linux were left without the
+ * equivalent, which means the person most likely to run this suite - someone running
+ * opencodex on the machine they are developing it on - is the person it can disrupt.
+ *
+ * Read-only verbs stay allowed: probing what the manager reports is the whole point of
+ * the diagnostics, and observation cannot take a service down.
+ */
+export function assertLiveServiceManagerAllowed(command: string): void {
+  if (!isTestHomeGuardArmed()) return;
+  const trimmed = command.trim();
+  if (!SERVICE_MANAGER_COMMAND.test(trimmed)) return;
+  if (READ_ONLY_SERVICE_MANAGER.test(trimmed)) return;
+  throw new Error(
+    `refusing to run \`${trimmed}\` from an armed test process: launchd and the systemd user `
+    + "manager address a job by name, not by HOME, so this reaches the service the developer is "
+    + "actually running. Inject the service operation instead of calling the live manager.",
+  );
+}