@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/lib/state-store-registrations.ts

@@ -32,7 +32,11 @@ import {
   reconcileOAuthFlowState,
   sweepExpiredXaiPermanentFailureVerdicts,
 } from "../oauth";
-import { sweepExpiredAnthropicRoutingHealth } from "../oauth/anthropic-routing";
+import { sweepAllAnthropicRoutingHealth, reconcileAnthropicRoutingState } from "../oauth/anthropic-routing";
+import { reconcileAllAnthropicFamilyQuota } from "../oauth/anthropic-model-quota";
+import { reconcileAllAnthropicRatePauses, sweepExpiredAllAnthropicRatePauses } from "../oauth/anthropic-rate-limit-policy";
+import { reconcileAllAnthropicCooldownGenerations } from "../providers/quota/anthropic-cooldown-recovery";
+import { configuredAnthropicInstance } from "../providers/anthropic-instance";
 import { listLiveOAuthAccountKeys, reconcileOAuthReauthState } from "../oauth/store";
 import { reconcileGuardianBackoff } from "../oauth/token-guardian";
 import { sweepExpiredApiKeyCooldowns } from "../providers/key-failover";
@@ -41,6 +45,7 @@ import { sweepAbandonedResponseStateTemps, sweepExpiredResponseStates, sweepOrph
 import { sweepExpiredAntigravityReplay } from "../adapters/google-antigravity-replay";
 import { reconcileProviderAccountQuotaRows } from "../providers/quota";
 import { reconcileRouterWarningMemos } from "../router";
+import { configureSharedSpendLedger, spendPolicyFromConfig } from "./spend-reservation-ledger";
 import type { OcxConfig } from "../types";
 import {
   type GenerationContext,
@@ -58,19 +63,27 @@ export function setLiveStateStoreConfig(config: OcxConfig): void {
 
 export function reconcileLiveStateStores() {
   if (!liveServerConfig) return { storesVisited: 0, rowsRemoved: 0 };
+  // Only adopted live providers own canonical pools; detached disk snapshots may
+  // contain providers the routing instance deliberately has not activated yet.
+  configureSharedSpendLedger(spendPolicyFromConfig(liveServerConfig.spend,
+    liveServerConfig.spendPoolAliases, Object.keys(liveServerConfig.providers)));
   return reconcileStateGeneration(buildGenerationContext());
 }
 
 export function buildGenerationContext(): GenerationContext {
   if (!liveServerConfig) throw new Error("live server config is not installed");
   const providerNames = new Set(Object.keys(liveServerConfig.providers));
+  const oauthAccountKeys = new Set(listLiveOAuthAccountKeys(providerNames));
+  if (configuredAnthropicInstance(liveServerConfig, "anthropic2") !== "anthropic2") {
+    for (const key of oauthAccountKeys) if (key.startsWith("anthropic2\0")) oauthAccountKeys.delete(key);
+  }
   return {
     generation: 0,
     providerNames,
     comboIds: new Set(Object.keys(liveServerConfig.combos ?? {})),
     comboTargets: listLiveComboTargetKeys(liveServerConfig),
     codexAccountIds: listLiveCodexAccountIds(liveServerConfig),
-    oauthAccountKeys: listLiveOAuthAccountKeys(providerNames),
+    oauthAccountKeys,
     configRoots: listLiveConfigOwnershipRoots(getConfigDir()),
   };
 }
@@ -84,7 +97,11 @@ export const STATE_STORE_REGISTRATIONS = [
     sweepExpired: sweepExpiredComboTargetCooldowns,
     reconcileGeneration: reconcileComboTargetCooldowns,
   },
-  { name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
+  { name: "anthropic-routing-health", sweepExpired: sweepAllAnthropicRoutingHealth,
+    reconcileGeneration: context => reconcileAnthropicRoutingState(context, liveServerConfig ?? undefined) },
+  { name: "anthropic-family-quota", reconcileGeneration: reconcileAllAnthropicFamilyQuota },
+  { name: "anthropic-rate-pauses", sweepExpired: sweepExpiredAllAnthropicRatePauses, reconcileGeneration: reconcileAllAnthropicRatePauses },
+  { name: "anthropic-cooldown-generations", reconcileGeneration: reconcileAllAnthropicCooldownGenerations },
   { name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
   {
     name: "codex-quota-401-recovery",

package/src/lib/synced-state-location.ts

@@ -1,4 +1,4 @@
-import { lstatSync, realpathSync } from "node:fs";
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 // POSIX path operations on purpose: every path this module classifies is a macOS path. The
 // host's own path module would build backslash or drive-letter paths on Windows and make the
@@ -15,7 +15,11 @@ const { join, resolve } = posix;
  * synced folder turns ordinary requests into intermittent 502s (#6314). This only answers
  * "is it likely synced"; the guard itself stays strict.
  */
-export type SyncedStateLocation = "icloud-drive" | "file-provider" | "icloud-desktop-documents";
+export type SyncedStateLocation =
+  | "icloud-drive"
+  | "file-provider"
+  | "icloud-desktop-documents"
+  | "google-drive-desktop-documents";
 
 export interface SyncedStateLocationProbe {
   readonly platform?: NodeJS.Platform;
@@ -24,23 +28,34 @@ export interface SyncedStateLocationProbe {
   readonly realpath?: (path: string) => string;
   /** Whether a directory entry exists at the path, without following it. */
   readonly entryExists?: (path: string) => boolean;
+  /** Entry names in a directory. An unreadable directory is empty, not an error. */
+  readonly listEntries?: (dir: string) => readonly string[];
 }
 
 const defaultEntryExists = (path: string): boolean => {
   try { lstatSync(path); return true; } catch { return false; }
 };
 
+const defaultListEntries = (dir: string): readonly string[] => {
+  try { return readdirSync(dir); } catch { return []; }
+};
+
 /**
  * Advisory only. Apple publishes no API a CLI can ask, so this reads the observed layout:
  * iCloud Drive lives under ~/Library/Mobile Documents, File Provider clients (OneDrive, Dropbox,
  * Google Drive) under ~/Library/CloudStorage, and with "Desktop & Documents Folders" turned on
- * iCloud Drive holds a Desktop/Documents entry of its own. A false positive costs one warning
- * line; nothing is refused on the strength of it.
+ * iCloud Drive holds a Desktop/Documents entry of its own. Google Drive for desktop can also
+ * sync the native Desktop and Documents folders without moving them under CloudStorage (#6314).
+ * The cheap signals for that are a DriveFS directory or a `GoogleDrive-*` CloudStorage folder.
+ * They do not read which folders the app was told to sync, so Drive being installed can warn
+ * even when Documents is not selected. A false positive costs one warning line; nothing is
+ * refused on the strength of it.
  */
 export function syncedStateLocation(dir: string, probe: SyncedStateLocationProbe = {}): SyncedStateLocation | undefined {
   if ((probe.platform ?? process.platform) !== "darwin") return undefined;
   const realpath = probe.realpath ?? ((path: string) => realpathSync.native(path));
   const entryExists = probe.entryExists ?? defaultEntryExists;
+  const listEntries = probe.listEntries ?? defaultListEntries;
   const canonical = (path: string): string => {
     try { return realpath(path); } catch { return resolve(path); }
   };
@@ -56,17 +71,42 @@ export function syncedStateLocation(dir: string, probe: SyncedStateLocationProbe
   if (within(mobileDocuments)) return "icloud-drive";
   if (within(join(home, "Library", "CloudStorage"))) return "file-provider";
   for (const folder of ["Desktop", "Documents"]) {
-    if (within(join(home, folder)) && entryExists(join(mobileDocuments, "com~apple~CloudDocs", folder))) {
-      return "icloud-desktop-documents";
+    if (!within(join(home, folder))) continue;
+    if (entryExists(join(mobileDocuments, "com~apple~CloudDocs", folder))) return "icloud-desktop-documents";
+    if (googleDriveAppearsToSyncDesktopDocuments(home, entryExists, listEntries)) {
+      return "google-drive-desktop-documents";
     }
   }
   return undefined;
 }
 
+/**
+ * Presence only. Drive for desktop keeps its config under DriveFS and, on current macOS,
+ * a `GoogleDrive-*` directory in CloudStorage. Either one means the app is in use. Missing
+ * or unreadable markers are "not detected", never a startup failure.
+ */
+function googleDriveAppearsToSyncDesktopDocuments(
+  home: string,
+  entryExists: (path: string) => boolean,
+  listEntries: (dir: string) => readonly string[],
+): boolean {
+  const driveFs = join(home, "Library", "Application Support", "Google", "DriveFS");
+  try {
+    if (entryExists(driveFs)) return true;
+  } catch { /* unreadable marker */ }
+  try {
+    return listEntries(join(home, "Library", "CloudStorage"))
+      .some((name) => name.toLowerCase().startsWith("googledrive-"));
+  } catch {
+    return false;
+  }
+}
+
 const LOCATION_LABEL: Record<SyncedStateLocation, string> = {
   "icloud-drive": "inside iCloud Drive",
   "file-provider": "inside a cloud-storage (File Provider) folder",
   "icloud-desktop-documents": "in Desktop or Documents, which iCloud Drive appears to sync",
+  "google-drive-desktop-documents": "in Desktop or Documents, which Google Drive appears to sync",
 };
 
 /** The startup warning. Names the location kind, never the path. */

package/src/lib/test-home-guard.ts

@@ -20,7 +20,7 @@
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
@@ -31,6 +31,8 @@ const GUARD_ENV = "OCX_TEST_HOME_GUARD";
  * loads, so the true home is only knowable from this hand-off.
  */
 const REAL_HOME_ENV = "OCX_REAL_HOME";
+/** Set by `scripts/test.ts` to the developer's own Claude config directory before it sandboxes one. */
+const REAL_CLAUDE_CONFIG_DIR_ENV = "OCX_REAL_CLAUDE_CONFIG_DIR";
 
 /**
  * Resolve symlinks so two spellings of one location compare equal — macOS hands out
@@ -62,6 +64,25 @@ function canonicalize(path: string): string {
 const REAL_HOME = process.env[REAL_HOME_ENV]?.trim() || homedir();
 const PROTECTED_HOME = canonicalize(join(REAL_HOME, ".opencodex"));
 const PROTECTED_CODEX_HOME = canonicalize(join(REAL_HOME, ".codex"));
+/**
+ * The developer's Claude config directory: the default `<real home>/.claude`, plus their own
+ * `CLAUDE_CONFIG_DIR` when they set one. `scripts/test.ts` hands the original over as
+ * `OCX_REAL_CLAUDE_CONFIG_DIR` because its child already starts with a sandboxed
+ * `CLAUDE_CONFIG_DIR`; a bare run imports this module before the preload rewrites the
+ * environment, so `CLAUDE_CONFIG_DIR` still holds the developer's value here.
+ *
+ * Claude agent sync prunes generated `agents/ocx-*.md`, and a bare `bun test` once did that
+ * to a live directory: Bun's `os.homedir()` ignores a HOME rewritten after startup (#6775).
+ */
+const REAL_CLAUDE_CONFIG_DIRS = [...new Set([
+  join(REAL_HOME, ".claude"),
+  process.env[REAL_CLAUDE_CONFIG_DIR_ENV]?.trim() || process.env.CLAUDE_CONFIG_DIR?.trim() || join(REAL_HOME, ".claude"),
+])];
+const PROTECTED_CLAUDE_TREES = REAL_CLAUDE_CONFIG_DIRS.map(path => ({
+  path: canonicalize(path),
+  lexical: resolve(path),
+  label: "the real Claude config directory",
+}));
 /**
  * `~/Library/LaunchAgents` needs its own entry because HOME isolation does not reach it:
  * `os.homedir()` reads the password database, not `$HOME`, so a macOS test that rewrites
@@ -83,6 +104,11 @@ export function protectedCodexHomeForTests(): string {
   return PROTECTED_CODEX_HOME;
 }
 
+/** The Claude config directories this process protects. Exported for the guard's own tests. */
+export function protectedClaudeConfigDirsForTests(): readonly string[] {
+  return PROTECTED_CLAUDE_TREES.map(tree => tree.path);
+}
+
 export function isTestHomeGuardArmed(): boolean {
   return process.env[GUARD_ENV] === "1";
 }
@@ -155,6 +181,54 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
   );
 }
 
+/**
+ * Throw when an armed test process is about to write or prune inside the real Claude config
+ * directory. Unlike the OpenCodex and Codex homes this refuses descendants too, and callers pass
+ * every directory they are about to touch (the config root AND its `agents`/`cache` child), so a
+ * sandbox child that is a link into the real directory is judged by where it resolves.
+ *
+ * The protected roots are resolved at check time rather than at import, so a custom directory
+ * created after this module loaded still compares by its current identity. On macOS and Windows,
+ * whose default filesystems ignore case, paths compare case-insensitively: `.CLAUDE` is the same
+ * directory there. Comparing too broadly only refuses more, which is the safe direction here.
+ *
+ * Call FIRST, outside any best-effort catch, so a refusal is visible and nothing is touched.
+ */
+export function assertNotRealClaudeConfigUnderTest(...paths: string[]): void {
+  if (!isTestHomeGuardArmed()) return;
+  const roots = currentClaudeConfigRoots();
+  for (const path of paths) {
+    for (const candidate of [canonicalize(path), resolve(path)]) {
+      for (const root of roots) {
+        if (!isSameOrInsideIgnoringPlatformCase(root, candidate)) continue;
+        throw new Error(
+          `refusing to write the real Claude config directory (${root}) from a test process. `
+          + "Set CLAUDE_CONFIG_DIR to a temp directory, or pass an explicit config directory "
+          + "(for a server, startServer's managementApi.claudeAgentConfigDir).",
+        );
+      }
+    }
+  }
+}
+
+function currentClaudeConfigRoots(): string[] {
+  return REAL_CLAUDE_CONFIG_DIRS.flatMap(path => [canonicalize(path), resolve(path)]);
+}
+
+function foldPlatformCase(path: string): string {
+  return process.platform === "darwin" || process.platform === "win32" ? path.toLowerCase() : path;
+}
+
+function isSameOrInsideIgnoringPlatformCase(root: string, candidate: string): boolean {
+  const parent = foldPlatformCase(root);
+  const child = foldPlatformCase(candidate);
+  if (parent === child) return true;
+  const rel = relative(parent, child);
+  // Only a leading ".." COMPONENT leaves the root, split on this platform's separator: a child
+  // named "..fixture", or "..\\fixture" on POSIX where a backslash is a filename character, is inside.
+  return rel !== "" && !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+
 /**
  * The trees a removal must never reach, and the reason each one is named.
  *
@@ -172,6 +246,7 @@ const PROTECTED_TREES: ReadonlyArray<{ path: string; lexical: string; label: str
     lexical: resolve(join(REAL_HOME, "Library", "LaunchAgents")),
     label: "the real LaunchAgents directory",
   },
+  ...PROTECTED_CLAUDE_TREES,
 ];
 const PROTECTED_REAL_HOME = canonicalize(REAL_HOME);
 const LEXICAL_REAL_HOME = resolve(REAL_HOME);
@@ -258,6 +333,17 @@ export function protectedRemovalReason(target: string): string | null {
         if (isInside(candidate, protectedPath)) return `an ancestor of ${tree.label} (${protectedPath})`;
       }
     }
+    // The Claude directory is judged like its writer guard: roots resolved now, case folded
+    // where the filesystem folds it, so an alias created after import is still refused.
+    for (const root of currentClaudeConfigRoots()) {
+      if (isSameOrInsideIgnoringPlatformCase(root, candidate)) {
+        // Same narrow lift as the trees above: content of the running checkout when that
+        // checkout itself lives inside the directory. Never the root itself.
+        if (foldPlatformCase(root) !== foldPlatformCase(candidate) && isOwnCheckoutContent(root, candidate)) continue;
+        return `the real Claude config directory or a path inside it (${root})`;
+      }
+      if (isSameOrInsideIgnoringPlatformCase(candidate, root)) return `an ancestor of the real Claude config directory (${root})`;
+    }
   }
   return null;
 }

package/src/lib/translator-budget.ts

@@ -191,6 +191,7 @@ class Budget implements TranslatorBudget {
   }
 
   openCall(id: string): void {
+    if (this.disposed) return;
     if (!this.calls.has(id)) {
       this.calls.set(id, { logicalBytes: 0, physicalBytes: 0 });
       aggregateActiveCalls += 1;
@@ -210,6 +211,7 @@ class Budget implements TranslatorBudget {
     bytes: number,
     scope: { kind: TranslatorBufferKind; callId?: string },
   ): TranslatorTransientReservation {
+    if (this.disposed) return { commitRetained() {}, release() {} };
     const admitted = normalizeBytes(bytes);
     if (scope.callId && admitted > this.maxCallArgumentBytes) {
       this.reject("tool_args", this.maxCallArgumentBytes);
@@ -222,6 +224,7 @@ class Budget implements TranslatorBudget {
     return {
       commitRetained: () => {
         if (state !== "reserved") return;
+        if (this.disposed) { state = "released"; return; }
         state = "committed";
         if (!scope.callId) return;
         const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
@@ -234,6 +237,7 @@ class Budget implements TranslatorBudget {
       release: () => {
         if (state !== "reserved") return;
         state = "released";
+        if (this.disposed) return;
         this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
         this.hardChargedBytes = Math.max(0, this.hardChargedBytes - admitted);
         this.changed();
@@ -242,6 +246,7 @@ class Budget implements TranslatorBudget {
   }
 
   chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    if (this.disposed) return;
     const admitted = normalizeBytes(delta);
     if (scope.callId) {
       const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
@@ -279,6 +284,7 @@ class Budget implements TranslatorBudget {
   }
 
   private observe(bytes: number): () => void {
+    if (this.disposed) return () => {};
     const observed = normalizeBytes(bytes);
     this.observedBytes += observed;
     this.changed();
@@ -369,7 +375,7 @@ export function resetTranslatorAggregateForTests(): void {
   aggregateOverflows = 0;
 }
 
-export function finalizeTranslatorBudgetResponse(response: Response, budget: TranslatorBudget): Response {
+export function finalizeTranslatorBudgetResponse(response: Response, budget: TranslatorBudget, signal?: AbortSignal): Response {
   if (!response.body) {
     budget.dispose();
     return response;
@@ -379,9 +385,12 @@ export function finalizeTranslatorBudgetResponse(response: Response, budget: Tra
   const finalize = () => {
     if (finalized) return;
     finalized = true;
+    signal?.removeEventListener("abort", finalize);
     budget.dispose();
   };
-  return new Response(new ReadableStream<Uint8Array>({
+  // The transport owns cancellation and terminal precedence. Abort releases only
+  // accounting here, including when no consumer ever pulls or cancels this body.
+  const body = new ReadableStream<Uint8Array>({
     async pull(controller) {
       try {
         const result = await reader.read();
@@ -395,7 +404,11 @@ export function finalizeTranslatorBudgetResponse(response: Response, budget: Tra
       }
     },
     async cancel(reason) {
-      try { await reader.cancel(reason); } finally { finalize(); }
+      finalize();
+      await reader.cancel(reason);
     },
-  }), { status: response.status, statusText: response.statusText, headers: response.headers });
+  });
+  if (signal?.aborted) finalize();
+  else signal?.addEventListener("abort", finalize, { once: true });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
 }

package/src/lib/upstream-retry.ts

@@ -508,7 +508,11 @@ export interface ResetRetryOptions {
    * `rebuildAndRefetch` recovery kind whose provider has no transient policy -- was not merely
    * uncounted but UNCOUNTABLE: the callback existed on a type those call sites never reach.
    */
-  onSendsConsumed?: (sends: number) => void;
+  onSendsConsumed?: ((sends: number) => void) & {
+    beforeSend?: () => boolean;
+    close?: () => void;
+    execute?: <T>(run: () => Promise<T>) => Promise<T>;
+  };
   /**
    * Spend one operator-granted replacement for a pre-header reset this helper would otherwise
    * refuse. Absent means no operator policy, which is the fail-closed answer.
@@ -629,6 +633,7 @@ export async function fetchWithResetRetry(
   // more send on every recovery leg, which is most of what made a bounded per-layer retry
   // compose into an unbounded per-request count.
   if (attempts === 0) throw new SendBudgetExhaustedError(opts.label);
+  try {
   let lastError: unknown;
   let sawReset = false;
   // True once this leg has spent the request's operator allowance. From that point the leg
@@ -640,9 +645,13 @@ export async function fetchWithResetRetry(
     // Reported before the await, one physical send at a time: a send that rejects has still
     // been made, and this helper leaves through four exits (return, reset give-up, non-reset
     // rethrow, abort), so a per-send report is the only shape that is correct on all of them.
-    opts.onSendsConsumed?.(1);
+    if (opts.onSendsConsumed?.beforeSend && !opts.onSendsConsumed.beforeSend()) throw new SendBudgetExhaustedError(opts.label);
+    if (!opts.onSendsConsumed?.beforeSend) opts.onSendsConsumed?.(1);
     try {
-      const response = await doFetch(attempt === 0 ? firstRecovery : "connection-reset");
+      let response: Response;
+      try { const run = () => doFetch(attempt === 0 ? firstRecovery : "connection-reset");
+        response = await (opts.onSendsConsumed?.execute ? opts.onSendsConsumed.execute(run) : run()); }
+      finally { if (opts.onSendsConsumed?.beforeSend) opts.onSendsConsumed(1); }
       return spentOperatorReplacement ? settleOperatorReplacement(response) : response;
     } catch (err) {
       if (opts.abortSignal?.aborted) throw err;
@@ -686,6 +695,7 @@ export async function fetchWithResetRetry(
     }
   }
   throw lastError ?? new Error("upstream fetch failed");
+  } finally { opts.onSendsConsumed?.close?.(); }
 }
 
 /**
@@ -717,8 +727,10 @@ export async function fetchWithTransientRetry(
   const countedFetch: ReplayableFetch = (recovery) => {
     // Incremented BEFORE the await so a rejected send still consumes budget; counting only
     // successes would let a reset storm loop without bound.
+    if (opts.onSendsConsumed?.beforeSend && !opts.onSendsConsumed.beforeSend()) throw new SendBudgetExhaustedError(opts.label);
     sent += 1;
-    return doFetch(recovery);
+    const run = () => doFetch(recovery);
+    return opts.onSendsConsumed?.execute ? opts.onSendsConsumed.execute(run) : run();
   };
   // No floor. A spent budget hands the inner helper 0, which refuses rather than buying one
   // more send -- the loop condition alone was never enough, because every later recovery leg
@@ -789,7 +801,7 @@ export async function fetchWithTransientRetry(
   // Budget exhausted: the last response is returned with its body intact.
   return res;
   } finally {
-    opts.onSendsConsumed?.(sent);
+    try { opts.onSendsConsumed?.(sent); } finally { opts.onSendsConsumed?.close?.(); }
   }
 }
 

package/src/lib/windows-atomic-replace.ts

@@ -37,6 +37,9 @@ export type ReplacePublisher =
   | "storage-cleanup"
   | "tray";
 
+/** Called immediately before every rename attempt, including each Windows retry. */
+export interface RenameValidationHooks { validateBeforeRename?: (destination: string) => void }
+
 /** The Windows error codes this module treats as a momentary hold. */
 export type ReplaceRetryCode = "EBUSY" | "EPERM" | "EACCES";
 
@@ -97,7 +100,7 @@ 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(
+export function transientWindowsReplaceCode(
   platform: NodeJS.Platform,
   error: unknown,
 ): ReplaceRetryCode | null {
@@ -106,6 +109,32 @@ function transientWindowsReplaceCode(
   return code === "EBUSY" || code === "EPERM" || code === "EACCES" ? code : null;
 }
 
+/** One filesystem operation plus its retry observers, carried as members (not free callbacks). */
+export interface WindowsFileOperationStep<T> {
+  run: () => T;
+  onRetry?: (code: ReplaceRetryCode, exhausted: boolean) => void;
+  beforeAttempt?: () => void;
+}
+
+/** Bounded sharing-violation retries for one filesystem operation, never a transaction. */
+export function retryWindowsFileOperation<T>(
+  step: WindowsFileOperationStep<T>,
+  io: Pick<AtomicRenameIO, "platform" | "sleep"> = { platform: process.platform, sleep: Bun.sleepSync },
+): T {
+  for (let attempt = 0; ; attempt += 1) {
+    step.beforeAttempt?.();
+    try { return step.run(); }
+    catch (error) {
+      const code = transientWindowsReplaceCode(io.platform, error);
+      if (!code) throw error;
+      const exhausted = attempt >= MAX_RETRIES;
+      step.onRetry?.(code, exhausted);
+      if (exhausted) throw error;
+      io.sleep(25 * (attempt + 1));
+    }
+  }
+}
+
 export function renameAtomicFile(
   source: string,
   destination: string,
@@ -115,30 +144,23 @@ export function renameAtomicFile(
     sleep: Bun.sleepSync,
   },
   publisher: ReplacePublisher = "config",
+  hooks: RenameValidationHooks = {},
 ): 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));
-    }
-  }
+  retryWindowsFileOperation({
+    run: () => io.rename(source, destination),
+    onRetry: (code, exhausted) => bump(publisher, code, exhausted ? "exhausted" : "retried"),
+    beforeAttempt: () => hooks.validateBeforeRename?.(destination),
+  }, io);
 }
 
 export async function renameAtomicFileAsync(
   source: string,
   destination: string,
   publisher: ReplacePublisher = "config",
+  hooks: RenameValidationHooks = {},
 ): Promise<void> {
   for (let attempt = 0; ; attempt += 1) {
+    hooks.validateBeforeRename?.(destination);
     try {
       renameSync(source, destination);
       return;

package/src/lib/windows-elevation.ts

@@ -203,6 +203,12 @@ export function resolveTrustedWindowsPowerShellExe(): string {
   return assertTrustedSystemExecutable(candidate, "PowerShell");
 }
 
+/** Absolute System32\\reg.exe path; PATH, SystemRoot and WINDIR cannot select it. */
+export function resolveTrustedWindowsRegExe(): string {
+  const candidate = join(resolveTrustedWindowsSystemDirectory(), "reg.exe");
+  return assertTrustedSystemExecutable(candidate, "reg.exe");
+}
+
 /** Absolute path to System32\\schtasks.exe from a trusted system directory. */
 export function resolveTrustedWindowsSchtasksExe(): string {
   if (elevationExeOverridesForTests?.schtasks) {