@iislee/opencodex 2.11.0 → 2.31.0

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.
@@ -114,6 +215,7 @@ export async function fetchWithAttemptDeadline(
   timeoutMs: number,
   abortSignal?: AbortSignal,
   preferIdentityEncoding = false,
+  executor: typeof globalThis.fetch = globalThis.fetch,
 ): Promise<Response> {
   const attemptTimeout = clearableDeadline(timeoutMs, abortSignal);
   const headers = new Headers(init.headers);
@@ -121,7 +223,7 @@ export async function fetchWithAttemptDeadline(
     headers.set("accept-encoding", "identity");
   }
   try {
-    return await fetch(url, {
+    return await executor(url, {
       ...init,
       headers,
       signal: attemptTimeout.signal,
@@ -148,6 +250,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 +316,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 +361,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 +379,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-atomic-replace.ts

@@ -0,0 +1,155 @@
+/**
+ * Windows-tolerant atomic replace.
+ *
+ * POSIX `rename()` replaces the destination entry unconditionally. Windows can
+ * refuse the same call with EBUSY, EPERM or EACCES while another process holds
+ * the target open — a real-time scanner that just indexed the file, a sync
+ * client, a backup agent. The hold is usually momentary, so a bounded retry
+ * turns an operational failure back into a successful publish.
+ *
+ * The envelope is deliberately small: two retries, 25ms then 50ms, about 75ms
+ * total. It is sized for a scanner blinking, not for a file someone actually
+ * has open. Widening it without evidence would trade a rare failure for a
+ * routine stall.
+ *
+ * This lives in its own module rather than in config.ts because
+ * config-ownership.ts is one of its callers and config.ts already imports
+ * config-ownership.ts — exporting it from there would close an import cycle.
+ */
+
+import { renameSync } from "node:fs";
+
+/**
+ * Which durable publisher retried. A closed union on purpose: the value is a
+ * label in a diagnostic surface, and a path-derived string could carry a
+ * username. The type is the enforcement — a path cannot be passed here without
+ * failing typecheck. (`privacy:scan` reads file text and cannot see a runtime
+ * value, so it is a backstop for the response body, not the guard.)
+ */
+export type ReplacePublisher =
+  | "config"
+  | "prompt-journal"
+  | "config-ownership"
+  | "claude-agents"
+  | "lab-automation"
+  | "lab-ledger"
+  | "storage-cleanup"
+  | "tray";
+
+/** The Windows error codes this module treats as a momentary hold. */
+export type ReplaceRetryCode = "EBUSY" | "EPERM" | "EACCES";
+
+export interface ReplaceRetryCounts {
+  /** Replaces that hit this code and were retried. */
+  retried: number;
+  /** Replaces that exhausted every retry and threw. */
+  exhausted: number;
+}
+
+/**
+ * Keyed by publisher AND code. The code is the diagnostic half: EBUSY from a
+ * scanner, EACCES from a permissions problem and EPERM from a lock are three
+ * different stories, and collapsing them would leave the counters unable to
+ * answer the question they exist for.
+ */
+const counters = new Map<string, ReplaceRetryCounts>();
+
+function counterKey(publisher: ReplacePublisher, code: ReplaceRetryCode): string {
+  return `${publisher}:${code}`;
+}
+
+function bump(
+  publisher: ReplacePublisher,
+  code: ReplaceRetryCode,
+  field: keyof ReplaceRetryCounts,
+): void {
+  const key = counterKey(publisher, code);
+  const current = counters.get(key) ?? { retried: 0, exhausted: 0 };
+  current[field] += 1;
+  counters.set(key, current);
+}
+
+/**
+ * Process-lifetime snapshot, keyed `publisher:CODE`. These reset on restart,
+ * which is fine: the question they answer is "does this ever fire at all", not
+ * "how often per hour".
+ */
+export function readWindowsReplaceRetryCounters(): Record<string, ReplaceRetryCounts> {
+  const out: Record<string, ReplaceRetryCounts> = {};
+  for (const [key, counts] of counters) out[key] = { ...counts };
+  return out;
+}
+
+/** Test-only: the counters are module state and cases must not leak into each other. */
+export function resetWindowsReplaceRetryCountersForTests(): void {
+  counters.clear();
+}
+export interface AtomicRenameIO {
+  platform: NodeJS.Platform;
+  rename: (source: string, destination: string) => void;
+  sleep: (milliseconds: number) => void;
+}
+
+const MAX_RETRIES = 2;
+
+/**
+ * Windows sharing violations only, returning the code so the caller can record
+ * which one. Any other error is the caller's to see, immediately.
+ */
+function transientWindowsReplaceCode(
+  platform: NodeJS.Platform,
+  error: unknown,
+): ReplaceRetryCode | null {
+  if (platform !== "win32") return null;
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "EBUSY" || code === "EPERM" || code === "EACCES" ? code : null;
+}
+
+export function renameAtomicFile(
+  source: string,
+  destination: string,
+  io: AtomicRenameIO = {
+    platform: process.platform,
+    rename: renameSync,
+    sleep: Bun.sleepSync,
+  },
+  publisher: ReplacePublisher = "config",
+): void {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      io.rename(source, destination);
+      return;
+    } catch (error) {
+      const code = transientWindowsReplaceCode(io.platform, error);
+      if (!code) throw error;
+      if (attempt >= MAX_RETRIES) {
+        bump(publisher, code, "exhausted");
+        throw error;
+      }
+      bump(publisher, code, "retried");
+      io.sleep(25 * (attempt + 1));
+    }
+  }
+}
+
+export async function renameAtomicFileAsync(
+  source: string,
+  destination: string,
+  publisher: ReplacePublisher = "config",
+): Promise<void> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      renameSync(source, destination);
+      return;
+    } catch (error) {
+      const code = transientWindowsReplaceCode(process.platform, error);
+      if (!code) throw error;
+      if (attempt >= MAX_RETRIES) {
+        bump(publisher, code, "exhausted");
+        throw error;
+      }
+      bump(publisher, code, "retried");
+      await Bun.sleep(25 * (attempt + 1));
+    }
+  }
+}

package/src/lib/windows-elevation.ts

@@ -21,6 +21,13 @@ type TrustedSystemDirectoryResolver = () => string;
 type IsUserAnAdmin = () => number;
 type WindowsElevationProbe = () => boolean | null;
 
+export class WindowsSystemDirectoryFfiUnavailableError extends Error {
+  constructor() {
+    super("Failed to load GetSystemDirectoryW from kernel32.dll.");
+    this.name = "WindowsSystemDirectoryFfiUnavailableError";
+  }
+}
+
 let getSystemDirectoryWFn: GetSystemDirectoryW | null | undefined;
 let trustedSystemDirectoryResolverForTests: TrustedSystemDirectoryResolver | null = null;
 let isUserAnAdminFn: (() => boolean) | null | undefined;
@@ -114,7 +121,7 @@ export function resolveTrustedWindowsSystemDirectory(): string {
   }
   const getSystemDirectoryW = loadGetSystemDirectoryW();
   if (!getSystemDirectoryW) {
-    throw new Error("Failed to load GetSystemDirectoryW from kernel32.dll.");
+    throw new WindowsSystemDirectoryFfiUnavailableError();
   }
 
   let size = 260;
@@ -168,7 +175,7 @@ export function assertTrustedSystemExecutableForTests(candidate: string, label:
   return assertTrustedSystemExecutable(candidate, label);
 }
 
-type ElevationExeOverrides = { powershell?: string; schtasks?: string };
+type ElevationExeOverrides = { powershell?: string; schtasks?: string; taskkill?: string; icacls?: string };
 let elevationExeOverridesForTests: ElevationExeOverrides | null = null;
 
 /**
@@ -204,6 +211,24 @@ export function resolveTrustedWindowsSchtasksExe(): string {
   return assertTrustedSystemExecutable(candidate, "schtasks.exe");
 }
 
+/** Absolute path to System32\\taskkill.exe from a trusted system directory. */
+export function resolveTrustedWindowsTaskkillExe(): string {
+  if (elevationExeOverridesForTests?.taskkill) {
+    return elevationExeOverridesForTests.taskkill;
+  }
+  const candidate = join(resolveTrustedWindowsSystemDirectory(), "taskkill.exe");
+  return assertTrustedSystemExecutable(candidate, "taskkill.exe");
+}
+
+/** Absolute path to System32\\icacls.exe from a trusted system directory. */
+export function resolveTrustedWindowsIcaclsExe(): string {
+  if (elevationExeOverridesForTests?.icacls) {
+    return elevationExeOverridesForTests.icacls;
+  }
+  const candidate = join(resolveTrustedWindowsSystemDirectory(), "icacls.exe");
+  return assertTrustedSystemExecutable(candidate, "icacls.exe");
+}
+
 /** Stable machine-readable marker for a denied `schtasks /create`. Crosses the CLI→proxy boundary. */
 export const WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER =
   "OCX_ERROR_CODE=WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED";
@@ -605,6 +630,49 @@ export function runWindowsElevated(file: string, args: string[]): Promise<number
   return startPowerShellCommand(script).completion.then(result => result.exitCode);
 }
 
+/**
+ * Register one scheduled-task definition without exposing a mutable XML pathname to
+ * the elevated process. The XML bytes are fixed in the encoded PowerShell command
+ * before UAC; Register-ScheduledTask receives that string directly after elevation.
+ */
+export function runWindowsElevatedScheduledTaskRegistration(
+  taskName: string,
+  xml: string,
+): Promise<number> {
+  const xmlBase64 = Buffer.from(xml, "utf16le").toString("base64");
+  const powerShellPath = windowsPowerShell();
+  const powerShellDirectory = powerShellPath.replace(/[\\/][^\\/]+$/, "");
+  const scheduledTasksModule = `${powerShellDirectory}\\Modules\\ScheduledTasks\\ScheduledTasks.psd1`;
+  const inner = [
+    `$taskName = ${psSingleQuote(taskName)}`,
+    `$xmlBase64 = ${psSingleQuote(xmlBase64)}`,
+    "$xml = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($xmlBase64))",
+    `$module = Microsoft.PowerShell.Core\\Import-Module -Name ${psSingleQuote(scheduledTasksModule)} -PassThru -Force -ErrorAction Stop`,
+    "$registerTask = $module.ExportedCommands['Register-ScheduledTask']",
+    "if ($null -eq $registerTask) { throw 'Trusted ScheduledTasks module does not export Register-ScheduledTask.' }",
+    "& $registerTask -TaskName $taskName -Xml $xml -Force -ErrorAction Stop | Out-Null",
+  ].join("; ");
+  const encodedCommand = Buffer.from(inner, "utf16le").toString("base64");
+  const script = [
+    `$p = Start-Process -FilePath ${psSingleQuote(powerShellPath)}`,
+    ` -ArgumentList ${psSingleQuote(buildWindowsElevatedArgumentList([
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-EncodedCommand",
+      encodedCommand,
+    ]))}`,
+    " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;",
+    `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`,
+    "$null = $p.Handle;",
+    `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`,
+    "exit $p.ExitCode",
+  ].join("");
+
+  return startPowerShellCommand(script).completion.then(result => result.exitCode);
+}
+
 /**
  * Build the elevated (post-UAC) script: create → run → optional delete rollback.
  * Returns only OpenCodex protocol exit codes (never raw schtasks codes, never 1223).