@iislee/opencodex 2.11.0

package/src/codex/auth-collision.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getCodexAccountCredential } from "./account-store";
+import { loadConfig } from "../config";
+import { resolveCodexHomeDir } from "./home";
+import { extractAccountId } from "../oauth/chatgpt";
+import { isSelectableCodexPoolAccount } from "./account-id";
+
+export interface CodexTokens {
+  access_token: string;
+  account_id: string;
+  id_token?: string;
+}
+
+/**
+ * Why a read *outcome* and not just `Tokens | null`: callers need to tell a real sign-out apart
+ * from a transient read failure. A single null collapsed "file absent", "malformed JSON", and
+ * "read error" into one answer, so a half-written `auth.json` looked exactly like a logout and
+ * callers destroyed healthy cached account state because of it.
+ */
+export type CodexTokenReadResult =
+  | { status: "ok"; tokens: CodexTokens }
+  | { status: "missing" | "invalid" | "unreadable" };
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as { code?: unknown }).code === code;
+}
+
+/**
+ * Reads the Codex CLI credential file and classifies the outcome. Reads once instead of doing an
+ * `existsSync` pre-check, so a file replaced between check and read cannot be misread as absent.
+ * Never returns or logs the raw error or any token material.
+ */
+export function readCodexTokensResult(): CodexTokenReadResult {
+  let raw: string;
+  try {
+    raw = readFileSync(join(resolveCodexHomeDir(), "auth.json"), "utf-8");
+  } catch (error) {
+    return { status: hasErrnoCode(error, "ENOENT") ? "missing" : "unreadable" };
+  }
+  try {
+    const j = JSON.parse(raw) as {
+      tokens?: { access_token?: string; account_id?: string; id_token?: string };
+    };
+    if (!j?.tokens?.access_token) return { status: "invalid" };
+    return {
+      status: "ok",
+      tokens: {
+        access_token: j.tokens.access_token,
+        account_id: j.tokens.account_id ?? "",
+        id_token: j.tokens.id_token,
+      },
+    };
+  } catch {
+    return { status: "invalid" };
+  }
+}
+
+/**
+ * Compatibility wrapper: any usable-token check keeps the original null contract, which keeps
+ * request routing fail-closed. Only callers that must distinguish the failure reason should use
+ * `readCodexTokensResult()`.
+ */
+export function readCodexTokens(): CodexTokens | null {
+  const result = readCodexTokensResult();
+  return result.status === "ok" ? result.tokens : null;
+}
+
+export function getMainChatgptAccountId(): string | null {
+  const tokens = readCodexTokens();
+  if (!tokens) return null;
+  return extractAccountId(tokens.id_token, tokens.access_token) ?? (tokens.account_id || null);
+}
+
+function normalizedEmail(email: string | undefined | null): string | null {
+  const trimmed = email?.trim().toLowerCase();
+  return trimmed || null;
+}
+
+function isWorkspacePlan(plan: string | undefined | null): boolean {
+  return !!plan && /team|business|enterprise|workspace|edu/i.test(plan);
+}
+
+// Main login and managed pool accounts are separate duplicate buckets.
+// Inside the pool, personal and workspace subscriptions are also separate buckets.
+// Within each pool bucket, keep the original ChatGPT account id + email collision guard.
+export function checkAccountIdCollision(
+  chatgptAccountId: string,
+  email?: string | null,
+  plan?: string | null,
+  excludeAccountId?: string | null,
+): { collision: true; reason: string } | { collision: false } {
+  const candidateEmail = normalizedEmail(email);
+  const candidateWorkspace = isWorkspacePlan(plan);
+  for (const account of loadConfig().codexAccounts ?? []) {
+    if (excludeAccountId && account.id === excludeAccountId) continue;
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    if (isWorkspacePlan(account.plan) !== candidateWorkspace) continue;
+    const cred = getCodexAccountCredential(account.id);
+    const poolEmail = normalizedEmail(account.email);
+    if (cred && cred.chatgptAccountId === chatgptAccountId && (!candidateEmail || !poolEmail || poolEmail === candidateEmail)) {
+      return { collision: true, reason: `Account is already in the pool (${account.id}).` };
+    }
+  }
+  return { collision: false };
+}

package/src/codex/auth-context.ts

@@ -0,0 +1,352 @@
+import {
+  CodexCredentialGenerationConflictError,
+  CodexCredentialRefreshLockTimeoutError,
+  CodexCredentialRefreshBusyError,
+  CodexCredentialRefreshStaleError,
+  getValidCodexToken,
+  isCodexAccountGenerationLive,
+} from "./account-store";
+import { ConfigMutationLockError } from "../config";
+import { markAccountNeedsReauth } from "./account-runtime-state";
+import { isCodexAccountUsable } from "./account-usability";
+import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
+import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
+import {
+  codexQuotaScopeForModel,
+  getCodexQuotaHealthSnapshot,
+  releaseCodexQuotaProbeLease,
+  releaseCodexQuotaScopeProbeLease,
+  tryAcquireCodexQuotaProbeLease,
+  tryAcquireCodexQuotaScopeProbeLease,
+  pickAlternateCodexAccount,
+  resolveCodexAccountForThreadDetailed,
+} from "./routing";
+import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
+import { maskAccountId } from "../lib/privacy";
+import { formatErrorResponse } from "../bridge";
+import { getAccountQuota } from "./quota";
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import { FORWARD_HEADERS } from "../adapters/openai-responses";
+import { captureConfigGeneration } from "../lib/state-store-sweeper";
+
+export type CodexAuthContext =
+  | { kind: "main"; accountId: null }
+  | {
+      kind: "pool";
+      accountId: string;
+      writerGeneration: number;
+      generation: number;
+      accessToken: string;
+      chatgptAccountId: string;
+      /**
+       * Set when this request was admitted through an active quota cooldown as
+       * the account's single probe. Must be echoed into the upstream outcome so
+       * only this request can clear the cooldown (#433).
+      */
+      probeLeaseId?: string;
+      /** Native model quota group selected for this request, when known. */
+      quotaScope?: CodexQuotaScope;
+      /** Scope that owns `probeLeaseId`, when it is a scoped recovery probe. */
+      probeQuotaScope?: CodexQuotaScope;
+    }
+  | {
+      // Main Codex account participating in rotation: token injected from ~/.codex/auth.json
+      // (Option A). Distinct from "main" (passthrough fallback that forwards the client token).
+      kind: "main-pool";
+      accountId: string;
+      writerGeneration: number;
+      accessToken: string;
+      chatgptAccountId: string;
+      /** See `pool.probeLeaseId`. */
+      probeLeaseId?: string;
+      quotaScope?: CodexQuotaScope;
+      probeQuotaScope?: CodexQuotaScope;
+    };
+
+/** Probe lease carried by this context, when it holds one. */
+export function codexProbeLeaseId(ctx: CodexAuthContext | undefined): string | undefined {
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeLeaseId : undefined;
+}
+
+/** Scope of a lease carried by this context, when it probes a model-specific quota. */
+export function codexProbeQuotaScope(ctx: CodexAuthContext | undefined): CodexQuotaScope | undefined {
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.probeQuotaScope : undefined;
+}
+
+/**
+ * Hand back a probe lease for a request that will not reach upstream. Safe to
+ * call with a context that holds no lease.
+ */
+export function releaseCodexAuthContextProbeLease(ctx: CodexAuthContext | undefined): void {
+  const leaseId = codexProbeLeaseId(ctx);
+  if (!ctx || ctx.kind === "main" || !leaseId) return;
+  if (ctx.probeQuotaScope) releaseCodexQuotaScopeProbeLease(ctx.accountId!, ctx.probeQuotaScope, leaseId);
+  else releaseCodexQuotaProbeLease(ctx.accountId!, leaseId);
+}
+
+export type OcxRuntimeProviderConfig = OcxProviderConfig & {
+  _codexAccountOverride?: { accessToken: string; chatgptAccountId: string };
+  _codexAccountRequired?: boolean;
+};
+
+export class CodexAuthContextError extends Error {
+  accountId: string;
+
+  constructor(accountId: string, cause: unknown) {
+    super("Codex pool account auth failed", { cause });
+    this.name = "CodexAuthContextError";
+    this.accountId = accountId;
+  }
+}
+
+export class CodexPoolAuthenticationError extends Error {
+  constructor() {
+    super("OpenAI account pool has no usable account credential");
+    this.name = "CodexPoolAuthenticationError";
+  }
+}
+
+export class CodexDirectAuthenticationError extends Error {
+  constructor() {
+    super("Codex Direct requires a caller Authorization bearer token");
+    this.name = "CodexDirectAuthenticationError";
+  }
+}
+
+export function hasCallerCodexBearer(headers: Headers): boolean {
+  return /^Bearer\s+\S+/i.test(headers.get("authorization")?.trim() ?? "");
+}
+
+export class CodexAccountCooldownError extends Error {
+  accountId: string;
+  cooldownUntil: number;
+  cooldownSource?: CodexCooldownSource;
+  quotaScope?: CodexQuotaScope;
+
+  constructor(
+    accountId: string,
+    cooldownUntil: number,
+    cooldownSource?: CodexCooldownSource,
+    quotaScope?: CodexQuotaScope,
+  ) {
+    super("Selected Codex account is cooling down");
+    this.name = "CodexAccountCooldownError";
+    this.accountId = accountId;
+    this.cooldownUntil = cooldownUntil;
+    this.cooldownSource = cooldownSource;
+    this.quotaScope = quotaScope;
+  }
+}
+
+/**
+ * Human-readable account label for a client-visible error. NEVER the raw id: the proxy
+ * supports non-loopback binds (auth-cors.ts `isApiAuthRequired` requires a token there
+ * rather than refusing), so data-plane bodies can reach remote authenticated clients.
+ * The main login has no secret id, so it renders as the literal alias users type.
+ */
+export function cooldownAccountLabel(accountId: string): string {
+  return accountId === MAIN_CODEX_ACCOUNT_ID ? "main" : maskAccountId(accountId) ?? "account-…????";
+}
+
+/**
+ * Actionable message for a cooled-down account: until when, why, and how to escape.
+ * Shared by every transport so the WebSocket surface (Codex Desktop) says the same thing
+ * as HTTP. The bare "cooling down" string left users with no route but commenting out the
+ * injected `openai_base_url` in config.toml.
+ */
+export function cooldownErrorMessage(err: CodexAccountCooldownError): string {
+  const until = new Date(err.cooldownUntil).toISOString();
+  const scope = err.quotaScope === "spark"
+    ? "Spark quota"
+    : err.quotaScope === "shared"
+      ? "shared native quota"
+      : null;
+  return `Selected Codex account (${cooldownAccountLabel(err.accountId)})${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
+    + ` (source: ${err.cooldownSource ?? "default"}).`
+    + ` Run 'ocx account list openai' to find the id, then`
+    + ` 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.`;
+}
+
+/** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
+export function cooldownErrorResponse(err: CodexAccountCooldownError, now = Date.now()): Response {
+  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err));
+  const headers = new Headers(res.headers);
+  headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
+  return new Response(res.body, { status: res.status, headers });
+}
+
+export class CodexThreadAffinityExpiredError extends Error {
+  accountId: string;
+
+  constructor(accountId: string) {
+    super("Codex thread account affinity expired");
+    this.name = "CodexThreadAffinityExpiredError";
+    this.accountId = accountId;
+  }
+}
+
+export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
+  return !(cause instanceof CodexCredentialGenerationConflictError)
+    && !(cause instanceof CodexCredentialRefreshLockTimeoutError)
+    && !(cause instanceof CodexCredentialRefreshBusyError)
+    && !(cause instanceof CodexCredentialRefreshStaleError)
+    && !(cause instanceof ConfigMutationLockError);
+}
+
+export interface ResolveCodexAuthContextOptions {
+  excludeAccountId?: string;
+  /** Final native model selected for this request, used to select its quota group. */
+  modelId?: string;
+}
+
+export async function resolveCodexAuthContext(
+  headers: Headers,
+  config: OcxConfig,
+  mode: CodexAccountMode,
+  options: ResolveCodexAuthContextOptions = {},
+): Promise<CodexAuthContext> {
+  const writerGeneration = captureConfigGeneration();
+  if (mode === "direct") {
+    if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
+    return { kind: "main", accountId: null };
+  }
+  reconcileMainCodexAccountRuntimeState();
+  const threadId = headers.get("x-codex-parent-thread-id");
+  const quotaScope = codexQuotaScopeForModel(options.modelId);
+  const resolution = options.excludeAccountId
+    ? (() => {
+        const accountId = pickAlternateCodexAccount(config, options.excludeAccountId!, Date.now(), quotaScope);
+        return accountId
+          ? { status: "selected" as const, accountId }
+          : { status: "none" as const };
+      })()
+    : resolveCodexAccountForThreadDetailed(threadId, config, Date.now(), quotaScope);
+  if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
+  let accountId = resolution.status === "selected" ? resolution.accountId : null;
+  if (!accountId) throw new CodexPoolAuthenticationError();
+  // Lazy prime: if the selected account has no quota yet, the pool is likely
+  // unprimed (dashboard never opened, or startup prime was blocked). Kick a
+  // best-effort prime so the NEXT routing decision has real scores. This never
+  // blocks the current request, and the helper's single-flight guard collapses
+  // repeated triggers into one pass.
+  if (!getAccountQuota(accountId)) {
+    import("./auth-api")
+      .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
+      .catch(() => {});
+  }
+  // Snapshot (not just the deadline) so a refused request can report WHY it is cooled:
+  // a literal Retry-After reads very differently to a user than a reset-derived guess.
+  const cooldown = getCodexQuotaHealthSnapshot(accountId, quotaScope);
+  const cooldownUntil = cooldown?.cooldownUntil;
+  // A cooled-down account never sends traffic, so upstream recovery can never be
+  // observed and the cooldown outlives the real limit. Admit one probe per
+  // interval; its outcome decides whether the cooldown ends (#433).
+  let probeLeaseId: string | undefined;
+  let probeQuotaScope: CodexQuotaScope | undefined;
+  if (cooldownUntil) {
+    probeQuotaScope = cooldown?.quotaScope;
+    probeLeaseId = probeQuotaScope
+      ? tryAcquireCodexQuotaScopeProbeLease(accountId, probeQuotaScope) ?? undefined
+      : tryAcquireCodexQuotaProbeLease(accountId) ?? undefined;
+    if (!probeLeaseId) {
+      throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
+    }
+  }
+
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+    // Main account in rotation: inject the read-only auth.json token and fail closed if it vanished.
+    const token = getMainAccountToken();
+    if (!token) {
+      // Nothing will reach upstream, so give the probe back instead of burning it.
+      if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
+      else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+      throw new CodexPoolAuthenticationError();
+    }
+    return {
+      kind: "main-pool",
+      accountId,
+      writerGeneration,
+      accessToken: token.accessToken,
+      chatgptAccountId: token.chatgptAccountId,
+      ...(quotaScope ? { quotaScope } : {}),
+      ...(probeLeaseId ? { probeLeaseId } : {}),
+      ...(probeQuotaScope ? { probeQuotaScope } : {}),
+    };
+  }
+
+  try {
+    const token = await getValidCodexToken(accountId);
+    return {
+      kind: "pool",
+      accountId,
+      writerGeneration,
+      generation: token.generation,
+      accessToken: token.accessToken,
+      chatgptAccountId: token.chatgptAccountId,
+      ...(quotaScope ? { quotaScope } : {}),
+      ...(probeLeaseId ? { probeLeaseId } : {}),
+      ...(probeQuotaScope ? { probeQuotaScope } : {}),
+    };
+  } catch (cause) {
+    if (probeLeaseId && probeQuotaScope) releaseCodexQuotaScopeProbeLease(accountId, probeQuotaScope, probeLeaseId);
+    else if (probeLeaseId) releaseCodexQuotaProbeLease(accountId, probeLeaseId);
+    if (shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
+      markAccountNeedsReauth(accountId, writerGeneration);
+    }
+    throw new CodexAuthContextError(accountId, cause);
+  }
+}
+
+export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefined): void {
+  if (ctx?.kind !== "pool" && ctx?.kind !== "main-pool") return;
+  // A context holding the probe lease was deliberately admitted through the cooldown.
+  if (ctx.probeLeaseId) return;
+  const cooldown = getCodexQuotaHealthSnapshot(ctx.accountId, ctx.quotaScope);
+  if (cooldown?.cooldownUntil) {
+    throw new CodexAccountCooldownError(ctx.accountId, cooldown.cooldownUntil, cooldown.cooldownSource, cooldown.quotaScope);
+  }
+}
+
+export function applyCodexAuthContextToProvider(
+  provider: OcxProviderConfig,
+  ctx: CodexAuthContext,
+  mode: CodexAccountMode | undefined,
+): OcxRuntimeProviderConfig {
+  if (mode !== "pool" || (ctx.kind !== "pool" && ctx.kind !== "main-pool") || provider.authMode !== "forward") return provider;
+  return {
+    ...provider,
+    _codexAccountOverride: {
+      accessToken: ctx.accessToken,
+      chatgptAccountId: ctx.chatgptAccountId,
+    },
+    _codexAccountRequired: true,
+  };
+}
+
+export function headersForCodexAuthContext(headers: Headers, ctx: CodexAuthContext): Headers {
+  const selected = new Headers();
+  for (const name of FORWARD_HEADERS) {
+    const value = headers.get(name);
+    if (value) selected.set(name, value);
+  }
+  if (ctx.kind === "pool" || ctx.kind === "main-pool") {
+    selected.set("authorization", `Bearer ${ctx.accessToken}`);
+    selected.set("chatgpt-account-id", ctx.chatgptAccountId);
+  }
+  return selected;
+}
+
+export function isCodexAuthContextUsable(ctx: CodexAuthContext, config: OcxConfig): boolean {
+  if (ctx.kind === "main") return true;
+  if (ctx.kind === "main-pool") return isCodexAccountUsable(config, ctx.accountId);
+  return isCodexAccountUsable(config, ctx.accountId) && isCodexAccountGenerationLive(ctx.accountId, ctx.generation);
+}
+
+export function stripCodexRuntimeProviderFields(provider: OcxProviderConfig): OcxProviderConfig {
+  const {
+    _codexAccountOverride: _override,
+    _codexAccountRequired: _required,
+    ...safeProvider
+  } = provider as OcxRuntimeProviderConfig;
+  return safeProvider;
+}

package/src/codex/autostart-health.ts

@@ -0,0 +1,149 @@
+import { codexAutoStartEnabled } from "../config";
+import { diagnoseService, type ServiceDiagnostic } from "../service";
+import type { OcxConfig } from "../types";
+import { getCodexRoutingKind, type CodexRoutingKind } from "./inject";
+import { diagnoseCodexShim, type CodexShimDiagnostic } from "./shim";
+
+export type StartupProtection = "service" | "shim" | "none";
+export type StartupHealthStatus = "native" | "protected" | "at-risk";
+export type ShimCoverage = "full" | "cli-only" | "none";
+
+export interface StartupHealthInputs {
+  routingKind: CodexRoutingKind;
+  autostartEnabled: boolean;
+  serviceInstalled: boolean;
+  serviceViable: boolean;
+  serviceEnabled: boolean;
+  serviceRunning: boolean;
+  serviceStale: boolean;
+  serviceConflict: boolean;
+  serviceSupported: boolean;
+  shimInstalled: boolean;
+  shimHealthy: boolean;
+  platform: NodeJS.Platform;
+  diagnosticStale?: boolean;
+}
+
+export interface StartupHealth {
+  status: StartupHealthStatus;
+  routingKind: CodexRoutingKind;
+  routingInjected: boolean;
+  localRoutingDependency: boolean;
+  autostartEnabled: boolean;
+  rebootSafe: boolean;
+  protection: StartupProtection;
+  serviceInstalled: boolean;
+  serviceViable: boolean;
+  serviceEnabled: boolean;
+  serviceRunning: boolean;
+  serviceStale: boolean;
+  serviceConflict: boolean;
+  shimInstalled: boolean;
+  shimHealthy: boolean;
+  shimCoverage: ShimCoverage;
+  serviceSupported: boolean;
+  platform: NodeJS.Platform;
+  diagnosticStale: boolean;
+  recommendedCommand: string | null;
+  commands: {
+    installService: string;
+    installShim: string;
+    restoreNative: string;
+  };
+}
+
+const COMMANDS = {
+  installService: "ocx service install",
+  installShim: "ocx codex-shim install",
+  restoreNative: "ocx restore",
+} as const;
+
+export function deriveStartupHealth(inputs: StartupHealthInputs): StartupHealth {
+  const shimEffective = inputs.autostartEnabled && inputs.shimHealthy;
+  const routingInjected = inputs.routingKind === "opencodex-local";
+  const localRoutingDependency = inputs.routingKind === "opencodex-local"
+    || inputs.routingKind === "custom-local"
+    || inputs.routingKind === "unknown";
+  // Script launchers never cover Codex Desktop/app-server surfaces. This is
+  // intentionally conservative on every OS and for WSL-shared Codex homes.
+  const shimCoverage: ShimCoverage = !shimEffective
+    ? "none"
+    : "cli-only";
+  // We can only credit an opencodex service/shim for routing that opencodex owns.
+  // An arbitrary localhost gateway has an independent lifecycle that OCX cannot repair.
+  const ownsLocalRouting = inputs.routingKind === "opencodex-local";
+  const protection: StartupProtection = ownsLocalRouting && inputs.serviceViable
+    ? "service"
+    : ownsLocalRouting && shimEffective
+      ? "shim"
+      : "none";
+  const rebootSafe = !localRoutingDependency || (ownsLocalRouting && inputs.serviceViable);
+  const status: StartupHealthStatus = !localRoutingDependency
+    ? "native"
+    : rebootSafe
+      ? "protected"
+      : "at-risk";
+  const recommendedCommand = status !== "at-risk"
+    ? null
+    : inputs.routingKind === "custom-local" || inputs.routingKind === "unknown"
+      ? COMMANDS.restoreNative
+    : inputs.serviceSupported
+      ? COMMANDS.installService
+      : COMMANDS.restoreNative;
+  return {
+    ...inputs,
+    diagnosticStale: inputs.diagnosticStale ?? false,
+    routingInjected,
+    localRoutingDependency,
+    status,
+    rebootSafe,
+    protection,
+    shimCoverage,
+    recommendedCommand,
+    commands: { ...COMMANDS },
+  };
+}
+
+export interface StartupHealthDiagnostics {
+  routingKind?: CodexRoutingKind;
+  service?: ServiceDiagnostic;
+  shim?: CodexShimDiagnostic;
+}
+
+/** Collect current machine state without mutating config, services, or shims. */
+export function collectStartupHealth(
+  config: Pick<OcxConfig, "codexAutoStart">,
+  diagnostics: StartupHealthDiagnostics = {},
+): StartupHealth {
+  const shim = diagnostics.shim ?? diagnoseCodexShim();
+  const service = diagnostics.service ?? diagnoseService();
+  return deriveStartupHealth({
+    routingKind: diagnostics.routingKind ?? getCodexRoutingKind(),
+    autostartEnabled: codexAutoStartEnabled(config),
+    serviceInstalled: service.installed,
+    serviceViable: service.viable,
+    serviceEnabled: service.enabled,
+    serviceRunning: service.running,
+    serviceStale: service.stale,
+    serviceConflict: service.conflict,
+    serviceSupported: service.supported,
+    shimInstalled: shim.installed,
+    shimHealthy: shim.healthy,
+    platform: process.platform,
+  });
+}
+
+export function startupHealthSummary(health: StartupHealth): string {
+  if (health.status === "native") return health.routingKind === "custom-remote"
+    ? "custom remote Codex routing (no local restart dependency)"
+    : "native Codex routing (no opencodex restart dependency)";
+  if (health.protection === "service") return "protected by background service";
+  const command = health.recommendedCommand ?? health.commands.restoreNative;
+  if (health.routingKind === "unknown") return `AT RISK after restart (Codex routing could not be verified; run '${command}')`;
+  if (health.routingKind === "custom-local") return `AT RISK after restart (custom local gateway lifecycle is not managed by opencodex; run '${command}')`;
+  if (health.shimCoverage === "cli-only") return `AT RISK for Codex Desktop after restart (launcher shim covers CLI scripts only; run '${command}')`;
+  if (health.serviceConflict) return `AT RISK after restart (background service managers conflict; run '${command}')`;
+  if (health.serviceStale) return `AT RISK after restart (background service files are stale; run '${command}')`;
+  if (health.serviceInstalled && !health.serviceViable) return `AT RISK after restart (installed service is disabled, stopped, or unhealthy; run '${command}')`;
+  return `AT RISK after restart (no viable background service; run '${command}')`;
+}