@remodex/rmx 1.0.2

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

@@ -0,0 +1,263 @@
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+/**
+ * Shared client-facing SSE payload rewrite shell.
+ *
+ * Multiple opt-in transforms (image-gen namespace restore, item-id repair, …) compose into one
+ * parse/stringify pass so a tee'd stream is not re-framed twice per event.
+ */
+
+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/);
+  if (!match || match.index === undefined) return null;
+  return {
+    block: buffer.slice(0, match.index),
+    delimiter: match[0],
+    rest: buffer.slice(match.index + match[0].length),
+  };
+}
+
+/** Join all data lines from one SSE event according to the event-stream field rules. */
+export function sseDataPayload(block: string): string | null {
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    data.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  return data.length > 0 ? data.join("\n") : null;
+}
+
+/** Replace an SSE event's data field while preserving non-data fields and newline style. */
+export function replaceSseDataPayload(block: string, payload: string): string {
+  const newline = block.includes("\r\n") ? "\r\n" : "\n";
+  const lines = block.split(/\r?\n/);
+  const rewritten: string[] = [];
+  let replaced = false;
+  for (const line of lines) {
+    if (!line.startsWith("data:")) {
+      rewritten.push(line);
+      continue;
+    }
+    if (!replaced) {
+      rewritten.push(`data: ${payload}`);
+      replaced = true;
+    }
+  }
+  return replaced ? rewritten.join(newline) : block;
+}
+
+/** Apply rewrites left-to-right; empty list is identity. */
+export function composeSsePayloadRewrites(...rewrites: SsePayloadRewrite[]): SsePayloadRewrite {
+  if (rewrites.length === 0) return (payload) => payload;
+  if (rewrites.length === 1) return rewrites[0]!;
+  return (payload) => {
+    let next = payload;
+    for (const rewrite of rewrites) next = rewrite(next);
+    return next;
+  };
+}
+
+/**
+ * Relay an SSE body through a single JS pull wrapper, rewriting each event's data payload in place.
+ * Non-data fields and framing are preserved; invalid JSON payloads are left to the rewrite callback.
+ */
+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;
+    const nextBytes = bufferBytes + encoder.encode(fragment).byteLength;
+    const reservation = translatorBudget.reserveTransient(nextBytes, { kind: "live_transient" });
+    try {
+      buffer += fragment;
+      reservation.commitRetained();
+      translatorBudget.releaseRetained(bufferBytes, { kind: "live_transient" });
+      bufferBytes = nextBytes;
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+  };
+
+  const replaceBuffer = (next: string): void => {
+    const nextBytes = encoder.encode(next).byteLength;
+    const reservation = translatorBudget.reserveTransient(nextBytes, { kind: "live_transient" });
+    reservation.commitRetained();
+    buffer = next;
+    translatorBudget.releaseRetained(bufferBytes, { kind: "live_transient" });
+    bufferBytes = nextBytes;
+  };
+
+  const enqueueText = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    text: string,
+  ): void => {
+    const bytes = encoder.encode(text).byteLength;
+    const reservation = translatorBudget.reserveTransient(bytes, { kind: "live_transient" });
+    try {
+      const encoded = encoder.encode(text);
+      reservation.commitRetained();
+      controller.enqueue(encoded);
+      translatorBudget.releaseRetained(bytes, { kind: "live_transient" });
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+  };
+
+  const releaseBuffer = (): void => {
+    translatorBudget.releaseRetained(bufferBytes, { kind: "live_transient" });
+    buffer = "";
+    bufferBytes = 0;
+  };
+
+  const emitProcessedBlocks = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    flushFinal = false,
+  ): number => {
+    let emitted = 0;
+    let next: { block: string; delimiter: string; rest: string } | null;
+    while ((next = nextSseBlock(buffer))) {
+      replaceBuffer(next.rest);
+      for (const outBlock of rewrite(next.block)) {
+        enqueueText(controller, outBlock + next.delimiter);
+        emitted += 1;
+      }
+    }
+    if (flushFinal && buffer.length > 0) {
+      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 : ""));
+        emitted += 1;
+      }
+      releaseBuffer();
+    }
+    return emitted;
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        // A network chunk is not an SSE-event boundary. Bun may not issue a
+        // second pull after a fulfilled pull enqueues nothing, so keep reading
+        // until at least one complete rewritten block is available or EOF is
+        // reached. This also handles block rewrites that intentionally drop an
+        // event without parking the client stream.
+        for (;;) {
+          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;
+          }
+          appendBuffer(decoder.decode(value, { stream: true }));
+          if (emitProcessedBlocks(controller) > 0) return;
+        }
+      } 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-action-control.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { durableBunPath } from "../lib/bun-runtime";
+import {
+  WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER,
+  isWindowsSchtasksCreateAccessDenied,
+} from "../lib/windows-elevation";
+import {
+  finalizeWindowsSchedulerServiceRegistration,
+  type ElevatedReconciliationOutcome,
+  type FinalizeWindowsSchedulerOptions,
+  type FinalizeWindowsSchedulerResult,
+  type WindowsSchedulerTaskProbe,
+} from "../service";
+
+export type StartupInstallAction = "install-service" | "install-shim";
+
+export type StartupInstallState =
+  | { status: "idle" }
+  | {
+      status: "running";
+      action: StartupInstallAction;
+      attemptId: string;
+      startedAt: number;
+    }
+  | {
+      status: "indeterminate";
+      action: "install-service";
+      attemptId: string;
+      startedAt: number;
+      timedOutAt: number;
+      reconciliation: Promise<ElevatedReconciliationOutcome>;
+    }
+  | {
+      status: "blocked";
+      reason: "partial-elevated-install";
+      action: "install-service";
+      attemptId: string;
+      detail: string;
+    };
+
+const INSTALL_DETAIL_LIMIT = 2_000;
+const INDETERMINATE_MESSAGE =
+  "Windows elevation timed out, but the elevated Task Scheduler transaction may still be running. New service installation attempts are temporarily blocked while Remodex reconciles its final state.";
+const RECONCILING_MESSAGE =
+  "A previous elevated Windows service installation is still being reconciled. Wait for it to finish or inspect the Task Scheduler state before retrying.";
+const BLOCKED_PARTIAL_MESSAGE =
+  "A previous elevated Windows service installation left a partial Task Scheduler state. Remove the Remodex scheduler task (or confirm it is absent), then clear the install block before retrying.";
+
+let installState: StartupInstallState = { status: "idle" };
+
+type FinalizeFn = (
+  script?: string,
+  options?: FinalizeWindowsSchedulerOptions,
+) => Promise<FinalizeWindowsSchedulerResult>;
+let finalizeImpl: FinalizeFn = finalizeWindowsSchedulerServiceRegistration;
+
+/** Test-only seam so elevation retry tests do not mock.module the service package. */
+export function setStartupInstallFinalizeForTests(next: FinalizeFn | null): void {
+  finalizeImpl = next ?? finalizeWindowsSchedulerServiceRegistration;
+}
+
+/** Snapshot of the install lock for diagnostics and tests. */
+export function getStartupInstallState(): StartupInstallState {
+  return installState;
+}
+
+/** True when this attempt still owns the active/indeterminate/blocked lock. */
+export function ownsStartupInstallAttempt(attemptId: string): boolean {
+  return (installState.status === "running"
+    || installState.status === "indeterminate"
+    || installState.status === "blocked")
+    && installState.attemptId === attemptId;
+}
+
+/**
+ * Clear a partial-install block after the operator has cleaned up Task Scheduler.
+ * Requires an observed probe and clears only when the task is proven absent.
+ * Does not itself delete the task.
+ */
+export function clearStartupInstallPartialBlock(options: {
+  probe: WindowsSchedulerTaskProbe;
+}): { cleared: boolean; detail: string } {
+  if (installState.status !== "blocked") {
+    return { cleared: false, detail: `Install lock is ${installState.status}, not blocked.` };
+  }
+  if (options.probe.status === "present") {
+    return {
+      cleared: false,
+      detail: "Remodex Task Scheduler task is still present; remove it before clearing the block.",
+    };
+  }
+  if (options.probe.status === "unknown") {
+    return {
+      cleared: false,
+      detail: `Could not verify Task Scheduler absence (${options.probe.detail}); not clearing the block.`,
+    };
+  }
+  installState = { status: "idle" };
+  return { cleared: true, detail: "Partial-install block cleared." };
+}
+
+/** Test-only reset of the install lock. */
+export function resetStartupInstallStateForTests(): void {
+  installState = { status: "idle" };
+}
+
+export function startupInstallArgv(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): string[] {
+  if (action === "install-service") {
+    return options?.repair ? ["service", "repair"] : ["service", "install"];
+  }
+  return ["codex-shim", "install"];
+}
+
+export interface CliInstallFailure {
+  /** Machine marker such as OCX_ERROR_CODE=..., when present in any stream. */
+  code: string | null;
+  stdout: string;
+  stderr: string;
+  message: string;
+  /** Bounded user-facing diagnostic (may append the marker if truncated away). */
+  detail: string;
+}
+
+function extractOcxErrorCode(text: string): string | null {
+  const match = text.match(/OCX_ERROR_CODE=[A-Z0-9_]+/);
+  return match ? match[0] : null;
+}
+
+/**
+ * Classify a CLI install failure, keeping the machine marker separate from the
+ * truncated user-facing diagnostic.
+ */
+export function classifyCliInstallFailure(stdout: string, stderr: string, error: Error): CliInstallFailure {
+  const stdoutText = stdout.trim();
+  const stderrText = stderr.trim();
+  const message = error.message.trim();
+  const combined = [stderrText, stdoutText, message].filter(Boolean).join("\n");
+  const code = extractOcxErrorCode(combined);
+  let detail = combined || message;
+  if (detail.length > INSTALL_DETAIL_LIMIT) {
+    const truncated = detail.slice(0, INSTALL_DETAIL_LIMIT);
+    detail = code && !truncated.includes(code)
+      ? `${truncated}\n${code}… (truncated)`
+      : `${truncated}… (truncated)`;
+  }
+  return { code, stdout: stdoutText, stderr: stderrText, message, detail };
+}
+
+/** @deprecated Prefer classifyCliInstallFailure; kept for existing tests. */
+export function installFailureDetail(stdout: string, stderr: string, error: Error): string {
+  return classifyCliInstallFailure(stdout, stderr, error).detail;
+}
+
+function runCliInstall(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): Promise<{ stdout: string; stderr: string }> {
+  const bun = durableBunPath();
+  const cli = join(import.meta.dir, "..", "cli", "index.ts");
+  const argv = [cli, ...startupInstallArgv(action, options)];
+  return new Promise((resolve, reject) => {
+    execFile(bun, argv, {
+      encoding: "utf8",
+      env: process.env,
+      timeout: 60_000,
+      windowsHide: true,
+      maxBuffer: 256 * 1024,
+    }, (error, stdout, stderr) => {
+      if (error) {
+        const failure = classifyCliInstallFailure(stdout, stderr, error);
+        reject(Object.assign(new Error(failure.detail), { ocxInstallFailure: failure }));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+function installFailureCode(error: unknown): string | null {
+  if (error && typeof error === "object" && "ocxInstallFailure" in error) {
+    const failure = (error as { ocxInstallFailure?: CliInstallFailure }).ocxInstallFailure;
+    if (failure?.code) return failure.code;
+  }
+  const detail = error instanceof Error ? error.message : String(error);
+  return extractOcxErrorCode(detail);
+}
+
+function rejectIfBusy(_action: StartupInstallAction): Error | null {
+  if (installState.status === "running") {
+    return new Error(`Another startup installation is already running: ${installState.action}`);
+  }
+  if (installState.status === "indeterminate") {
+    return new Error(RECONCILING_MESSAGE);
+  }
+  if (installState.status === "blocked") {
+    return new Error(BLOCKED_PARTIAL_MESSAGE);
+  }
+  return null;
+}
+
+function applyReconciliationOutcome(
+  attemptId: string,
+  outcome: ElevatedReconciliationOutcome,
+): void {
+  if (installState.status !== "indeterminate" || installState.attemptId !== attemptId) {
+    return;
+  }
+  if (outcome === "blocked-partial") {
+    installState = {
+      status: "blocked",
+      reason: "partial-elevated-install",
+      action: "install-service",
+      attemptId,
+      detail: BLOCKED_PARTIAL_MESSAGE,
+    };
+    return;
+  }
+  installState = { status: "idle" };
+}
+
+/**
+ * Execute the existing fixed CLI installer outside the proxy event loop.
+ *
+ * Repair mode (`options.repair`) runs `rmx service repair` — asset rewrite + restart
+ * without Task Scheduler re-registration, so it must not enter the UAC elevation path.
+ *
+ * After an elevation request timeout the lock becomes `indeterminate` until the
+ * original elevated transaction completes and is reconciled. A process restart
+ * clears this in-memory lock — callers must then inspect Task Scheduler reality
+ * (see evaluateSchedulerInstallRestartReconciliation) before installing again.
+ */
+export function runStartupInstallAction(
+  action: StartupInstallAction,
+  options?: { repair?: boolean },
+): Promise<{ message: string }> {
+  const busy = rejectIfBusy(action);
+  if (busy) return Promise.reject(busy);
+
+  const repair = options?.repair === true;
+  const attemptId = randomUUID();
+  const startedAt = Date.now();
+  installState = { status: "running", action, attemptId, startedAt };
+
+  const operation = (async () => {
+    try {
+      await runCliInstall(action, { repair });
+    } catch (error) {
+      const code = installFailureCode(error);
+      const detail = error instanceof Error ? error.message : String(error);
+      // Elevate only for fresh install + structured Task Scheduler /create access denial —
+      // never for repair, WinSW removal, asset writes, or generic permission errors.
+      if (
+        !repair
+        && action === "install-service"
+        && process.platform === "win32"
+        && (code === WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER
+          || isWindowsSchtasksCreateAccessDenied(detail))
+      ) {
+        const finalized = await finalizeImpl(undefined, {
+          attemptId,
+          stillOwnsAttempt: ownsStartupInstallAttempt,
+        });
+        if (finalized.kind === "indeterminate") {
+          const ownedAttemptId = finalized.attemptId;
+          installState = {
+            status: "indeterminate",
+            action: "install-service",
+            attemptId: ownedAttemptId,
+            startedAt,
+            timedOutAt: Date.now(),
+            reconciliation: finalized.reconciliation,
+          };
+          void finalized.reconciliation.then(
+            outcome => {
+              applyReconciliationOutcome(ownedAttemptId, outcome);
+            },
+            () => {
+              // Fail closed: a rejected reconciliation must not leave an unhandled rejection
+              // or silently idle the lock while Task Scheduler state may still be partial.
+              applyReconciliationOutcome(ownedAttemptId, "blocked-partial");
+            },
+          );
+          throw new Error(INDETERMINATE_MESSAGE);
+        }
+      } else {
+        throw error;
+      }
+    }
+    if (action === "install-service") {
+      return { message: repair ? "Background service repaired." : "Background service installed." };
+    }
+    return {
+      message: repair ? "Codex launcher shim repaired." : "Codex launcher shim installed.",
+    };
+  })();
+
+  return operation.finally(() => {
+    // Do not clear an indeterminate or blocked lock from a timed-out elevation.
+    if (installState.status === "running" && installState.attemptId === attemptId) {
+      installState = { status: "idle" };
+    }
+  });
+}

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

@@ -0,0 +1,119 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { codexAutoStartEnabled } from "../config";
+import { deriveStartupHealth, type StartupHealth } from "../codex/autostart-health";
+import { getCodexRoutingKind } from "../codex/inject";
+import { diagnoseCodexShim } from "../codex/shim";
+import { durableBunPath } from "../lib/bun-runtime";
+import type { OcxConfig } from "../types";
+import { truncateRetainedUtf8 } from "../lib/admission";
+
+const CACHE_TTL_MS = 30_000;
+const PROBE_TIMEOUT_MS = 5_000;
+const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
+let cached: { timestamp: number; value: StartupHealth } | null = null;
+let inflight: Promise<StartupHealth> | null = null;
+let generation = 0;
+
+export function markStartupHealthDiagnosticStale(value: StartupHealth): StartupHealth {
+  if (!value.localRoutingDependency) return { ...value, diagnosticStale: true };
+  return {
+    ...value,
+    status: "at-risk",
+    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.serviceInstalled && !value.serviceConflict
+        ? value.commands.repairService
+        : value.commands.installService,
+  };
+}
+
+function conservativeFallback(config: Pick<OcxConfig, "codexAutoStart">): StartupHealth {
+  const shim = diagnoseCodexShim();
+  return deriveStartupHealth({
+    routingKind: getCodexRoutingKind(),
+    autostartEnabled: codexAutoStartEnabled(config),
+    serviceInstalled: false,
+    serviceViable: false,
+    serviceEnabled: false,
+    serviceRunning: false,
+    serviceStale: false,
+    serviceConflict: false,
+    serviceSupported: process.platform === "win32" || process.platform === "darwin" || process.platform === "linux",
+    shimInstalled: shim.installed,
+    shimHealthy: shim.healthy,
+    platform: process.platform,
+    diagnosticStale: true,
+  });
+}
+
+function runProbe(config: Pick<OcxConfig, "codexAutoStart">): Promise<StartupHealth> {
+  const bun = durableBunPath();
+  const cli = join(import.meta.dir, "..", "cli", "index.ts");
+  return new Promise(resolve => {
+    execFile(bun, [cli, "__startup-health"], {
+      encoding: "utf8",
+      env: process.env,
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true,
+      maxBuffer: 256 * 1024,
+    }, (error, stdout) => {
+      if (!error) {
+        const lines = stdout.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+          try {
+            const parsed = JSON.parse(lines[index]) as StartupHealth;
+            if (["native", "protected", "at-risk"].includes(parsed.status) && typeof parsed.rebootSafe === "boolean") {
+              resolve({
+                ...parsed,
+                recommendedCommand: parsed.recommendedCommand === null
+                  ? null
+                  : 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),
+                },
+                diagnosticStale: false,
+              });
+              return;
+            }
+          } catch { /* scan earlier output; config repair messages may precede JSON */ }
+        }
+      }
+      resolve(cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config));
+    });
+  });
+}
+
+function refreshInBackground(config: Pick<OcxConfig, "codexAutoStart">): void {
+  if (inflight) return;
+  const startedGeneration = generation;
+  const probe = runProbe(config).then(value => {
+    if (startedGeneration === generation) cached = { timestamp: Date.now(), value };
+    return value;
+  });
+  inflight = probe.finally(() => {
+    if (inflight === probe || startedGeneration === generation) inflight = null;
+  });
+}
+
+/** Stale-while-revalidate: service-manager probes never hold open a model/UI request. */
+export async function getCachedStartupHealth(config: Pick<OcxConfig, "codexAutoStart">): Promise<StartupHealth> {
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) return cached.value;
+  refreshInBackground(config);
+  return cached ? markStartupHealthDiagnosticStale(cached.value) : conservativeFallback(config);
+}
+
+export function invalidateStartupHealthCache(): void {
+  generation += 1;
+  cached = null;
+  inflight = null;
+}