@bitkyc08/opencodex 2.56.0 → 2.58.0

package/src/images/loop.ts

@@ -615,7 +615,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
                   signal: headerDeadline.signal,
                 }, retryRecovery));
               },
-              { abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
+              { replaySafe: true, abortSignal: headerDeadline.signal, label: "image-bridge-loop" },
             );
           }
         } finally {

package/src/lib/bounded-subprocess.ts

@@ -9,28 +9,80 @@ export interface BoundedSubprocessExit {
   timedOut: boolean;
 }
 
-/** Kill at the deadline and abandon immediately; late exit/rejection remains observed. */
+export type SubprocessDeadlineScheduler = (
+  callback: () => void,
+  milliseconds: number,
+) => () => void;
+
+const scheduleDeadline: SubprocessDeadlineScheduler = (callback, milliseconds) => {
+  const timer = setTimeout(callback, milliseconds);
+  return () => clearTimeout(timer);
+};
+
+/**
+ * Compatibility allowance used by the ACL runner's outer watchdog.
+ *
+ * `kill()` only REQUESTS termination. It returns before the kernel has torn the process down, and
+ * every handle that process holds stays held until it does. On Windows that is not a detail: file
+ * locking is mandatory, so a directory an abandoned `icacls.exe` still has open cannot be removed
+ * by anyone, and the removal fails with EPERM rather than waiting.
+ */
+export const SUBPROCESS_KILL_GRACE_MS = 2_000;
+
+/**
+ * Wait for a child until the deadline. At the deadline, kill it AND wait for it to actually die.
+ *
+ * This used to kill, `unref`, and resolve in the same tick, which made every caller's "I waited
+ * for my child" guarantee false precisely when it mattered. The ACL runner now waits here until
+ * actual exit; if its separate caller-facing belt fires first, that layer registers the target so
+ * removal can wait for the reap without making ordinary startup or shutdown unbounded.
+ *
+ * That cost three failed fixes. #4789 blamed the removal retry budget and asked for more than
+ * 2.5s; #4796 gave it a 15s exponential schedule; a later change awaited the hardening flight from
+ * the test hook. Windows shard 1/6 failed identically through all three, because none of them
+ * addressed a live process holding the handle -- run 35108652486 burned the full 15s budget and
+ * still threw `EPERM ... rm ocx-management-auth-fDchUb`, with two
+ * `ACL hardening timed out (ETIMEDOUT) - transient icacls stall` lines logged beside it.
+ *
+ * The old grace still abandoned a live child after two seconds. That recreated the same false
+ * ownership contract on a slower clock: the ACL flight settled, cleanup removed the directory,
+ * and Windows returned EPERM because the child still held it. A handle-bearing caller therefore
+ * has no second deadline after kill. The child's actual exit is the only release signal.
+ *
+ * Pass `0` to opt out for a child that holds no path anyone will remove. The numeric form is kept
+ * for compatibility with the existing callers; any positive value means that reaping is required.
+ * The injected scheduler is a test seam so deadline and exit ordering can be proved without sleep.
+ */
 export function waitForSubprocessExit(
   proc: KillableSubprocess,
   timeoutMs: number,
+  reapAfterKill: number = SUBPROCESS_KILL_GRACE_MS,
+  schedule: SubprocessDeadlineScheduler = scheduleDeadline,
 ): Promise<BoundedSubprocessExit> {
   return new Promise(resolve => {
     let settled = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
+    let deadlineFired = false;
+    let cancelDeadline: (() => void) | undefined;
     const finish = (result: BoundedSubprocessExit): void => {
       if (settled) return;
       settled = true;
-      if (timer !== undefined) clearTimeout(timer);
+      cancelDeadline?.();
       resolve(result);
     };
-    timer = setTimeout(() => {
+    const reaped = proc.exited.then(
+      exitCode => finish(deadlineFired
+        ? { exitCode: null, timedOut: true }
+        : { exitCode, timedOut: false }),
+      () => finish({ exitCode: null, timedOut: deadlineFired }),
+    );
+    cancelDeadline = schedule(() => {
+      deadlineFired = true;
       try { proc.kill(); } catch { /* already exited */ }
-      try { proc.unref?.(); } catch { /* abandonment is still authoritative */ }
-      finish({ exitCode: null, timedOut: true });
+      if (reapAfterKill <= 0) {
+        try { proc.unref?.(); } catch { /* abandonment is still authoritative */ }
+        finish({ exitCode: null, timedOut: true });
+        return;
+      }
     }, Math.max(1, timeoutMs));
-    void proc.exited.then(
-      exitCode => finish({ exitCode, timedOut: false }),
-      () => finish({ exitCode: null, timedOut: false }),
-    );
   });
 }

package/src/lib/errors.ts

@@ -7,6 +7,15 @@ export interface OcxErrorPayload {
 export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
   "Encrypted function output content could not be decrypted or decoded.";
 
+/**
+ * The error identity for a send this proxy declined to make (#4708).
+ *
+ * Declared here rather than only on the error class because the classifier is what decides
+ * whether the identity survives serialization, and every dispatch path has to name the same
+ * string for a client to be able to tell this apart from a provider rate limit.
+ */
+export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
+
 /** Canonical human-readable message paths used by Responses upstream failures. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
@@ -253,6 +262,14 @@ export function classifyError(status: number, type: string, message: string): Oc
   ) {
     return { message, type: "insufficient_quota", code: "insufficient_quota" };
   }
+  // A refusal this proxy made itself, kept apart from the provider rate limits below. The HTTP
+  // semantics are identical -- 429, do not send this again now -- but the code is the only thing
+  // that tells an operator reading a log whether the provider throttled the request or whether
+  // this process declined to send it. Folding it into the generic rate-limit code sent them to
+  // the provider's dashboard to explain a decision that was never made there.
+  if (type === SEND_BUDGET_EXHAUSTED_CODE) {
+    return { message, type: "rate_limit_error", code: SEND_BUDGET_EXHAUSTED_CODE };
+  }
   if (
     status === 429 ||
     text.includes("rate limit") ||

package/src/lib/request-execution-budget.ts

@@ -56,6 +56,7 @@ export type BudgetDenial =
   | "final-recovery-spent"
   | "alternate-target-exhausted"
   | "target-transition-exhausted"
+  | "spend-exhausted"
   | "not-replay-safe";
 
 export interface DispatchIntent {
@@ -94,12 +95,45 @@ export interface SingleUseDispatchPermit {
    * once an external send reporter already settled it.
    */
   release(): void;
+  /**
+   * Take over an externally counted booking, because the layer holding this permit is the one
+   * that physically sends.
+   *
+   * `countedExternally` promises that a retry helper will name this send through
+   * `onSendsConsumed`. An adapter that owns its own dispatch ladder -- Kiro's reset loop,
+   * Cursor's transport loop -- reserves per physical send instead, so no reporter ever arrives
+   * and the pending booking would sit there until it silently swallowed an unrelated later
+   * report. Confirming through this method settles the permit AND closes the booking, so the
+   * send stays charged exactly once (#4709). Returns false once the permit is settled, which is
+   * what keeps one permit from admitting two sends.
+   */
+  assumeCharge(): boolean;
 }
 
 export type DispatchDecision =
   | { allowed: true; permit: SingleUseDispatchPermit }
   | { allowed: false; reason: BudgetDenial };
 
+/**
+ * Notified when this request's physical-send count moves.
+ *
+ * `spent` is the only number here that counts SENDS rather than intentions: a reservation
+ * increments it, a refund decrements it, and an externally reported send settles against a
+ * booking that was already counted. Anything that books one entry per increment therefore
+ * books exactly one entry per physical send -- which is what lets the durable spend ledger
+ * have a production caller without every dispatch site in the tree remembering to call it.
+ *
+ * `charge` may refuse, and a refusal denies the dispatch. That is deliberate: the ledger is
+ * the only bound here that survives a restart, so a limit it enforces has to be able to stop a
+ * send rather than merely describe one.
+ */
+export interface RequestSendObserver {
+  /** Book one physical send. False refuses the dispatch before the budget charges it. */
+  charge(): boolean;
+  /** Give back a booking whose send never happened. */
+  refund(): void;
+}
+
 /**
  * Carried on HandleResponsesOptions so a combo child, a rebuild and an alternate-account leg
  * all decrement the same holder. `used` is the existing #4605 counter and still counts every
@@ -134,33 +168,57 @@ const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
 
 let logicalRequestSeq = 0;
 
-export function createRequestExecutionBudget(
-  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
-  logicalRequestId?: string,
+/**
+ * One request's physical-send ledger, held apart from the budget object so a derived policy
+ * scope can share the exact same one.
+ *
+ * `spent` and `pendingExternalSends` belong together: a pending booking is a send that is
+ * already counted in `spent` and awaiting its reporter, so a scope that shared one without the
+ * other would either charge that send twice or never charge it at all.
+ *
+ * The durable-spend observer belongs here for the same reason. It books one entry per physical
+ * send by watching this counter move, so a derived scope that spent the counter without
+ * carrying the observer would move it without booking, and a combo child's sends would go
+ * missing from the ledger (#4707).
+ */
+interface SharedSendLedger {
+  spent: number;
+  pendingExternalSends: number;
+  readonly observer?: RequestSendObserver;
+}
+
+const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>();
+
+function createRequestExecutionBudgetWithLedger(
+  policy: RequestExecutionBudgetPolicy,
+  logicalRequestId: string | undefined,
+  counter: SharedSendLedger,
 ): RequestExecutionBudget {
-  let spent = 0;
-  // Reservations whose physical send is reported by a retry helper rather than by the permit.
-  // They are already charged; the reporter's first send settles one instead of charging again.
-  let pendingExternalSends = 0;
+  const observer = counter.observer;
   let reserveSpent = false;
   let alternateTargetSends = 0;
   let targetTransitions = 0;
   let lastTargetKey: string | undefined;
 
   const budget: RequestExecutionBudget = {
-    get used(): number { return spent; },
+    get used(): number { return counter.spent; },
     set used(next: number) {
       // The retry helpers report their real send count by assigning through this field. A
       // reservation taken with `countedExternally` has already booked one of those sends, so
       // the report settles the pending booking first and only the surplus is charged.
-      const delta = next - spent;
+      const delta = next - counter.spent;
       if (delta <= 0) {
-        spent = Math.max(0, next);
+        counter.spent = Math.max(0, next);
         return;
       }
-      const settled = Math.min(delta, pendingExternalSends);
-      pendingExternalSends -= settled;
-      spent += delta - settled;
+      const settled = Math.min(delta, counter.pendingExternalSends);
+      counter.pendingExternalSends -= settled;
+      const charged = delta - settled;
+      counter.spent += charged;
+      // These sends have already left. The ledger records them even past a ceiling it would
+      // have refused, because refusing after the fact only hides spend that was really
+      // incurred -- the refusal has to happen at the reservation below, or not at all.
+      for (let index = 0; index < charged; index += 1) observer?.charge();
     },
     logicalRequestId: logicalRequestId ?? `lr-${Date.now().toString(36)}-${(logicalRequestSeq += 1).toString(36)}`,
     policyVersion: REQUEST_BUDGET_POLICY_VERSION,
@@ -171,11 +229,11 @@ export function createRequestExecutionBudget(
     get lastTargetKey() { return lastTargetKey; },
     remainingBaseSends(cap: number): number {
       const capped = Number.isFinite(cap) ? Math.trunc(cap) : 0;
-      return Math.max(0, Math.min(capped, policy.baseSendAllowance - spent));
+      return Math.max(0, Math.min(capped, policy.baseSendAllowance - counter.spent));
     },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
-      if (spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
+      if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
 
       const changesTarget = lastTargetKey !== undefined && lastTargetKey !== intent.targetKey;
       const isAlternateTarget = changesTarget || intent.sendClass === "account-failover"
@@ -190,7 +248,7 @@ export function createRequestExecutionBudget(
       // The base allowance is spent first. Only once it is gone does a recovery class reach
       // for the single shared reserve -- an account move and a validated rebuild cannot each
       // take one.
-      const drawsReserve = policy.baseSendAllowance - spent <= 0;
+      const drawsReserve = policy.baseSendAllowance - counter.spent <= 0;
       if (drawsReserve) {
         if (!RESERVE_FUNDED_CLASSES.has(intent.sendClass)) {
           return { allowed: false, reason: "base-allowance-exhausted" };
@@ -200,13 +258,18 @@ export function createRequestExecutionBudget(
         }
       }
 
+      // Consulted last, because it is the only bound here that WRITES. A ledger entry booked
+      // for a dispatch a cheaper check above would have refused is spend this request never
+      // makes, and it would hold those tokens against the scope until retention expired.
+      if (observer && !observer.charge()) return { allowed: false, reason: "spend-exhausted" };
+
       // THE RESERVATION IS THE CHARGE. Deciding here and charging in `use()` left a window in
       // which two legs read the same remainder, both received a permit, and both dispatched:
       // one remaining send admitted two physical sends, which is the per-request multiplication
       // this budget exists to stop. Everything is booked now; `release()` is the way back.
       const previousTargetKey = lastTargetKey;
-      spent += 1;
-      if (intent.countedExternally === true) pendingExternalSends += 1;
+      counter.spent += 1;
+      if (intent.countedExternally === true) counter.pendingExternalSends += 1;
       if (drawsReserve) reserveSpent = true;
       if (isAlternateTarget) alternateTargetSends += 1;
       if (changesTarget) targetTransitions += 1;
@@ -222,16 +285,28 @@ export function createRequestExecutionBudget(
             settled = "used";
             return true;
           },
+          assumeCharge(): boolean {
+            if (settled !== "open") return false;
+            settled = "used";
+            // The booking this reservation made for an external reporter is now owned by the
+            // caller. Leaving it pending is not harmless: the next `used` report of this request
+            // would settle against it and one real send would go uncharged.
+            if (intent.countedExternally === true && counter.pendingExternalSends > 0) {
+              counter.pendingExternalSends -= 1;
+            }
+            return true;
+          },
           release(): void {
             if (settled !== "open") return;
             settled = "released";
             // An externally counted reservation the reporter already settled paid for a send
             // that physically happened. Refunding it would hand the request a free send back.
             if (intent.countedExternally === true) {
-              if (pendingExternalSends === 0) return;
-              pendingExternalSends -= 1;
+              if (counter.pendingExternalSends === 0) return;
+              counter.pendingExternalSends -= 1;
             }
-            spent -= 1;
+            counter.spent -= 1;
+            observer?.refund();
             if (drawsReserve) reserveSpent = false;
             if (isAlternateTarget) alternateTargetSends -= 1;
             if (changesTarget) targetTransitions -= 1;
@@ -241,9 +316,60 @@ export function createRequestExecutionBudget(
       };
     },
   };
+  sharedSendLedgers.set(budget, counter);
   return budget;
 }
 
+export function createRequestExecutionBudget(
+  policy: RequestExecutionBudgetPolicy = CODEX_TEXT_GUARDED_BUDGET_POLICY,
+  logicalRequestId?: string,
+  observer?: RequestSendObserver,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
+    spent: 0,
+    pendingExternalSends: 0,
+    ...(observer ? { observer } : {}),
+  });
+}
+
+/**
+ * A budget that applies its own policy and keeps its own recovery ledgers while spending the
+ * parent's exact physical-send ledger.
+ *
+ * Aliasing the public `used` property was not enough, and that is the whole defect. The factory
+ * reads its own private counter back in `remainingBaseSends`, in the total check, and in the
+ * reserve test, so an aliased scope answered every admission question from a counter that only
+ * ever saw its own reservations. A combo's per-target holdback is computed from
+ * `maxTotalModelSends` and is therefore unenforceable unless the scope actually observes what
+ * the request has already spent.
+ */
+export function deriveRequestExecutionBudget(
+  parent: RequestExecutionBudget,
+  policy: RequestExecutionBudgetPolicy,
+): RequestExecutionBudget {
+  return createRequestExecutionBudgetWithLedger(policy, parent.logicalRequestId, ledgerFor(parent));
+}
+
+/**
+ * A budget that did not come from this factory still honors the public `used` contract, so
+ * bridge onto it rather than failing the request. `isRequestExecutionBudget` is a shape test,
+ * so a stub can reach here; turning that into a thrown error would convert a routing request
+ * into a 500 to report a condition production never produces. Only a factory-backed parent can
+ * share pending external bookings and a durable-spend observer, which are private by
+ * construction; a bridged scope keeps the parent's spend accurate and books nothing of its own.
+ */
+function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
+  const existing = sharedSendLedgers.get(parent);
+  if (existing) return existing;
+  let pendingExternalSends = 0;
+  return {
+    get spent(): number { return parent.used; },
+    set spent(next: number) { parent.used = next; },
+    get pendingExternalSends(): number { return pendingExternalSends; },
+    set pendingExternalSends(next: number) { pendingExternalSends = next; },
+  };
+}
+
 export function isRequestExecutionBudget(
   value: TransientSendBudget | undefined,
 ): value is RequestExecutionBudget {

package/src/lib/spend-reservation-ledger.ts

@@ -669,6 +669,24 @@ export function createSpendReservationLedger(options: {
         case "checkpoint": applyCheckpoint(record); break;
       }
     }
+    // A reservation that survived replay has no owner left. The process that made it is gone,
+    // so nothing in this one can ever settle it, and leaving it live means the send stays
+    // pending forever against a scope that can never resolve it. Deleting the entry is not the
+    // alternative either: that would hand the same send id a second reservation.
+    //
+    // Both live states resolve to UNRESOLVED, including an undispatched one. The tempting
+    // distinction -- open never reached the wire, so give its tokens back -- assumes the
+    // journal is complete up to the crash, and the torn-tail handling above says it is not: a
+    // send can dispatch and die before its dispatch record lands. Abandoning that reservation
+    // returns tokens for a send that may have been billed, and worse, it RESETS a ceiling that
+    // had already fired. An exhausted scope staying exhausted across a restart is the whole
+    // reason this store is on disk.
+    const reconciledAt = now();
+    for (const [send, reservation] of reservations) {
+      if (!isLive(reservation.status)) continue;
+      applyResolve(send, "lost", 0, reconciledAt);
+      append({ v: 1, kind: "lost", send, at: reconciledAt });
+    }
   }
 
   /**

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

@@ -21,7 +21,7 @@ import {
 } from "../combos/failover";
 import { reconcileComboWarningMemos } from "../combos/request";
 import { reconcileComboRotationState } from "../combos/resolve";
-import { reconcileComboRecall } from "../server/responses/combo-session-recall";
+import { reconcileComboRecall, sweepExpiredComboRecall } from "../server/responses/combo-session-recall";
 import { listLiveComboTargetKeys } from "../combos/types";
 import {
   listLiveConfigOwnershipRoots,
@@ -112,7 +112,11 @@ export const STATE_STORE_REGISTRATIONS = [
   { name: "model-cache-history", reconcileGeneration: reconcileModelCacheGeneration },
   { name: "pool-rotation", reconcileGeneration: reconcilePoolRotationState },
   { name: "combo-rotation", reconcileGeneration: reconcileComboRotationState },
-  { name: "combo-session-recall", reconcileGeneration: reconcileComboRecall },
+  {
+    name: "combo-session-recall",
+    sweepExpired: sweepExpiredComboRecall,
+    reconcileGeneration: reconcileComboRecall,
+  },
   { name: "guardian-backoff", reconcileGeneration: reconcileGuardianBackoff },
   { name: "codex-reauth", reconcileGeneration: reconcileCodexReauthState },
   { name: "oauth-reauth", reconcileGeneration: reconcileOAuthReauthState },

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

@@ -20,7 +20,7 @@
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { realpathSync } from "node:fs";
 
 const GUARD_ENV = "OCX_TEST_HOME_GUARD";
@@ -152,3 +152,87 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
     + "Point CODEX_HOME at a temp directory for this test before writing native auth.json.",
   );
 }
+
+/**
+ * The trees a removal must never reach, and the reason each one is named.
+ *
+ * The writer guard above cannot help here. `rmSync` is plain `node:fs`: it calls no writer of
+ * ours, so no assertion of ours runs, and by the time anything could observe the damage the
+ * directory is already gone. On 2026-09-15 that is exactly what happened — a test resolved the
+ * process-global config directory and removed it, taking every OAuth login, the Codex account
+ * store, the service tokens and a 372MB usage ledger with it.
+ */
+const PROTECTED_TREES: ReadonlyArray<{ path: string; lexical: string; label: string }> = [
+  { path: PROTECTED_HOME, lexical: resolve(join(REAL_HOME, ".opencodex")), label: "the real OpenCodex home" },
+  { path: PROTECTED_CODEX_HOME, lexical: resolve(join(REAL_HOME, ".codex")), label: "the real Codex home" },
+  {
+    path: PROTECTED_LAUNCH_AGENTS,
+    lexical: resolve(join(REAL_HOME, "Library", "LaunchAgents")),
+    label: "the real LaunchAgents directory",
+  },
+];
+const PROTECTED_REAL_HOME = canonicalize(REAL_HOME);
+const LEXICAL_REAL_HOME = resolve(REAL_HOME);
+
+/** Canonical paths whose removal is refused. Exported so the guard's tests cannot drift off them. */
+export function protectedRemovalTreesForTests(): readonly string[] {
+  return [PROTECTED_REAL_HOME, ...PROTECTED_TREES.map(tree => tree.path)];
+}
+
+/** Whether `child` sits strictly below `parent`, both already canonicalized. */
+function isInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Why removing `target` is refused, or `null` when it is not a protected location.
+ *
+ * Three relations are refused, not one. Equality alone would still permit
+ * `rmSync(getConfigPath())` against a live `config.json`, and it would permit
+ * `rmSync(homedir())`, which takes the protected tree with it. So a target is refused when it
+ * IS a protected tree, when it sits INSIDE one, or when it is an ANCESTOR of one.
+ *
+ * Canonicalization is what makes a symlink useless as a bypass: a temp path that merely points
+ * at the real home resolves to the real home before any comparison happens.
+ */
+export function protectedRemovalReason(target: string): string | null {
+  // Both spellings are judged, not just the canonical one. Canonicalization is what defeats a
+  // symlink alias, but it also resolves the target away: if `~/.opencodex` is itself a link,
+  // the literal path a caller passed is the thing that gets unlinked, and only the lexical
+  // form still names it. Upstream Codex makes the same distinction in its writable-root
+  // handling, keeping logical and resolved forms side by side rather than collapsing to one.
+  for (const candidate of [canonicalize(target), resolve(target)]) {
+    if (candidate === PROTECTED_REAL_HOME || candidate === LEXICAL_REAL_HOME) {
+      return `the real home directory (${PROTECTED_REAL_HOME})`;
+    }
+    for (const tree of PROTECTED_TREES) {
+      for (const protectedPath of [tree.path, tree.lexical]) {
+        if (candidate === protectedPath) return `${tree.label} (${protectedPath})`;
+        if (isInside(protectedPath, candidate)) return `a path inside ${tree.label} (${protectedPath})`;
+        if (isInside(candidate, protectedPath)) return `an ancestor of ${tree.label} (${protectedPath})`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Throw before a removal that would reach a protected tree.
+ *
+ * Deliberately NOT gated on {@link isTestHomeGuardArmed}. Arming happens in `tests/preload.ts`,
+ * which Bun loads from the `bunfig.toml` it finds in the CURRENT WORKING DIRECTORY — so a run
+ * started outside the repository arms nothing, leaves OPENCODEX_HOME unset, and resolves the
+ * developer's real home. That unarmed run is precisely the one that caused the incident, so the
+ * refusal has to hold without it. Nothing in production calls this; the callers are test
+ * helpers, where the only cost of an unconditional check is a path comparison.
+ */
+export function assertRemovalOutsideProtectedTrees(target: string): void {
+  const reason = protectedRemovalReason(target);
+  if (reason === null) return;
+  throw new Error(
+    `refusing to remove ${reason} from a test process: "${target}" resolves there. `
+    + "Create the directory this test owns with createTempHome() from tests/helpers/temp-home "
+    + "and remove that handle instead (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+  );
+}