@bitkyc08/opencodex 2.36.0-preview.20260829 → 2.36.0

package/src/codex/runtime.ts

@@ -435,6 +435,18 @@ export type CodexRuntimeProcessCachePeek =
 let resolveCacheEpoch = 0;
 let resolveCache: ResolveCacheMemo | null = null;
 
+/**
+ * Bumped whenever persisted runtime state is replaced or process authority is cleared.
+ *
+ * Consumers that memoize anything derived from `codex-runtime.json` — entitlement's client
+ * version, for one — read this instead of a timestamp, so a runtime switch invalidates them at
+ * the moment of the write rather than after a delay window. Exposed because the alternative was
+ * a time-based guess that could answer under the previous version after the file had changed.
+ */
+export function codexRuntimeStateEpoch(): number {
+  return resolveCacheEpoch;
+}
+
 function publishResolveCache(key: string, at: number, value: ResolveCodexRuntimeResult): void {
   const epoch = ++resolveCacheEpoch;
   resolveCache = {

package/src/codex/subagent-model-fallback.ts

@@ -39,6 +39,7 @@ import { routeModel, type RouteResult } from "../router";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
 import { codexAccountNamespaceForModel } from "./account-namespace-match";
 import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 import {
   getUpstreamHostHealth,
   normalizeUpstreamHostCircuitThreshold,
@@ -276,31 +277,68 @@ export function isSubagentModelUnavailable(
     poolAccountPreview,
     candidateAccountUsabilityOptions?.modelEligibleAccountIds,
   );
-  if (isModelHealthBlocked(model, config, resolvedAccountId, now)) return true;
-  if (!isPoolCodexRoute(route)) return false;
-
-  // Pool candidates need a usable account. Derive requirement from the resolved
-  // route (canonical openai defaults to pool even when codexAccountMode is omitted).
-  if (!resolvedAccountId) return true;
-  if (isCodexAccountPaused(config, resolvedAccountId)) return true;
-  if (!isCodexAccountUsable(config, resolvedAccountId, candidateAccountUsabilityOptions)) return true;
-  if (route.codexAccountId !== undefined) {
-    // An account-qualified route is pinned and cannot consume Pool's recovery-probe
-    // escape hatch. Honor both account-wide and model-scoped cooldowns so fallback
-    // advances instead of selecting a candidate that exact auth will reject.
-    const quotaScope = codexQuotaScopeForModel(route.modelId);
-    if (getCodexQuotaHealthSnapshot(resolvedAccountId, quotaScope, now) !== null) return true;
-  } else {
-    const quotaScope = codexQuotaScopeForModel(route.modelId);
-    const cooldown = getCodexQuotaHealthSnapshot(resolvedAccountId, quotaScope, now);
-    if (cooldown !== null) {
-      const probeAvailable = cooldown.quotaScope
-        ? canAcquireCodexQuotaScopeProbeLease(resolvedAccountId, cooldown.quotaScope, now)
-        : canAcquireCodexQuotaProbeLease(resolvedAccountId, now);
-      if (!probeAvailable) return true;
+  const accountUnavailable = (
+    candidateAccountId: string | null,
+    usabilityOptions: CodexAccountUsabilityOptions | undefined,
+    includeQuotaExhaustion: boolean,
+  ): boolean => {
+    if (isModelHealthBlocked(model, config, candidateAccountId, now)) return true;
+    if (!isPoolCodexRoute(route)) return false;
+
+    // Pool candidates need a usable account. Derive requirement from the resolved
+    // route (canonical openai defaults to pool even when codexAccountMode is omitted).
+    if (!candidateAccountId) return true;
+    if (isCodexAccountPaused(config, candidateAccountId)) return true;
+    if (!isCodexAccountUsable(config, candidateAccountId, usabilityOptions)) return true;
+    if (route.codexAccountId !== undefined) {
+      // An account-qualified route is pinned and cannot consume Pool's recovery-probe
+      // escape hatch. Honor both account-wide and model-scoped cooldowns so fallback
+      // advances instead of selecting a candidate that exact auth will reject.
+      const quotaScope = codexQuotaScopeForModel(route.modelId);
+      if (getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now) !== null) return true;
+    } else {
+      const quotaScope = codexQuotaScopeForModel(route.modelId);
+      const cooldown = getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now);
+      if (cooldown !== null) {
+        const probeAvailable = cooldown.quotaScope
+          ? canAcquireCodexQuotaScopeProbeLease(candidateAccountId, cooldown.quotaScope, now)
+          : canAcquireCodexQuotaProbeLease(candidateAccountId, now);
+        if (!probeAvailable) return true;
+      }
     }
-  }
-  return isNativeModelQuotaExhausted(model, config, resolvedAccountId, now);
+    if (
+      !includeQuotaExhaustion
+      || (
+        candidateAccountId === MAIN_CODEX_ACCOUNT_ID
+        && usabilityOptions?.nativeMainSelectionOnly === true
+      )
+    ) return false;
+    return isNativeModelQuotaExhausted(model, config, candidateAccountId, now);
+  };
+
+  // Prefer a genuinely usable entitled pool account. Preview can deliberately return
+  // the configured active account even when no selectable candidate exists, so a
+  // null/main-only check is not enough to detect the temporary-drain case.
+  if (!accountUnavailable(resolvedAccountId, candidateAccountUsabilityOptions, true)) return false;
+
+  // During a temporary native-main drain, entitlement discovery excludes main to
+  // preserve the credential fence. If no non-main candidate can serve an unqualified
+  // gated model, retain main only as a read-free sentinel: final auth owns the atomic
+  // claim and returns maintenance instead of letting a routed fallback bypass it.
+  const preserveDrainingMainCandidate = route.codexAccountId === undefined
+    && candidateAccountUsabilityOptions?.nativeMainSelectionOnly === true
+    && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId);
+  if (!preserveDrainingMainCandidate) return true;
+  const drainingMainUsabilityOptions: CodexAccountUsabilityOptions = {
+    ...candidateAccountUsabilityOptions,
+    modelEligibleAccountIds: new Set([
+      ...(modelEligibleAccountIds ?? []),
+      MAIN_CODEX_ACCOUNT_ID,
+    ]),
+  };
+  // Quota scoring main would lazily read the native credential/plan. Cached health,
+  // pause, reauth, and cooldown state are safe; defer physical scoring to final auth.
+  return accountUnavailable(MAIN_CODEX_ACCOUNT_ID, drainingMainUsabilityOptions, false);
 }
 
 export function selectAvailableSubagentModel(

package/src/codex/user-identity.ts

@@ -36,27 +36,29 @@ const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
  * Hard budget for the Windows identity-lookup PowerShell child. These lookups
  * run at startup and on config writes; a hung child must fail the lookup
  * (recoverable — the caller refuses) rather than wedge the proxy indefinitely.
- */
-const WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS = 8_000;
-
-/**
- * The same budget, widened for a contended CI runner.
  *
- * 8s is a generous ceiling for `powershell.exe -Command` on a real desktop and is not one
- * on a GitHub Windows runner executing a quarter of this suite: the composed-acceptance
- * cases fail there with "Windows effective-account lookup timed out" while the child is
- * still starting. That is runner contention, not a hung lookup, and the budget exists to
- * bound the latter.
+ * 30s, and the same on a desktop as in CI. The split below used to give desktops
+ * 8s, on the theory that only a shared runner is contended enough to need more.
+ * A zh-CN Windows 10 host measured 3.2s for the SID expression and 4.6s for the
+ * `Add-Type` LocalAppData expression — per spawn, with a bare
+ * `powershell.exe -NoProfile -Command exit` costing ~3s where a typical desktop
+ * pays ~150ms — so ordinary spawn jitter breached 8s intermittently and `ocx sync`
+ * failed with "Windows effective-account lookup timed out" (#2914).
+ *
+ * That is the same contention the CI branch was widened for, which is what makes
+ * the split vestigial rather than merely conservative: it encoded an assumption
+ * about WHERE contention happens, and the assumption was wrong. Antivirus
+ * real-time scanning, a loaded Task Scheduler, and cold PowerShell startup do not
+ * care whether the machine is a runner.
  *
- * Gated on `CI` alone. A user's machine keeps the 8s ceiling exactly as before, so the
- * recoverable-refusal contract this budget protects is unchanged where it matters.
+ * The contract this budget protects is unchanged: a genuinely hung child still
+ * fails the lookup and the caller still refuses rather than writing. Only the
+ * ceiling moved, and it moved for the case where the lookup would have succeeded.
  */
-const WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_CI_MS = 30_000;
+const WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS = 30_000;
 
 function windowsIdentityLookupTimeoutMs(): number {
-  return process.env.CI === "true"
-    ? WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_CI_MS
-    : WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS;
+  return WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS;
 }
 
 /**
@@ -435,6 +437,18 @@ function resolveWindowsRuntimeRoot(identity: Extract<UserIdentity, { platform: "
   }
 }
 
+/**
+ * Resolve the canonical, effective-user runtime root shared by Codex lock domains.
+ *
+ * This is a directory, not a final lock or database path. Callers create their
+ * own named child so independent exclusion domains cannot self-contend.
+ */
+export function resolveEffectiveUserRuntimeRoot(identity: UserIdentity): string {
+  return identity.platform === "posix"
+    ? resolvePosixRuntimeRoot(identity.uid)
+    : resolveWindowsRuntimeRoot(identity);
+}
+
 /**
  * Windows path identity is case-insensitive; everywhere else it is exact.
  *
@@ -461,9 +475,7 @@ export const resolveCodexCoordinatorDatabasePath: ResolveCodexCoordinatorDatabas
   if (!isAbsolute(canonicalCodexHome)) {
     refuse("The canonical CODEX_HOME must be an absolute path.");
   }
-  const root = identity.platform === "posix"
-    ? resolvePosixRuntimeRoot(identity.uid)
-    : resolveWindowsRuntimeRoot(identity);
+  const root = resolveEffectiveUserRuntimeRoot(identity);
   const locks = join(root, "native-write-locks");
   if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
   else {
@@ -495,9 +507,7 @@ export const resolveCodexCatalogSerializationDatabasePath:
     if (!isAbsolute(canonicalCodexHome)) {
       refuse("The canonical CODEX_HOME must be an absolute path.");
     }
-    const root = identity.platform === "posix"
-      ? resolvePosixRuntimeRoot(identity.uid)
-      : resolveWindowsRuntimeRoot(identity);
+    const root = resolveEffectiveUserRuntimeRoot(identity);
     const locks = join(root, "catalog-write-locks");
     if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
     else {
@@ -534,9 +544,7 @@ export const resolveCodexHistorySerializationDatabasePath:
     if (!isAbsolute(canonicalStateDbPath)) {
       refuse("The canonical Codex state database must be an absolute path.");
     }
-    const root = identity.platform === "posix"
-      ? resolvePosixRuntimeRoot(identity.uid)
-      : resolveWindowsRuntimeRoot(identity);
+    const root = resolveEffectiveUserRuntimeRoot(identity);
     const locks = join(root, "history-write-locks");
     if (identity.platform === "posix") ensurePrivatePosixDirectory(locks, identity.uid);
     else {

package/src/combos/index.ts

@@ -43,3 +43,4 @@ export {
   concreteComboRequestBody,
   resetComboEffortWarningStateForTests,
 } from "./request";
+export { earliestQuotaResetAt, quotaResetRemainingMs } from "./reset-window";

package/src/combos/reset-window.ts

@@ -0,0 +1,46 @@
+import type { ProviderQuota } from "../providers/quota";
+
+function collectResetCandidates(quota: ProviderQuota): number[] {
+  const candidates: number[] = [];
+  const push = (value: number | undefined): void => {
+    if (value !== undefined && Number.isFinite(value)) candidates.push(value);
+  };
+  push(quota.fiveHourResetAt);
+  push(quota.weeklyResetAt);
+  push(quota.monthlyResetAt);
+  if (quota.customWindows) {
+    for (const w of quota.customWindows) {
+      push(w.resetAt);
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Earliest future reset timestamp from a cached provider quota snapshot,
+ * or null when no fresh quota data exists or all resets have elapsed.
+ */
+export function earliestQuotaResetAt(
+  quota: ProviderQuota | null,
+  now: number,
+): number | null {
+  if (!quota) return null;
+  const future = collectResetCandidates(quota).filter(ts => ts > now);
+  if (future.length > 0) return Math.min(...future);
+  return null;
+}
+
+/**
+ * Milliseconds until the soonest known quota-window reset.
+ * Returns Infinity when no quota data exists, quota is stale, or all known
+ * reset timestamps have elapsed. An elapsed reset is stale evidence — it
+ * does not prove the next request has fresh capacity.
+ */
+export function quotaResetRemainingMs(
+  quota: ProviderQuota | null,
+  now: number,
+): number {
+  const nearest = earliestQuotaResetAt(quota, now);
+  if (nearest === null) return Number.POSITIVE_INFINITY;
+  return nearest - now;
+}

package/src/combos/resolve.ts

@@ -1,5 +1,7 @@
 import type { OcxComboTarget, OcxConfig } from "../types";
+import { getCachedProviderQuota } from "../providers/quota-routing-cache";
 import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import { quotaResetRemainingMs } from "./reset-window";
 import { getCombo, resolveComboId, targetKey } from "./types";
 import type { NormalizedComboConfig } from "./types";
 import {
@@ -19,6 +21,7 @@ interface SelectionState {
   activeKey?: string;
   successes: number;
   currentWeights: Map<string, number>;
+  successfulUses: Map<string, number>;
 }
 
 const selectionState = new Map<string, SelectionState>();
@@ -82,6 +85,36 @@ function smoothWeightedIndex(
   return best;
 }
 
+/**
+ * Select the eligible target whose earliest known quota reset is nearest.
+ *
+ * Only reads the last successfully cached provider-quota snapshot; it never
+ * triggers an upstream quota probe. When no target has fresh reset data,
+ * every remaining value is Infinity and configured order becomes the
+ * fallback. Targets with elapsed or stale reset timestamps are treated as
+ * unknown (Infinity).
+ */
+function resetWindowIndex(
+  targets: Required<OcxComboTarget>[],
+  eligible: (target: Required<OcxComboTarget>) => boolean,
+  now = Date.now(),
+): number {
+  let selected = -1;
+  let smallestRemaining = Number.POSITIVE_INFINITY;
+  for (let index = 0; index < targets.length; index++) {
+    const target = targets[index]!;
+    if (!eligible(target)) continue;
+    const remaining = quotaResetRemainingMs(getCachedProviderQuota(target.provider, now), now);
+    // Strict comparison deliberately retains configured order for ties,
+    // including the no-snapshot fallback where every value is Infinity.
+    if (selected < 0 || remaining < smallestRemaining) {
+      selected = index;
+      smallestRemaining = remaining;
+    }
+  }
+  return selected;
+}
+
 export function pickComboTarget(
   config: OcxConfig,
   comboId: string,
@@ -103,7 +136,7 @@ export function pickComboTarget(
   if (combo.strategy === "round-robin") {
     let state = selectionState.get(comboId);
     if (!state) {
-      state = { successes: 0, currentWeights: new Map() };
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
       selectionState.set(comboId, state);
     }
     if (state.activeKey) {
@@ -120,6 +153,41 @@ export function pickComboTarget(
         state.successes = 0;
       }
     }
+  } else if (combo.strategy === "random") {
+    // Weighted random selection happens independently for every request.
+    const eligibleTargets = combo.targets
+      .map((target, index) => ({ target, index }))
+      .filter(({ target }) => eligible(target));
+    if (eligibleTargets.length > 0) {
+      const totalWeight = eligibleTargets.reduce((sum, entry) => sum + entry.target.weight, 0);
+      let random = Math.random() * totalWeight;
+      for (const entry of eligibleTargets) {
+        random -= entry.target.weight;
+        if (random <= 0) {
+          targetIndex = entry.index;
+          break;
+        }
+      }
+      if (targetIndex < 0) targetIndex = eligibleTargets[eligibleTargets.length - 1]!.index;
+    }
+  } else if (combo.strategy === "least-used") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
+      selectionState.set(comboId, state);
+    }
+    let fewestUses = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < combo.targets.length; index++) {
+      const target = combo.targets[index]!;
+      if (!eligible(target)) continue;
+      const uses = state.successfulUses.get(targetKey(target)) ?? 0;
+      if (targetIndex < 0 || uses < fewestUses) {
+        targetIndex = index;
+        fewestUses = uses;
+      }
+    }
+  } else if (combo.strategy === "reset-window") {
+    targetIndex = resetWindowIndex(combo.targets, eligible);
   } else {
     targetIndex = combo.targets.findIndex(eligible);
   }
@@ -141,9 +209,18 @@ export function noteComboSuccess(
   target: Required<OcxComboTarget>,
   writerGeneration = captureConfigGeneration(),
 ): void {
-  if (combo.strategy !== "round-robin") return;
   const key = targetKey(target);
   if (!mayCommitComboState(comboId, key, writerGeneration)) return;
+  if (combo.strategy === "least-used") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
+      selectionState.set(comboId, state);
+    }
+    state.successfulUses.set(key, (state.successfulUses.get(key) ?? 0) + 1);
+    return;
+  }
+  if (combo.strategy !== "round-robin") return;
   const state = selectionState.get(comboId);
   if (!state || state.activeKey !== key) return;
   state.successes += 1;
@@ -206,6 +283,11 @@ export function reconcileComboRotationState(context: GenerationContext): number
       state.currentWeights.delete(key);
       removed += 1;
     }
+    for (const key of state.successfulUses.keys()) {
+      if (context.comboTargets.has(comboTargetOwnerKey(comboId, key))) continue;
+      state.successfulUses.delete(key);
+      removed += 1;
+    }
   }
   liveComboTargets = new Set(context.comboTargets);
   lastReconciledGeneration = context.generation;

package/src/combos/types.ts

@@ -215,8 +215,11 @@ export function comboConfigIssues(
   }
   if (body.strategy !== undefined
     && body.strategy !== "failover"
-    && body.strategy !== "round-robin") {
-    issues.push({ path: ["strategy"], message: 'strategy must be "failover" or "round-robin"' });
+    && body.strategy !== "round-robin"
+    && body.strategy !== "random"
+    && body.strategy !== "least-used"
+    && body.strategy !== "reset-window") {
+    issues.push({ path: ["strategy"], message: 'strategy must be "failover", "round-robin", "random", "least-used", or "reset-window"' });
   }
   if (body.stickyLimit !== undefined
     && (typeof body.stickyLimit !== "number" || !Number.isInteger(body.stickyLimit)

package/src/config/atomic-write.ts

@@ -1,6 +1,11 @@
 import {
   chmodSync,
+  closeSync,
+  constants,
+  fchmodSync,
+  fstatSync,
   lstatSync,
+  openSync,
   realpathSync,
   truncateSync,
   unlinkSync,
@@ -42,6 +47,12 @@ export interface AtomicWriteIO {
   unlink: (path: string) => void;
 }
 
+export interface AtomicWriteHooks {
+  afterTempWrite?: (tempPath: string, targetPath: string) => void;
+  beforeRename?: (tempPath: string, targetPath: string) => void;
+  validateBeforeRename?: (targetPath: string) => void;
+}
+
 export class AtomicWriteResidualTempError extends Error {
   constructor(readonly tempPath: string, readonly hardened = true, options?: ErrorOptions) {
     super(`Atomic config write left a ${hardened ? "hardened " : ""}zero-byte temporary file`, options);
@@ -92,52 +103,120 @@ function assertResolvedTargetAllowed(path: string, target: string): void {
   assertNotRealHomeUnderTest(dirname(target));
 }
 
-export function atomicWriteFile(path: string, content: string, io: AtomicWriteIO = {
-  write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
-  harden: target => {
-    try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
-    if (process.platform === "win32") hardenSecretPath(target, { required: true, timeoutMemoKey: path });
-  },
-  rename: renameAtomicFile,
-  truncate: target => truncateSync(target, 0),
-  unlink: unlinkSync,
-}): void {
+function assertPrivateTempDescriptor(path: string, descriptor: number): void {
+  const opened = fstatSync(descriptor);
+  const linked = lstatSync(path);
+  if (!opened.isFile() || !linked.isFile()
+    || opened.dev !== linked.dev || opened.ino !== linked.ino) {
+    throw new Error("atomic temporary file identity changed before write");
+  }
+  if (process.platform !== "win32" && (opened.mode & 0o777) !== 0o600) {
+    throw new Error("atomic temporary file permissions are not owner-only");
+  }
+}
+
+function writePrivateTempFile(
+  path: string,
+  content: string,
+  timeoutMemoKey: string,
+  onCreated: () => void,
+): void {
+  const descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+  onCreated();
+  try {
+    if (process.platform === "win32") {
+      hardenSecretPath(path, { required: true, timeoutMemoKey });
+    } else {
+      fchmodSync(descriptor, 0o600);
+    }
+    assertPrivateTempDescriptor(path, descriptor);
+    writeFileSync(descriptor, content, { encoding: "utf-8" });
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+async function writePrivateTempFileAsync(
+  path: string,
+  content: string,
+  timeoutMemoKey: string,
+  onCreated: () => void,
+): Promise<void> {
+  const descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+  onCreated();
+  try {
+    if (process.platform === "win32") {
+      await hardenSecretPathAsync(path, { required: true, timeoutMemoKey });
+    } else {
+      fchmodSync(descriptor, 0o600);
+    }
+    assertPrivateTempDescriptor(path, descriptor);
+    writeFileSync(descriptor, content, { encoding: "utf-8" });
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function atomicWriteFile(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
   recordOwnedConfigPath(getConfigDir(), path);
   const target = resolveWriteTarget(path);
   assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let hardened = false;
+  let ownsTemp = false;
+  const effective: AtomicWriteIO = io ?? {
+    write: (tempPath, value) => writePrivateTempFile(tempPath, value, path, () => { ownsTemp = true; }),
+    harden: tempPath => {
+      try { chmodSync(tempPath, 0o600); } catch { /* platform may ignore chmod */ }
+      if (process.platform === "win32") {
+        hardenSecretPath(tempPath, { required: true, timeoutMemoKey: path });
+      }
+    },
+    rename: renameAtomicFile,
+    truncate: tempPath => truncateSync(tempPath, 0),
+    unlink: unlinkSync,
+  };
   try {
-    io.write(tmp, content);
-    io.harden(tmp);
+    if (io) ownsTemp = true;
+    effective.write(tmp, content);
+    hooks.afterTempWrite?.(tmp, target);
+    effective.harden(tmp);
     hardened = true;
-    io.rename(tmp, target);
+    hooks.beforeRename?.(tmp, target);
+    hooks.validateBeforeRename?.(target);
+    effective.rename(tmp, target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
+    if (!ownsTemp) throw cause;
     let scrubbed = false;
     try {
-      io.truncate(tmp);
+      effective.truncate(tmp);
       scrubbed = true;
     } catch (error) {
       if (isMissingPathError(error)) scrubbed = true;
       else {
-        try { io.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
+        try { effective.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
       }
     }
     let removed = false;
     try {
-      io.unlink(tmp);
+      effective.unlink(tmp);
       removed = true;
     } catch (error) {
       if (isMissingPathError(error)) removed = true;
       else {
-        try { io.unlink(tmp); removed = true; }
+        try { effective.unlink(tmp); removed = true; }
         catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
       }
     }
     if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
     if (!removed && !hardened) {
-      try { io.harden(tmp); hardened = true; } catch { /* reported below */ }
+      try { effective.harden(tmp); hardened = true; } catch { /* reported below */ }
     }
     if (removed) forgetEphemeralSecretPath(tmp);
     if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
@@ -163,12 +242,13 @@ export async function atomicWriteFileAsync(
   io?: AtomicWriteAsyncIO,
   testSeam?: AtomicWriteAsyncTestSeam,
 ): Promise<void> {
+  let ownsTemp = false;
   const effective: AtomicWriteAsyncIO = io ?? {
-    write: (target, value) => writeFileSync(target, value, { encoding: "utf-8", mode: 0o600 }),
-    harden: async target => {
-      try { chmodSync(target, 0o600); } catch { /* platform may ignore chmod */ }
+    write: (tempPath, value) => writePrivateTempFileAsync(tempPath, value, path, () => { ownsTemp = true; }),
+    harden: async tempPath => {
+      try { chmodSync(tempPath, 0o600); } catch { /* platform may ignore chmod */ }
       if (process.platform === "win32") {
-        await hardenSecretPathAsync(target, { required: true, timeoutMemoKey: path });
+        await hardenSecretPathAsync(tempPath, { required: true, timeoutMemoKey: path });
       }
     },
     rename: renameAtomicFileAsync,
@@ -180,6 +260,7 @@ export async function atomicWriteFileAsync(
   const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let hardened = false;
   try {
+    if (io) ownsTemp = true;
     await effective.write(tmp, content);
     await testSeam?.afterTempWrite?.(tmp);
     await effective.harden(tmp);
@@ -187,6 +268,7 @@ export async function atomicWriteFileAsync(
     await effective.rename(tmp, target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
+    if (!ownsTemp) throw cause;
     let scrubbed = false;
     try {
       await effective.truncate(tmp);

package/src/config/provider-validation.ts

@@ -1,4 +1,5 @@
 import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+import { redactSecretString } from "../lib/redact";
 import { modelRecordValue } from "../reasoning-effort";
 import {
   isWirePinnedModel,
@@ -123,6 +124,16 @@ export function booleanRecordConfigError(value: unknown, field: string): string
   return null;
 }
 
+/** Validate the management DTO boundary for the opt-in empty-tool-output annotation. */
+export function providerEmptyToolOutputConfigError(name: string, provider: unknown): string | null {
+  const raw = provider as Record<string, unknown> | null | undefined;
+  const value = raw === null || raw === undefined ? undefined : raw.annotateEmptyToolOutputs;
+  if (value !== undefined && typeof value !== "boolean") {
+    return `provider ${JSON.stringify(redactSecretString(name))} annotateEmptyToolOutputs must be a boolean`;
+  }
+  return null;
+}
+
 export function reasoningSummaryDeliveryRecordConfigError(
   value: unknown,
   supportsReasoningSummaries: unknown,