@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/history-lock.ts

@@ -0,0 +1,241 @@
+/**
+ * H — the cross-process history serialization primitive.
+ *
+ * Today a native apply or restore performs SQLite rows, the backup manifest and
+ * every rollout file on the caller thread, and the manifest and rollout writes
+ * sit OUTSIDE the provider's SQLite transaction
+ * (`src/codex/history-provider.ts:606-648,656-698`). A SQLite busy timeout
+ * therefore serializes one third of a state transition and explains one stall.
+ * H is held across the whole unit — DB, manifest and rollouts together — so an
+ * opposite-direction process cannot overtake through the unguarded files.
+ *
+ * Two ways H differs from K, both forced by review:
+ *
+ * `H -> N` is a real edge, not a violation. The Worker reads the coordinator row
+ * and writes its terminal state while holding H, and both take BEGIN IMMEDIATE
+ * on N. That is why H must be its own database: sharing N's would make the
+ * Worker contend with itself. `N -> H`, `K -> H` and `C -> H` are forbidden, and
+ * the resulting `H -> N -> K -> C` order was checked acyclic in review round 3.
+ *
+ * H is keyed by the canonical state database as well as the canonical home,
+ * because one CODEX_HOME can name a different `state_5.sqlite` and those are not
+ * the same exclusion (`src/codex/user-identity.ts`).
+ *
+ * The permit is a runtime registration, not a type. An opaque TypeScript brand
+ * proves a permit-bearing call path exists; it cannot prove the callback still
+ * holds the lock, and a permit leaked past its callback type-checks perfectly.
+ * So every history mutator asks this module at runtime whether the permit it was
+ * handed is still live for the state database it is about to write.
+ *
+ * Design record: devlog/_plan/260804_codex_write_substrate/005_contract.md §6.
+ */
+import { chmodSync, lstatSync, realpathSync } from "node:fs";
+
+import { Database } from "bun:sqlite";
+
+import {
+  CodexUserIdentityRefusal,
+  resolveCodexHistorySerializationDatabasePath,
+  resolveEffectiveUserIdentity,
+} from "./user-identity";
+
+/**
+ * Authorization to perform history mutations inside ONE H acquisition.
+ *
+ * Deliberately carries no usable field. Holding this object is necessary and
+ * never sufficient: `assertHistoryWritePermit` decides, by looking the object up
+ * in a registry only this module can write. A forged cast, a prototype copy or a
+ * symbol clone produces a value of this type that every writer refuses.
+ */
+export interface HistoryWritePermit {
+  readonly [historyWritePermitBrand]: true;
+}
+
+declare const historyWritePermitBrand: unique symbol;
+
+export type HistorySerializationOutcome<T> =
+  | { kind: "completed"; value: T }
+  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" };
+
+export class HistoryWritePermitRefusal extends Error {
+  readonly code = "CODEX_HISTORY_WRITE_PERMIT_REFUSED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "HistoryWritePermitRefusal";
+  }
+}
+
+interface PermitRegistration {
+  readonly canonicalStateDbPath: string;
+  readonly transactionId: string;
+  live: boolean;
+}
+
+/**
+ * Registrations are marked dead, never deleted.
+ *
+ * Deleting would make a leaked permit indistinguishable from a forged one, and
+ * those are different bugs: "used after its acquisition released" points at a
+ * caller that kept a permit past its callback, while "never minted here" points
+ * at a cast or a clone. Both are refused; only the diagnosis differs. The map is
+ * weak, so a dead entry costs nothing once the permit is unreachable.
+ */
+const activePermits = new WeakMap<object, PermitRegistration>();
+let acquisitionCounter = 0;
+
+function isBusy(error: unknown): boolean {
+  const code = error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : "";
+  const message = error instanceof Error ? error.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+/**
+ * Refuse unless this exact permit is live for this exact state database.
+ *
+ * Every history mutator calls this BEFORE touching the database, the manifest or
+ * a rollout file. The state database is named by the caller rather than derived,
+ * because a rollout path can point anywhere the manifest recorded.
+ */
+export function assertHistoryWritePermit(
+  permit: HistoryWritePermit,
+  canonicalStateDbPath: string,
+): void {
+  const registration = activePermits.get(permit as unknown as object);
+  if (!registration) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit was not minted by the serialization owner.",
+    );
+  }
+  if (!registration.live) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit belongs to a released acquisition.",
+    );
+  }
+  if (registration.canonicalStateDbPath !== canonicalStateDbPath) {
+    throw new HistoryWritePermitRefusal(
+      "The history write permit authorizes a different Codex state database.",
+    );
+  }
+}
+
+/**
+ * Acquire H for one canonical state database and run `work` while it is held.
+ *
+ * The callback may enter N — that is the `H -> N` edge the Worker needs to read
+ * the coordinator row and publish its terminal state. It must never re-enter H.
+ *
+ * `busy_timeout = 0` with `BEGIN IMMEDIATE` makes contention fail fast and
+ * typed. Blocking here would hold the acquisition across an unbounded wait,
+ * which is the stall this phase exists to remove.
+ */
+export function withHistoryWriteSerialization<T>(
+  canonicalCodexHome: string,
+  canonicalStateDbPath: string,
+  work: (permit: HistoryWritePermit) => T,
+): HistorySerializationOutcome<T> {
+  let databasePath: string;
+  try {
+    databasePath = resolveCodexHistorySerializationDatabasePath(
+      resolveEffectiveUserIdentity(),
+      canonicalCodexHome,
+      canonicalStateDbPath,
+    );
+  } catch (error) {
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    return { kind: "unavailable", reason: "database" };
+  }
+
+  let database: Database | undefined;
+  let transactionOpen = false;
+  let registration: PermitRegistration | undefined;
+  let permit: HistoryWritePermit | undefined;
+
+  try {
+    let databaseWasAbsent = false;
+    try {
+      const before = lstatSync(databasePath);
+      if (before.isSymbolicLink() || !before.isFile()) {
+        return { kind: "unavailable", reason: "unsafe-path" };
+      }
+      if (process.platform !== "win32") {
+        const uid = process.getuid?.();
+        if (uid === undefined || before.uid !== uid || (before.mode & 0o777) !== 0o600) {
+          return { kind: "unavailable", reason: "unsafe-path" };
+        }
+      }
+    } catch (cause) {
+      const code = cause && typeof cause === "object" && "code" in cause
+        ? String((cause as { code?: unknown }).code)
+        : "";
+      if (code !== "ENOENT") throw cause;
+      databaseWasAbsent = true;
+    }
+
+    database = new Database(databasePath, { create: true });
+    if (databaseWasAbsent) {
+      try { chmodSync(databasePath, 0o600); } catch { /* Windows applies ACLs in WP11. */ }
+    }
+    const opened = lstatSync(databasePath);
+    if (opened.isSymbolicLink() || !opened.isFile()
+      || realpathSync.native(databasePath) !== databasePath) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+
+    acquisitionCounter += 1;
+    registration = {
+      canonicalStateDbPath,
+      transactionId: `${process.pid}:${acquisitionCounter}`,
+      live: true,
+    };
+    // A bare object: nothing about it is guessable or reconstructable, because
+    // the authority lives in the registry entry rather than in the value.
+    permit = {} as HistoryWritePermit;
+    activePermits.set(permit as unknown as object, registration);
+
+    let value: T;
+    try {
+      value = work(permit);
+    } finally {
+      // Revoke BEFORE releasing the transaction, so a mutator racing the release
+      // can never find a live permit without a live lock. This runs on the
+      // throwing path too, which is what a `finally`-less version gets wrong.
+      registration.live = false;
+    }
+
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return { kind: "completed", value };
+  } catch (error) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
+      transactionOpen = false;
+    }
+    if (registration?.live) {
+      registration.live = false;
+    }
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    if (isBusy(error)) return { kind: "unavailable", reason: "busy" };
+    // A callback failure is the caller's error, not a lock outcome: H acquired
+    // fine. Reporting it as `unavailable` would tell the caller to retry
+    // something that fails identically.
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* acquisition already finished */ }
+  }
+}
+
+/** Test-only: prove a leaked permit is dead without reaching into the registry. */
+export function isHistoryWritePermitLive(permit: HistoryWritePermit): boolean {
+  return activePermits.get(permit as unknown as object)?.live === true;
+}

package/src/codex/history-migration-guardian.ts

@@ -1,4 +1,5 @@
 import { countPendingOpencodexHistory, migrateHistoryToOpenai } from "./history-provider";
+import { resolveCodexHistoryJobTarget, runCodexHistoryJob } from "./history-job";
 
 /**
  * Daemon-side retry for the one-time Design-B history migration.
@@ -23,7 +24,8 @@ export interface HistoryMigrationGuardianHandle {
 
 export interface HistoryMigrationGuardianDeps {
   countFn?: typeof countPendingOpencodexHistory;
-  migrateFn?: () => ReturnType<typeof migrateHistoryToOpenai>;
+  migrateFn?: () => ReturnType<typeof migrateHistoryToOpenai>
+    | Promise<ReturnType<typeof migrateHistoryToOpenai>>;
   log?: Pick<Console, "log">;
   tickMs?: number;
   maxTicks?: number;
@@ -42,7 +44,18 @@ function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
 
 export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps = {}): HistoryMigrationGuardianHandle {
   const countFn = deps.countFn ?? countPendingOpencodexHistory;
-  const migrateFn = deps.migrateFn ?? (() => migrateHistoryToOpenai(undefined, undefined, { attempts: 1 }));
+  // The default migration goes through the history job, so the guardian's timer
+  // thread never performs the transition itself. A background repair that races
+  // an apply or a restore is exactly what H exists to order.
+  const migrateFn = deps.migrateFn ?? (async () => {
+    const outcome = await runCodexHistoryJob({
+      ...resolveCodexHistoryJobTarget(),
+      operation: "migrate-openai",
+    });
+    return outcome.kind === "converged"
+      ? { rows: outcome.rows, files: outcome.files }
+      : { rows: 0, files: 0, failed: true as const };
+  });
   const log = deps.log ?? console;
   const tickMs = deps.tickMs ?? DEFAULT_TICK_MS;
   const maxTicks = deps.maxTicks ?? DEFAULT_MAX_TICKS;
@@ -56,7 +69,7 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
     pending = (deps.scheduleFn ?? defaultSchedule)(tick, tickMs);
   };
 
-  const tick = () => {
+  const tick = async () => {
     if (stopped) return;
     ticks++;
     try {
@@ -66,9 +79,9 @@ export function startHistoryMigrationGuardian(deps: HistoryMigrationGuardianDeps
         return;
       }
       // Locked probe or pending work: attempt one migration pass.
-      const result = migrateFn();
+      const result = await migrateFn();
       if (!result.failed) {
-        const moved = result.rows + (result.ejectedRows ?? 0);
+        const moved = result.rows + ((result as { ejectedRows?: number }).ejectedRows ?? 0);
         if (moved > 0) {
           log.log(`🩹 history-migration: ${moved} legacy opencodex thread(s) migrated back to openai.`);
         }

package/src/codex/history-provider.ts

@@ -14,7 +14,14 @@ import { atomicWriteFile, getConfigDir } from "../config";
 export const MAX_ROLLOUT_ZST_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
 
 const STATE_DB_PATH = join(CODEX_HOME, "state_5.sqlite");
-function historyBackupPathFor(stateDbPath: string): string {
+/**
+ * The manifest that shadows one state database.
+ *
+ * Exported because the history job must resolve it at CALL time for a Worker
+ * that does not inherit this module's load-time constants — and must resolve it
+ * the same way, since a manifest addressed differently is a different manifest.
+ */
+export function historyBackupPathFor(stateDbPath: string): string {
   const normalized = process.platform === "win32" ? resolve(stateDbPath).toLowerCase() : resolve(stateDbPath);
   const id = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
   return join(getConfigDir(), `codex-history-backup-${id}.json`);
@@ -157,7 +164,7 @@ function patchFirstLineProviderInPlace(path: string, expectedId: string, provide
   }
 }
 
-type CodexHistoryProvider = "openai" | "opencodex";
+export type CodexHistoryProvider = "openai" | "opencodex";
 
 export interface CodexHistorySyncResult {
   rows: number;

package/src/codex/history-transition.ts

@@ -0,0 +1,105 @@
+/**
+ * Resolve the transition a history job belongs to.
+ *
+ * `updateCodexHistoryTransition` had no production caller, so every completed or
+ * skipped job left the coordinator row permanently `pending` — a transition was
+ * published and never resolved. This is that caller.
+ *
+ * The classification is `020_history_isolation.md:564-572`, applied rather than
+ * reinvented. The two unions do not line up one-to-one, so each outcome is
+ * mapped by hand: a cast across them would compile on the words they share and
+ * lie about the rest.
+ */
+import type { CodexHistoryJobOutcome } from "./history-job";
+import type { CodexHistoryState, CodexTransitionVersion } from "./convergence-types";
+import { updateCodexHistoryTransition } from "./transition-state";
+
+/** The retry budget for a contended terminal CAS. Bounded; never unbounded. */
+const TERMINAL_RETRY_ATTEMPTS = 3;
+const TERMINAL_RETRY_DELAY_MS = 250;
+
+function sleep(ms: number): void {
+  // The caller path here is synchronous after the awaited job, so a spin is the
+  // honest tool — awaiting would be, and this is short.
+  const until = Date.now() + ms;
+  while (Date.now() < until) { /* bounded */ }
+}
+
+function classify(outcome: CodexHistoryJobOutcome, txId: string | null): CodexHistoryState {
+  switch (outcome.kind) {
+    case "converged":
+      return {
+        status: "converged",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        // Mutation counts, not probe counts. The durable counts come from the
+        // final probe, which this path does not run — null rather than a
+        // manufactured zero.
+        pendingRows: null,
+        backupEntries: null,
+      };
+    case "skipped":
+      // The user opting out is a completed decision, not a failure — converged
+      // with no reason. Marking it blocked would retry what they asked not to do.
+      return { status: "converged", attempts: 0, nextRetryAt: null, txId, pendingRows: null, backupEntries: null };
+    case "blocked":
+      return {
+        status: outcome.reason === "busy" ? "pending" : "blocked",
+        reason: outcome.reason === "busy" ? "db-busy"
+          : outcome.reason === "database" ? "unreadable"
+          : "permission",
+        attempts: 1,
+        // A busy unit retries; the others do not reschedule themselves.
+        nextRetryAt: outcome.reason === "busy"
+          ? new Date(Date.now() + TERMINAL_RETRY_DELAY_MS * 10).toISOString()
+          : null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+    case "failed":
+      return {
+        status: "unknown",
+        reason: outcome.reason === "timeout" ? "timeout"
+          : outcome.reason === "worker-died" ? "worker-died"
+          : "record-write-failed",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+  }
+}
+
+/**
+ * Publish the terminal state of a history job against the transition it belongs
+ * to. A `conflict` means a newer transition won and is deliberately left alone.
+ * A `busy` terminal CAS retries a bounded number of times; when that exhausts,
+ * the previously persisted `pending` schedule is left intact — the same update
+ * needs the lock that was busy, so it cannot record its own failure
+ * (`005_contract.md:277`), and the retry being out of attempts is itself a
+ * terminal observation.
+ */
+export function resolveCodexHistoryTransition(
+  receipt: CodexTransitionVersion,
+  outcome: CodexHistoryJobOutcome,
+): void {
+  const state = classify(outcome, receipt.currentTxId);
+  for (let attempt = 0; attempt < TERMINAL_RETRY_ATTEMPTS; attempt += 1) {
+    const result = updateCodexHistoryTransition(receipt, state);
+    if (result.kind === "updated") return;
+    if (result.kind === "conflict") {
+      // A newer transition already owns the row. Overwriting it would be the
+      // overtaken job overwriting the winner.
+      return;
+    }
+    if (result.reason === "busy") {
+      if (attempt + 1 < TERMINAL_RETRY_ATTEMPTS) sleep(TERMINAL_RETRY_DELAY_MS * (attempt + 1));
+      continue;
+    }
+    // database / unsafe-path: retried CAS will not help.
+    return;
+  }
+}

package/src/codex/history-worker.ts

@@ -0,0 +1,176 @@
+/**
+ * Worker-thread entry for the Codex history unit.
+ *
+ * Everything mutable about history happens here, behind H: the SQLite rows, the
+ * backup manifest, and every rollout patch. Those three do not share a
+ * transaction — sync writes the manifest before its database transaction, and
+ * restore writes rollouts, then the database, then the manifest
+ * (`src/codex/history-provider.ts:606-648,656-698`) — so a busy timeout only
+ * ever serialized a third of a state transition. Holding H across the whole unit
+ * is what stops an opposite-direction process overtaking through the other two.
+ *
+ * The message is deliberately thin, and it does NOT carry a direction. A caller
+ * saying which way history should move is exactly what the durable operation
+ * exists to prevent: `syncResumeHistory: false` means leave history alone, apply
+ * targets opencodex only in legacy mode, and legacy recovery is a different
+ * operation from generic restore. So the Worker is told which JOB to run and
+ * reads the operation from the coordinator row itself.
+ *
+ * Homes are carried explicitly because a Worker is a separate process: it does
+ * not inherit the module-load `CODEX_HOME` that `history-provider.ts` resolves
+ * at import time, so a request that leaned on those constants would silently
+ * address the wrong home.
+ *
+ * Design record: devlog/_plan/260804_codex_write_substrate/020_history_isolation.md.
+ */
+import { withHistoryWriteSerialization } from "./history-lock";
+import {
+  writeHistoryProviderTransition,
+  writeLegacyOpenaiHistoryRecovery,
+  type HistoryWriteTarget,
+} from "./internal/history-writer";
+
+/**
+ * The durable operation, mirrored into the request for diagnostics only.
+ *
+ * The Worker validates this against what it reads and refuses a mismatch rather
+ * than trusting it — a tampered copy must not be able to turn a restore into an
+ * apply. Structured-clone safe by construction: a closed set of string literals.
+ */
+export type CodexHistoryWorkerOperation =
+  | "skip"
+  | "apply-opencodex"
+  | "migrate-openai"
+  | "restore-openai"
+  | "recover-legacy-openai";
+
+export interface HistoryWorkerRunMessage {
+  readonly type: "run";
+  readonly requestId: string;
+  /** Opaque durable job identity; the Worker refuses work that is not current. */
+  readonly jobId: string;
+  readonly operation: CodexHistoryWorkerOperation;
+  readonly canonicalCodexHome: string;
+  readonly canonicalStateDbPath: string;
+  readonly canonicalBackupPath: string;
+  /** Env snapshot: a Worker may not observe parent mutations on every platform. */
+  readonly env?: { readonly CODEX_HOME?: string; readonly OPENCODEX_HOME?: string };
+}
+
+export type HistoryWorkerResult =
+  | { readonly type: "done"; readonly requestId: string; readonly jobId: string;
+      readonly outcome: "converged" | "skipped";
+      readonly rows: number; readonly files: number }
+  | { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
+      readonly reason: "busy" | "database" | "unsafe-path" }
+  | { readonly type: "error"; readonly requestId: string; readonly jobId: string;
+      readonly message: string };
+
+const OPERATIONS: ReadonlySet<string> = new Set<CodexHistoryWorkerOperation>([
+  "skip",
+  "apply-opencodex",
+  "migrate-openai",
+  "restore-openai",
+  "recover-legacy-openai",
+]);
+
+/**
+ * Validate the message before it can reach a writer.
+ *
+ * A malformed message is dropped rather than coerced. Every field is required
+ * and non-empty: an absent path would otherwise fall back to a module-load
+ * constant that points at the wrong home in this process.
+ */
+export function isHistoryWorkerRunMessage(data: unknown): data is HistoryWorkerRunMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const message = data as Record<string, unknown>;
+  const nonEmpty = (value: unknown): value is string =>
+    typeof value === "string" && value.trim().length > 0;
+  return message.type === "run"
+    && nonEmpty(message.requestId)
+    && nonEmpty(message.jobId)
+    && typeof message.operation === "string"
+    && OPERATIONS.has(message.operation)
+    && nonEmpty(message.canonicalCodexHome)
+    && nonEmpty(message.canonicalStateDbPath)
+    && nonEmpty(message.canonicalBackupPath);
+}
+
+/**
+ * Run one history operation under H.
+ *
+ * Exported so the unit can be exercised in-process; the Worker entry below is a
+ * thin adapter over it. `skip` is a real outcome rather than an absence: opting
+ * out of history resume must be recorded, not inferred from nothing happening.
+ */
+export function runHistoryUnitUnderLock(
+  message: HistoryWorkerRunMessage,
+): HistoryWorkerResult {
+  const { requestId, jobId, operation } = message;
+  const target: HistoryWriteTarget = {
+    canonicalStateDbPath: message.canonicalStateDbPath,
+    canonicalBackupPath: message.canonicalBackupPath,
+  };
+
+  if (operation === "skip") {
+    return { type: "done", requestId, jobId, outcome: "skipped", rows: 0, files: 0 };
+  }
+
+  const acquired = withHistoryWriteSerialization(
+    message.canonicalCodexHome,
+    message.canonicalStateDbPath,
+    permit => {
+      if (operation === "recover-legacy-openai") {
+        return writeLegacyOpenaiHistoryRecovery(permit, target);
+      }
+      // apply-opencodex routes history to opencodex; migrate/restore return it to
+      // native. The provider is derived from the operation, never from a caller.
+      const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
+      return writeHistoryProviderTransition(permit, target, provider);
+    },
+  );
+
+  if (acquired.kind !== "completed") {
+    return { type: "blocked", requestId, jobId, reason: acquired.reason };
+  }
+  const result = acquired.value;
+  if (result.failed === true) {
+    return { type: "error", requestId, jobId, message: "history_transition_failed" };
+  }
+  return {
+    type: "done",
+    requestId,
+    jobId,
+    outcome: "converged",
+    rows: result.rows,
+    files: result.files,
+  };
+}
+
+declare const self: Worker;
+
+// Guarded so the module can be imported directly by tests without a Worker host.
+if (typeof self !== "undefined" && typeof (self as { onmessage?: unknown }) === "object") {
+  self.onmessage = (event: MessageEvent<unknown>) => {
+    if (!isHistoryWorkerRunMessage(event.data)) return;
+    const message = event.data;
+    try {
+      if (message.env?.CODEX_HOME) process.env.CODEX_HOME = message.env.CODEX_HOME;
+      if (message.env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = message.env.OPENCODEX_HOME;
+      self.postMessage(runHistoryUnitUnderLock(message));
+    } catch (error) {
+      self.postMessage({
+        type: "error",
+        requestId: message.requestId,
+        jobId: message.jobId,
+        message: error instanceof Error ? error.message : "history_worker_failed",
+      } satisfies HistoryWorkerResult);
+    } finally {
+      // Close from inside the Worker so the thread begins exiting before the
+      // parent's terminate() races isolate realm reclaim on Windows.
+      try {
+        (self as unknown as { close?: () => void }).close?.();
+      } catch { /* already closing */ }
+    }
+  };
+}