@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/lib/upstream-reachability.ts

@@ -0,0 +1,91 @@
+/**
+ * Classification of upstream fetch rejections that occur before any request
+ * bytes can reach the origin: DNS resolution failure and TCP connect refusal.
+ *
+ * Issue #914: these failures are machine/network-wide, not account-specific —
+ * every Codex pool account shares the provider host, so rotating accounts
+ * cannot repair them. The transport layer previously mapped every non-timeout
+ * rejection to `connect_error`, and at `upstreamFailoverThreshold` that streak
+ * soft-avoided a healthy account and cleared thread affinity.
+ *
+ * Bun collapses DNS failure and TCP refusal into one label class
+ * (`ConnectionRefused` / `FailedToOpenSocket`, errno 0); Node's undici emits
+ * the classic `ECONNREFUSED` / `ENOTFOUND` / `EAI_AGAIN` / `ENETUNREACH` /
+ * `ENETDOWN` / `EHOSTUNREACH` shapes. Both shapes are matched here, on `code`
+ * values only, through a bounded cause chain. Message substrings are never
+ * trusted (a message-only match is a negative case), and labels that can also
+ * appear after the origin saw the credential — `ECONNRESET`, `EPIPE`, TLS
+ * errors, unknown shapes — deliberately stay outside the set.
+ *
+ * Classifier semantics extracted from PR #966 (Yuxin-Qiao) with attribution;
+ * sidecar blast radius intentionally not inherited.
+ *
+ * MUST stay a leaf module: imports nothing from server.ts or adapters.
+ */
+
+import { UpstreamRetryEvidenceError } from "./upstream-retry";
+
+export const PRE_CONNECT_REACHABILITY_CODES = new Set([
+  // Bun: DNS failure and TCP refusal share this class.
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  // Node undici / classic Node shapes.
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EHOSTUNREACH",
+]);
+
+/** Upper bound on how far `cause` chains are inspected. */
+export const MAX_REACHABILITY_CAUSE_DEPTH = 3;
+
+/**
+ * True when the rejection (or a bounded `cause` of it) carries a proven
+ * pre-connection reachability code. Never matches message text.
+ */
+export function isPreConnectReachabilityError(err: unknown): boolean {
+  let current: unknown = err;
+  const seen = new Set<unknown>();
+  for (let depth = 0; depth < MAX_REACHABILITY_CAUSE_DEPTH; depth++) {
+    if (!(current instanceof Error) || seen.has(current)) return false;
+    seen.add(current);
+    const code = (current as { code?: unknown }).code;
+    if (typeof code === "string" && PRE_CONNECT_REACHABILITY_CODES.has(code)) return true;
+    current = current.cause;
+  }
+  return false;
+}
+
+export type TransportFailureKind = "timeout" | "connect_neutral" | "connect_error";
+
+/**
+ * Shared transport rejection classification for Codex pool upstream sends.
+ * Timeouts keep their existing identity (account-transient); proven pre-connect
+ * reachability failures become account-neutral; everything else (ECONNRESET,
+ * EPIPE, TLS, unknown shapes) keeps the existing `connect_error`
+ * account-attributed behavior.
+ */
+export function classifyTransportFailureKind(err: unknown): TransportFailureKind {
+  const evidence = err instanceof UpstreamRetryEvidenceError ? err : undefined;
+  const rejection = evidence ? evidence.cause : err;
+  if (rejection instanceof Error && rejection.name === "TimeoutError") return "timeout";
+  if (isPreConnectReachabilityError(rejection)) {
+    // A transient upstream response (5xx) or a credential-visible connection
+    // reset before the rejection proves the host and credential path were
+    // reached: the failure is account-attributable, never the pre-connection
+    // neutral class (issue #914 review).
+    if (evidence && (evidence.transientStatuses.length > 0 || evidence.resetSeen)) return "connect_error";
+    return "connect_neutral";
+  }
+  return "connect_error";
+}
+
+/** Stable `code` carried by a transport rejection, when there is one. */
+export function transportErrorCode(err: unknown): string | undefined {
+  const rejection = err instanceof UpstreamRetryEvidenceError ? err.cause : err;
+  if (!(rejection instanceof Error)) return undefined;
+  const code = (rejection as { code?: unknown }).code;
+  return typeof code === "string" && code !== "" ? code : undefined;
+}

package/src/lib/upstream-retry.ts

@@ -71,6 +71,107 @@ export async function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<
   });
 }
 
+/**
+ * Best-effort, bounded cancellation of a response body before a retry backoff.
+ *
+ * The 429 paths release the unread body before waiting so sockets do not accumulate under a
+ * rate-limit storm, but a never-settling `cancel()` promise must not be able to block the
+ * abort-aware backoff (client cancel, `maxIntervalMs`, or the cumulative header deadline).
+ * Cancellation is started and its rejection observed; the await is bounded by `timeoutMs`
+ * and the abort signal. This mirrors the rotation-path guarantee (release is initiated, not
+ * awaited forever) while preserving the resource-release intent of the same-target paths.
+ */
+export async function releaseResponseBodyBestEffort(
+  body: ReadableStream<Uint8Array> | null,
+  signal: AbortSignal | undefined,
+  timeoutMs = 1_000,
+): Promise<void> {
+  if (!body) return;
+  if (signal?.aborted) {
+    void body.cancel().catch(() => {});
+    return;
+  }
+  const cancel = body.cancel().catch(() => {});
+  if (!signal) {
+    await Promise.race([cancel, new Promise<void>(resolve => setTimeout(resolve, timeoutMs))]);
+    return;
+  }
+  await new Promise<void>(resolve => {
+    let timer: ReturnType<typeof setTimeout>;
+    /**
+     * Abort hook: clear the bounded-body release timer and settle the promise so a
+     * never-settling cancel() can never block the abort-aware backoff.
+     */
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, timeoutMs);
+    signal.addEventListener("abort", onAbort, { once: true });
+    void cancel.then(() => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Abort-aware sleep that yields an adapter `heartbeat` at least every `heartbeatIntervalMs`.
+ * The Responses bridge treats a returned iterator event as upstream liveness and aborts turns
+ * that stay silent past the stall budget (default 300s), while a retryOn429 wait may legally
+ * reach 600s — so deliberate waits must keep the watchdog fed or a long backoff is killed
+ * mid-turn. The final chunk always yields once, which doubles as the post-wait liveness beat.
+ */
+export async function* sleepWithHeartbeats(
+  ms: number,
+  signal?: AbortSignal,
+  heartbeatIntervalMs = 10_000,
+): AsyncGenerator<{ type: "heartbeat" }> {
+  if (ms <= 0) return;
+  // Guard against a non-positive interval: a zero/negative step would spin the loop forever
+  // while sleepWithAbort early-returns without ever observing the abort signal. NaN must be
+  // normalized too: Math.max(1, NaN) is NaN, which would abort the wait after one beat.
+  const stepMs = Number.isNaN(heartbeatIntervalMs) ? 1 : Math.max(1, heartbeatIntervalMs);
+  let remaining = ms;
+  while (remaining > 0) {
+    const chunk = Math.min(remaining, stepMs);
+    await sleepWithAbort(chunk, signal);
+    remaining -= chunk;
+    yield { type: "heartbeat" };
+  }
+}
+
+export interface SameTarget429WaitOptions {
+  body: ReadableStream<Uint8Array> | null;
+  signal?: AbortSignal;
+  delayMs: number;
+  /**
+   * When set, the wait yields adapter heartbeats so bridge stall watchdogs stay fed.
+   * Omit for pre-stream recovery paths that have no stall watchdog.
+   */
+  heartbeatIntervalMs?: number;
+}
+
+/**
+ * Shared pre-replay prep for opt-in same-target 429 waits:
+ * release the unread 429 body, then sleep (optionally with heartbeats).
+ * Callers still own attempt budgeting, abort re-checks, and the replay itself.
+ */
+export async function* prepareSameTarget429Wait(
+  options: SameTarget429WaitOptions,
+): AsyncGenerator<{ type: "heartbeat" }> {
+  await releaseResponseBodyBestEffort(options.body, options.signal);
+  if (options.heartbeatIntervalMs === undefined) {
+    await sleepWithAbort(options.delayMs, options.signal);
+    return;
+  }
+  yield* sleepWithHeartbeats(options.delayMs, options.signal, options.heartbeatIntervalMs);
+}
+
 export function isConnectionResetError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   // Aborts and timeouts are caller decisions / honest failures — never retryable.
@@ -148,6 +249,39 @@ export interface TransientRetryOptions extends ResetRetryOptions {
 export type UpstreamSendRecovery = "connection-reset" | "transient-5xx";
 type ReplayableFetch = (recovery?: UpstreamSendRecovery) => Promise<Response>;
 
+/**
+ * Rejection thrown by the upstream retry helpers when the terminal attempt
+ * rejects after earlier attempts already produced credential-visible evidence:
+ * transient 5xx responses, or a connection reset after the request was read.
+ *
+ * That evidence proves the host and credential path were reached, so the
+ * failure must stay account-attributed even though the terminal promise looks
+ * like a transport rejection (issue #914 review: mixed 5xx/reset -> rejection
+ * must not be downgraded to the account-neutral pre-connection class). The
+ * original rejection is preserved as `cause` so its code and message stay
+ * inspectable. Extracted from PR #966 (Yuxin-Qiao) with attribution.
+ */
+export class UpstreamRetryEvidenceError extends Error {
+  constructor(
+    public readonly transientStatuses: readonly number[],
+    cause: unknown,
+    /** True when a connection-reset retry already reached the origin. */
+    public readonly resetSeen = false,
+  ) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    const kinds: string[] = [];
+    if (transientStatuses.length > 0) kinds.push("transient 5xx response(s)");
+    if (resetSeen) kinds.push("a credential-visible connection reset");
+    super(
+      kinds.length > 0
+        ? `upstream fetch failed after ${kinds.join(" and ")}: ${detail}`
+        : `upstream fetch failed: ${detail}`,
+      { cause },
+    );
+    this.name = "UpstreamRetryEvidenceError";
+  }
+}
+
 /**
  * Opt out of Bun's keep-alive pool after a connection-reset retry.
  *
@@ -181,12 +315,22 @@ export async function fetchWithResetRetry(
 ): Promise<Response> {
   const attempts = Math.max(1, opts.attempts ?? RESET_RETRY_MAX_ATTEMPTS);
   let lastError: unknown;
+  let sawReset = false;
   for (let attempt = 0; attempt < attempts; attempt++) {
     if (opts.abortSignal?.aborted) throw abortError(opts.abortSignal);
     try {
       return await doFetch(attempt === 0 ? firstRecovery : "connection-reset");
     } catch (err) {
-      if (opts.abortSignal?.aborted || !isConnectionResetError(err) || attempt === attempts - 1) throw err;
+      if (opts.abortSignal?.aborted) throw err;
+      if (!isConnectionResetError(err)) {
+        // A reset that already reached the origin is credential-visible
+        // evidence: keep it attached so the terminal rejection cannot be
+        // downgraded to the pre-connection neutral class (#914 review).
+        if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
+        throw err;
+      }
+      if (attempt === attempts - 1) throw err;
+      sawReset = true;
       lastError = err;
       console.warn(
         `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
@@ -216,6 +360,7 @@ export async function fetchWithTransientRetry(
 ): Promise<Response> {
   const attempts = Math.max(1, opts.attempts ?? TRANSIENT_RETRY_MAX_ATTEMPTS);
   const slowAttemptMs = opts.slowAttemptMs ?? TRANSIENT_RETRY_SLOW_ATTEMPT_MS;
+  const transientStatuses: number[] = [];
   let attemptStart = Date.now();
   let res = await fetchWithResetRetry(doFetch, opts);
   for (let attempt = 0; attempt < attempts - 1; attempt++) {
@@ -233,7 +378,14 @@ export async function fetchWithTransientRetry(
     cancelResponseBodyBestEffort(res);
     await sleepWithAbort(delay, opts.abortSignal);
     attemptStart = Date.now();
-    res = await fetchWithResetRetry(doFetch, opts, "transient-5xx");
+    transientStatuses.push(res.status);
+    try {
+      res = await fetchWithResetRetry(doFetch, opts, "transient-5xx");
+    } catch (err) {
+      // Keep the prior 5xx evidence attached: the origin already responded, so
+      // this rejection is not pre-connection and must not classify as neutral.
+      throw new UpstreamRetryEvidenceError(transientStatuses, err);
+    }
   }
   return res;
 }

package/src/lib/windows-secret-acl.ts

@@ -29,14 +29,175 @@
  *   hardenSecretDir  — same contract for directories.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { env, platform } from "node:process";
 
-const hardenedDirectories = new Set<string>();
-const hardenedPaths = new Set<string>();
+const hardenedDirectories = new Map<string, HardenedIdentity>();
+const hardenedPaths = new Map<string, HardenedIdentity>();
 /** Paths whose harden TIMED OUT this process: do not re-stall every loadConfig on them. */
 const timedOutPaths = new Set<string>();
 
+/**
+ * The memo value: `object:freshness` for a file a harden was actually attributed
+ * to.
+ *
+ * There is deliberately no null member. An observation that cannot be read is
+ * not stored at all — the entry is deleted — because a "recorded as unverifiable"
+ * value was dead code the moment attribution became a before/after comparison,
+ * and a branch nothing can reach is a branch no test can defend.
+ */
+type HardenedIdentity = string;
+
+/**
+ * What a stat can tell us about WHICH OBJECT is at a path.
+ *
+ * Two fields, deliberately separated, because conflating them shipped a bug:
+ *
+ * - `object` — `dev:ino`. Answers "is this the same file". Survives an ACL or
+ *   permission change, which is exactly what we need across an icacls call.
+ * - `freshness` — `ctimeNs`. Answers "has this file's metadata moved since". It
+ *   distinguishes an unlink/recreate that ext4 gave the same inode back for, and
+ *   it MOVES when permissions change.
+ *
+ * The first version used `dev:ino:ctimeNs` for both jobs. Since chmod bumps ctime
+ * — probed, `{ctimeChangedByChmod: true}` — and icacls is a permission change, the
+ * before/after comparison would have rejected its own successful harden and failed
+ * closed on every first harden on Windows. Requiring the identity to be unchanged
+ * across an operation whose entire purpose is to change it is not a strict check;
+ * it is a broken one.
+ */
+interface PathObservation {
+  readonly object: string;
+  readonly freshness: string;
+}
+
+/**
+ * Observe which object is at a path, and how fresh it is.
+ *
+ * `dev:ino` alone is not enough to detect a replacement, which a Linux CI run
+ * proved: ext4 reuses the inode of an unlinked file immediately — 100 of 100
+ * unlink/recreate cycles produced the SAME `ino`, while macOS reused none in 200
+ * and happily reported the earlier fix working. That is why `freshness` exists;
+ * `ctimeNs` differed in 100 of 100 of those same cycles.
+ *
+ * `bigint: true` is used because `ctimeNs` exists only in that variant.
+ *
+ * Test seam: `setStatForTests` replaces this reader so a test can vary `dev`,
+ * `ino`, and `ctimeNs` independently. Mirroring the implementation's string
+ * format in test setup proves nothing about which components production uses —
+ * an audit removed `dev` and all forty tests still passed.
+ *
+ * UNVERIFIED: the plain `ino` is reported to be 0 on NTFS while the bigint form
+ * carries the file index, and the zero-ino guard exists for that case. Neither
+ * Darwin nor Linux CI can confirm it and no pinned-Bun Windows probe has run.
+ * It is defensive code, not a demonstrated platform fact.
+ */
+type StatReader = (path: string) => { dev: bigint; ino: bigint; ctimeNs: bigint };
+
+const defaultStatReader: StatReader = path => {
+  const s = statSync(path, { bigint: true });
+  return { dev: s.dev, ino: s.ino, ctimeNs: s.ctimeNs };
+};
+
+let statReader: StatReader = defaultStatReader;
+
+/** Test seam: drive dev / ino / ctime independently. */
+export function setStatForTests(reader: StatReader | null): void {
+  statReader = reader ?? defaultStatReader;
+}
+
+function observe(targetPath: string): PathObservation | null {
+  try {
+    const s = statReader(targetPath);
+    if (s.ino === 0n) return null;
+    return { object: `${s.dev}:${s.ino}`, freshness: `${s.ctimeNs}` };
+  } catch {
+    return null;
+  }
+}
+
+function memoValue(seen: PathObservation): HardenedIdentity {
+  return `${seen.object}:${seen.freshness}`;
+}
+
+/**
+ * True only when this exact FILE was hardened, not merely this pathname.
+ *
+ * The memo used to be a `Set<string>` of paths. A stable destination — such as
+ * the coordinator database `hardenStableLockFile` hardens — can be unlinked and
+ * recreated at the same name, and the replacement inherited the previous file's
+ * hardening while never having been through icacls. Ephemeral temps escaped this
+ * only because atomic writers call `forgetEphemeralSecretPath` once the temp is
+ * gone; nothing does that for a stable path.
+ */
+function memoSatisfied(cache: Map<string, HardenedIdentity>, targetPath: string): boolean {
+  const remembered = cache.get(targetPath);
+  if (remembered === undefined) return false;
+  const current = observe(targetPath);
+  // Unreadable now is not "unchanged": re-harden rather than trust a value we
+  // cannot confirm still describes what is there.
+  //
+  // A miss RETIRES the entry rather than leaving it. Keeping it left the cache in
+  // a state nothing could justify: after a mismatch and a failed re-harden, the
+  // stale value survived, so restoring the old identity would satisfy it again
+  // without any ACL work. That needs exact-identity ABA to bite — outside the
+  // proof bound this unit claims — but "the consequence is out of scope" is not a
+  // reason to keep an entry we have just proven does not describe what is there.
+  if (current === null || memoValue(current) !== remembered) {
+    cache.delete(targetPath);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Record a harden ONLY if the file we hardened is still the file at that path.
+ *
+ * Reading identity after the ACL sequence returns answers "what is there now",
+ * which is not the same question as "what did icacls operate on". A replacement
+ * landing mid-sequence — probed by swapping the file during the final
+ * `/remove:g` — made the memo remember the REPLACEMENT as hardened, so the next
+ * acquisition skipped ACL work on a file that had never seen it:
+ *
+ *   {identityChangedDuringHarden: true, callsForOriginal: 3, totalCalls: 3,
+ *    replacementWasHardened: false}
+ *
+ * So the OBJECT is captured before the sequence and compared after it. Only the
+ * object — `dev:ino` — because icacls changes permissions, and `ctimeNs` moves
+ * when permissions change (probed: `{ctimeChangedByChmod: true}`). Comparing the
+ * full identity across the call would have rejected every successful harden and
+ * failed closed on the first harden on Windows: the check would have been
+ * demanding that an operation not do the thing it exists to do.
+ *
+ * The memo then stores the object plus the freshness read AFTER hardening, which
+ * is the state a later lookup should match.
+ *
+ * A changed object, or an unreadable observation at either end, means we cannot
+ * say what was hardened: the memo is cleared rather than written, and required
+ * callers fail closed. An optional caller soft-fails, as it does for every other
+ * unproven ACL.
+ *
+ * Returns true when the harden may be reported successful.
+ */
+function recordHarden(
+  cache: Map<string, HardenedIdentity>,
+  targetPath: string,
+  before: PathObservation | null,
+): boolean {
+  const after = observe(targetPath);
+  if (before === null || after === null || before.object !== after.object) {
+    // Never leave a memo behind for a file we cannot vouch for, including one
+    // written by an earlier successful harden of a now-replaced file.
+    cache.delete(targetPath);
+    return false;
+  }
+  cache.set(targetPath, memoValue(after));
+  return true;
+}
+
+const SUBSTITUTED_DIAGNOSTIC =
+  "ACL hardening could not be attributed — the file at this path changed during hardening";
+
 export interface HardenResult {
   ok: boolean;
   diagnostics?: string;
@@ -173,11 +334,37 @@ export function forgetHardenedSecretPath(targetPath: string): void {
   hardenedPaths.delete(targetPath);
 }
 
+/**
+ * Ephemeral-path lifecycle release: clears the success memo AND any timeout
+ * memo keyed by THIS TEMP path in both namespaces. Call only after the temp is
+ * proven absent (successful rename, successful unlink, ENOENT, or an explicit
+ * non-existence check). Never pass a stable destination: destination-keyed
+ * timeout memos are intentional anti-restall state and are not touched here.
+ */
+export function forgetEphemeralSecretPath(tempPath: string): void {
+  hardenedPaths.delete(tempPath);
+  timedOutPaths.delete(`required:${tempPath}`);
+  timedOutPaths.delete(`optional:${tempPath}`);
+}
+
+/** Test seam: timeout memo sets return to baseline after ephemeral cleanup. */
+export function timedOutSecretPathCountForTests(): number {
+  return timedOutPaths.size;
+}
+
 /** Test seam for proving ephemeral success memos do not grow across replacements. */
 export function hardenedSecretPathCountForTests(): number {
   return hardenedPaths.size;
 }
 
+/**
+ * Directory counterpart. It had no seam, and that absence hid a real gap: a
+ * directory-only pathname memo passed every file-based test in this suite.
+ */
+export function hardenedSecretDirCountForTests(): number {
+  return hardenedDirectories.size;
+}
+
 function effectivePlatform(): string {
   return platformOverride ?? platform;
 }
@@ -393,11 +580,13 @@ function hardenEntry(
   targetPath: string,
   directory: boolean,
   opts: HardenOptions,
-  cache: Set<string>,
+  cache: Map<string, HardenedIdentity>,
 ): HardenResult {
-  if (!existsSync(targetPath)) return { ok: true };
+  // Observed absence retires the memo. Leaving it would let a later file at this
+  // path satisfy the cache if the filesystem ever hands back a matching identity.
+  if (!existsSync(targetPath)) { cache.delete(targetPath); return { ok: true }; }
   if (effectivePlatform() !== "win32") return { ok: true };
-  if (cache.has(targetPath)) return { ok: true };
+  if (memoSatisfied(cache, targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   if (timedOutPaths.has(memoKey)) {
     const diagnostics = "ACL hardening skipped — previous attempt timed out";
@@ -410,10 +599,17 @@ function hardenEntry(
   for (let attempt = 0; attempt < 2; attempt++) {
     if (attempt > 0 && deadline - nowFn() <= 0) break; // retry only while budget remains
     try {
+      // Captured BEFORE the sequence: this is the file we are about to harden.
+      const before = observe(targetPath);
       runIcacls(targetPath, directory, deadline);
-      cache.add(targetPath);
+      if (!recordHarden(cache, targetPath, before)) {
+        if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
+        return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
+      }
       return { ok: true };
     } catch (err) {
+      // A substitution is not a transient icacls stall; do not spend the retry on it.
+      if (err instanceof Error && err.message === SUBSTITUTED_DIAGNOSTIC) throw err;
       lastErr = err;
       if (!isTimeoutError(err)) break; // real failures do not retry
     }
@@ -437,11 +633,11 @@ async function hardenEntryAsync(
   targetPath: string,
   directory: boolean,
   opts: HardenOptions,
-  cache: Set<string>,
+  cache: Map<string, HardenedIdentity>,
 ): Promise<HardenResult> {
-  if (!existsSync(targetPath)) return { ok: true };
+  if (!existsSync(targetPath)) { cache.delete(targetPath); return { ok: true }; }
   if (effectivePlatform() !== "win32") return { ok: true };
-  if (cache.has(targetPath)) return { ok: true };
+  if (memoSatisfied(cache, targetPath)) return { ok: true };
   const memoKey = timeoutMemoKey(targetPath, opts);
   if (timedOutPaths.has(memoKey)) {
     const diagnostics = "ACL hardening skipped — previous attempt timed out";
@@ -454,10 +650,15 @@ async function hardenEntryAsync(
   for (let attempt = 0; attempt < 2; attempt++) {
     if (attempt > 0 && deadline - nowFn() <= 0) break;
     try {
+      const before = observe(targetPath);
       await runIcaclsAsync(targetPath, directory, deadline);
-      cache.add(targetPath);
+      if (!recordHarden(cache, targetPath, before)) {
+        if (opts.required) throw new Error(SUBSTITUTED_DIAGNOSTIC);
+        return { ok: false, diagnostics: SUBSTITUTED_DIAGNOSTIC };
+      }
       return { ok: true };
     } catch (err) {
+      if (err instanceof Error && err.message === SUBSTITUTED_DIAGNOSTIC) throw err;
       lastErr = err;
       if (!isTimeoutError(err)) break;
     }

package/src/lib/winsw.ts

@@ -20,7 +20,8 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandUserPath, getConfigDir, loadConfig } from "../config";
 import { recordOwnedConfigPath } from "./config-ownership";
-import { durableBunPath } from "./bun-runtime";
+import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from "./bun-runtime";
+import type { BunRuntimeSource } from "./bun-runtime";
 import { serviceApiTokenFilePath } from "./service-secrets";
 
 export const WINSW_VERSION = "2.12.0";
@@ -64,6 +65,8 @@ function currentCodexHomeAbsolute(): string {
 
 export interface WinswEntry {
   bun: string;
+  /** Provenance of `bun`, resolved together with it so the two can never disagree. */
+  bunRuntimeSource: BunRuntimeSource;
   cli: string;
 }
 
@@ -95,6 +98,8 @@ export function buildWinswXml(entry: WinswEntry, env: NodeJS.ProcessEnv = proces
   const aclTimeout = env.OPENCODEX_ACL_TIMEOUT_MS?.trim();
   const envLines = [
     `  <env name="OCX_SERVICE" value="1"/>`,
+    `  <env name="${BUN_RUNTIME_SOURCE_ENV}" value="${xmlEscape(entry.bunRuntimeSource)}"/>`,
+    `  <env name="${BUN_RUNTIME_PATH_ENV}" value="${xmlEscape(entry.bun)}"/>`,
     `  <env name="OCX_API_TOKEN_FILE" value="${xmlEscape(serviceApiTokenFilePath())}"/>`,
     `  <env name="PATH" value="${xmlEscape(env.PATH ?? "")}"/>`,
     env.CODEX_HOME?.trim() ? `  <env name="CODEX_HOME" value="${xmlEscape(currentCodexHomeAbsolute())}"/>` : null,
@@ -363,7 +368,7 @@ export function winswStatusSummary(): string {
   if (status === "nonexistent") {
     // A stale SCM service can outlive a deleted exe; surface the repair path.
     return existsSync(winswXmlPath()) && !existsSync(winswExePath())
-      ? "native assets present but WinSW binary missing — run 'ocx service install --native' to repair"
+      ? "native assets present but WinSW binary missing — run 'ocx service repair'"
       : "";
   }
   return `native (WinSW ${WINSW_VERSION}): ${status}`;
@@ -371,5 +376,6 @@ export function winswStatusSummary(): string {
 
 /** Default entry mirrors the Task Scheduler baking: durable Bun + cli.ts. */
 export function defaultWinswEntry(cliDir: string): WinswEntry {
-  return { bun: durableBunPath(), cli: join(cliDir, "cli", "index.ts") };
+  const runtime = durableBunRuntime();
+  return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(cliDir, "cli", "index.ts") };
 }