@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/native-main-claim.ts

@@ -0,0 +1,178 @@
+import { join } from "node:path";
+
+import { Database } from "bun:sqlite";
+
+import {
+  assertStableLockFile,
+  hardenStableLockFile,
+  openStableLockFile,
+  type StableLockFile,
+} from "./native-main-lock-file";
+import { nativeMainOwnerFilesystemSupported } from "./native-main-owner";
+import type { NativeProfileContext } from "./native-profile-store";
+import { NativeProfileError } from "./native-profile-types";
+
+export const NATIVE_MAIN_CLAIM_DB = ".opencodex-native-main.claim.sqlite";
+
+export interface NativeMainClaimOptions {
+  waitMs?: number;
+  pollMs?: number;
+  hardenPath?: (path: string) => Promise<void>;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+}
+
+export const NATIVE_MAIN_HARDENED_IDENTITY_MAX_ENTRIES = 32;
+export const hardenedIdentities = new Map<string, string>();
+
+export function rememberHardenedIdentity(path: string, identity: string): void {
+  hardenedIdentities.delete(path);
+  hardenedIdentities.set(path, identity);
+  while (hardenedIdentities.size > NATIVE_MAIN_HARDENED_IDENTITY_MAX_ENTRIES) {
+    const oldest = hardenedIdentities.keys().next().value;
+    if (oldest === undefined) break;
+    hardenedIdentities.delete(oldest);
+  }
+}
+
+export function nativeMainClaimPath(context: NativeProfileContext): string {
+  return join(context.codexHome, NATIVE_MAIN_CLAIM_DB);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function isBusy(error: unknown): boolean {
+  const code = errorCode(error);
+  const message = error instanceof Error ? error.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || /database (?:is|table is) locked/i.test(message);
+}
+
+function busyClaimError(message: string): NativeProfileError {
+  return new NativeProfileError("NATIVE_MAIN_CLAIM_BUSY", message, 503, true);
+}
+
+function unavailableClaimError(): NativeProfileError {
+  return new NativeProfileError(
+    "NATIVE_MAIN_CLAIM_UNAVAILABLE",
+    "The native-main cross-process claim is unavailable.",
+    503,
+    true,
+  );
+}
+
+function mapClaimSetupError(error: unknown, busyMessage: string): NativeProfileError {
+  if (error instanceof NativeProfileError) return error;
+  return isBusy(error) ? busyClaimError(busyMessage) : unavailableClaimError();
+}
+
+async function openClaimDatabase(
+  context: NativeProfileContext,
+  options: NativeMainClaimOptions,
+): Promise<{ database: Database; file: StableLockFile }> {
+  const platform = options.platform ?? process.platform;
+  if (!nativeMainOwnerFilesystemSupported(context.codexHome, platform, options.env ?? process.env)) {
+    throw new NativeProfileError(
+      "NATIVE_MAIN_CLAIM_UNAVAILABLE",
+      "Native-main claims are unsupported on this CODEX_HOME filesystem.",
+      503,
+      true,
+    );
+  }
+  const path = nativeMainClaimPath(context);
+  let file: StableLockFile | undefined;
+  let database: Database | undefined;
+  try {
+    file = openStableLockFile(path, platform);
+    const identity = `${file.dev}:${file.ino}`;
+    if (hardenedIdentities.get(path) !== identity) {
+      // The resolved platform is threaded into the DEFAULT hardener, not left to
+      // `hardenStableLockFile`'s own `process.platform` read. Otherwise a test
+      // that forces `platform` here still exercises the host's branch, and the
+      // production default — the thing that actually hardens a coordinator
+      // database — stays unproved. An audit deleted this call entirely and 89
+      // tests stayed green, because nearly every claim test injects `hardenPath`.
+      await (options.hardenPath ?? ((target: string) => hardenStableLockFile(target, platform)))(path);
+      assertStableLockFile(path, file);
+      rememberHardenedIdentity(path, identity);
+    }
+    database = new Database(path, { create: true });
+    // Journal-mode negotiation itself may need a database lock. Disable
+    // SQLite's synchronous busy wait first so a contender never blocks Bun's
+    // event loop while the current shared holder is waiting for JS to release.
+    database.exec("PRAGMA busy_timeout = 0; PRAGMA locking_mode = NORMAL");
+    const mode = database.query<{ journal_mode: string }, []>("PRAGMA journal_mode = DELETE").get()?.journal_mode;
+    if (mode?.toLowerCase() !== "delete") throw new Error("native-main claim database is not in rollback-journal mode");
+    assertStableLockFile(path, file);
+    return { database, file };
+  } catch (error) {
+    try { database?.close(); } catch { /* mapped below */ }
+    try { file?.close(); } catch { /* mapped below */ }
+    throw mapClaimSetupError(error, "Native-main credentials are changing.");
+  }
+}
+
+function releaseClaim(database: Database | undefined, file: StableLockFile | undefined): void {
+  try { database?.exec("ROLLBACK"); } catch { /* close still releases the OS-backed claim */ }
+  try { database?.close(); } catch { /* operation already completed */ }
+  try { file?.close(); } catch { /* operation already completed */ }
+}
+
+export async function withNativeMainSharedClaim<T>(
+  context: NativeProfileContext,
+  operation: () => Promise<T>,
+  options: NativeMainClaimOptions = {},
+): Promise<T> {
+  let database: Database | undefined;
+  let file: StableLockFile | undefined;
+  try {
+    ({ database, file } = await openClaimDatabase(context, options));
+    database.exec("BEGIN");
+    // A deferred BEGIN alone owns no lock. Reading page 1 through sqlite_schema
+    // establishes the SHARED lock that an exclusive transition must drain.
+    database.query<{ rootpage: number }, []>("SELECT rootpage FROM sqlite_schema LIMIT 1").get();
+    assertStableLockFile(nativeMainClaimPath(context), file);
+  } catch (error) {
+    releaseClaim(database, file);
+    throw mapClaimSetupError(error, "Native-main credentials are changing.");
+  }
+  try {
+    return await operation();
+  } finally {
+    releaseClaim(database, file);
+  }
+}
+
+export async function withNativeMainExclusiveClaim<T>(
+  context: NativeProfileContext,
+  operation: () => Promise<T>,
+  options: NativeMainClaimOptions = {},
+): Promise<T> {
+  const deadline = Date.now() + Math.max(0, options.waitMs ?? 0);
+  const pollMs = Math.max(1, options.pollMs ?? 50);
+  for (;;) {
+    let database: Database | undefined;
+    let file: StableLockFile | undefined;
+    try {
+      ({ database, file } = await openClaimDatabase(context, options));
+      database.exec("BEGIN EXCLUSIVE");
+      assertStableLockFile(nativeMainClaimPath(context), file);
+    } catch (error) {
+      releaseClaim(database, file);
+      const mapped = mapClaimSetupError(error, "Native-main credentials are in use.");
+      if (mapped.code === "NATIVE_MAIN_CLAIM_BUSY" && Date.now() < deadline) {
+        await Bun.sleep(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+        continue;
+      }
+      throw mapped;
+    }
+    try {
+      return await operation();
+    } finally {
+      releaseClaim(database, file);
+    }
+  }
+}

package/src/codex/native-main-lock-file.ts

@@ -0,0 +1,162 @@
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  type Stats,
+} from "node:fs";
+
+import { hardenSecretPathAsync } from "../lib/windows-secret-acl";
+
+export interface StableLockFile {
+  readonly fd: number;
+  readonly dev: number;
+  readonly ino: number;
+  close(): void;
+}
+
+export class StableLockPathUnsafeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StableLockPathUnsafeError";
+  }
+}
+
+interface StableLockEntry {
+  readonly fd: number;
+  readonly dev: number;
+  readonly ino: number;
+  refs: number;
+}
+
+// POSIX fcntl locks are process-associated: closing any raw descriptor for an
+// inode can release SQLite locks held through a different descriptor in this
+// process. Keep one side descriptor per canonical lock path and close it only
+// after every SQLite user has closed its connection and released its reference.
+const stableLockEntries = new Map<string, StableLockEntry>();
+
+function reference(path: string, entry: StableLockEntry): StableLockFile {
+  let closed = false;
+  return {
+    fd: entry.fd,
+    dev: entry.dev,
+    ino: entry.ino,
+    close() {
+      if (closed) return;
+      closed = true;
+      entry.refs = Math.max(0, entry.refs - 1);
+      if (entry.refs !== 0) return;
+      if (stableLockEntries.get(path) === entry) stableLockEntries.delete(path);
+      closeSync(entry.fd);
+    },
+  };
+}
+
+function assertRegular(stats: Stats, path: string): void {
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new StableLockPathUnsafeError(`unsafe SQLite lock path: ${path}`);
+  }
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function matches(handle: StableLockFile, stats: Stats): boolean {
+  return handle.dev === stats.dev && handle.ino === stats.ino;
+}
+
+export function openStableLockFile(path: string, platform: NodeJS.Platform = process.platform): StableLockFile {
+  const retained = stableLockEntries.get(path);
+  if (retained) {
+    retained.refs += 1;
+    const handle = reference(path, retained);
+    try {
+      assertStableLockFile(path, handle);
+      return handle;
+    } catch (error) {
+      handle.close();
+      throw error;
+    }
+  }
+  if (existsSync(path)) assertRegular(lstatSync(path), path);
+  const noFollow = platform === "win32" ? 0 : constants.O_NOFOLLOW;
+  const fd = openSync(path, constants.O_RDWR | constants.O_CREAT | noFollow, 0o600);
+  try {
+    const descriptor = fstatSync(fd);
+    assertRegular(descriptor, path);
+    const entry: StableLockEntry = {
+      fd,
+      dev: descriptor.dev,
+      ino: descriptor.ino,
+      refs: 1,
+    };
+    stableLockEntries.set(path, entry);
+    const handle = reference(path, entry);
+    assertStableLockFile(path, handle);
+    return handle;
+  } catch (error) {
+    const entry = stableLockEntries.get(path);
+    if (entry?.fd === fd) stableLockEntries.delete(path);
+    closeSync(fd);
+    throw error;
+  }
+}
+
+export function assertStableLockFile(path: string, handle: StableLockFile): void {
+  let pathStats: Stats;
+  try {
+    pathStats = lstatSync(path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") {
+      throw new StableLockPathUnsafeError(`SQLite lock path identity changed: ${path}`);
+    }
+    throw error;
+  }
+  assertRegular(pathStats, path);
+  if (!matches(handle, pathStats)) {
+    throw new StableLockPathUnsafeError(`SQLite lock path identity changed: ${path}`);
+  }
+}
+
+/**
+ * Harden the stable lock file: chmod everywhere, per-user NTFS ACLs on Windows.
+ *
+ * The platform is a parameter rather than a direct `process.platform` read so the
+ * Windows branch is reachable from a test. It was not, and an audit deleted the
+ * whole ACL delegation without a single test noticing — the primitive underneath
+ * had 73 tests while the call edge that activates it had none. That is the same
+ * absence-as-guarantee defect one layer up: proving a mechanism works says nothing
+ * about whether production still calls it.
+ *
+ * `required: true` is deliberate: a failure to apply the ACL must reject rather
+ * than leave a coordinator database readable by other accounts.
+ */
+export async function hardenStableLockFile(
+  path: string,
+  platform: NodeJS.Platform = process.platform,
+  options: { retryTimedOutOnce?: boolean } = {},
+): Promise<void> {
+  if (platform === "win32") {
+    // Best-effort here: POSIX modes are not authoritative on NTFS, and the
+    // required ACL hardening below is what actually decides.
+    try { chmodSync(path, 0o600); } catch { /* ACL below is authoritative. */ }
+    await hardenSecretPathAsync(path, {
+      required: true,
+      retryTimedOutOnce: options.retryTimedOutOnce,
+    });
+    return;
+  }
+  // On POSIX the mode IS the mechanism, so a failure may not be swallowed.
+  //
+  // The previous unconditional catch was a real fail-open: a coordinator
+  // database that already existed with permissive bits stayed permissive, and
+  // the caller was told the lock file had been hardened. Creation mode 0600 does
+  // not repair an existing file, and there is no ACL fallback outside Windows.
+  chmodSync(path, 0o600);
+}

package/src/codex/native-main-owner.ts

@@ -0,0 +1,329 @@
+import { join } from "node:path";
+
+import { Database } from "bun:sqlite";
+
+import {
+  assertStableLockFile,
+  hardenStableLockFile,
+  openStableLockFile,
+  type StableLockFile,
+} from "./native-main-lock-file";
+import type { NativeProfileContext } from "./native-profile-store";
+import { NativeProfileError } from "./native-profile-types";
+
+export const NATIVE_MAIN_OWNER_RETRY_MS = 250;
+export const NATIVE_MAIN_OWNER_DB = ".opencodex-native-main.owner.sqlite";
+
+export type NativeMainOwnerUnavailableReason = "lock-unavailable" | "unsupported-filesystem";
+
+export type NativeMainOwnerSnapshot =
+  | { status: "acquiring"; homeId: string }
+  | { status: "contended"; homeId: string }
+  | { status: "held"; homeId: string }
+  | { status: "unavailable"; homeId: string; reason: NativeMainOwnerUnavailableReason }
+  | { status: "closing"; homeId: string }
+  | { status: "released"; homeId: string };
+
+export interface NativeMainOwnerOptions {
+  retryMs?: number;
+  hardenPath?: (path: string) => Promise<void>;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface NativeMainOwnerReference {
+  readonly homeId: string;
+  snapshot(): NativeMainOwnerSnapshot;
+  subscribe(listener: (snapshot: NativeMainOwnerSnapshot) => void): () => void;
+  release(): Promise<void>;
+}
+
+interface OwnerEntry {
+  readonly context: NativeProfileContext;
+  readonly lockPath: string;
+  readonly options: Required<Pick<NativeMainOwnerOptions, "retryMs" | "platform">>
+    & Pick<NativeMainOwnerOptions, "env" | "hardenPath">;
+  refs: number;
+  generation: number;
+  snapshot: NativeMainOwnerSnapshot;
+  listeners: Set<(snapshot: NativeMainOwnerSnapshot) => void>;
+  database?: Database;
+  file?: StableLockFile;
+  prepared: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  drive?: Promise<void>;
+  activeOperations: Set<Promise<unknown>>;
+  aclTimeoutRetryUsed: boolean;
+  closing: boolean;
+}
+
+const entries = new Map<string, OwnerEntry>();
+const detachedEntries = new Set<OwnerEntry>();
+let exitHookInstalled = false;
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function isBusy(error: unknown): boolean {
+  const code = errorCode(error);
+  const message = error instanceof Error ? error.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED" || /database (?:is|table is) locked/i.test(message);
+}
+
+export function nativeMainOwnerFilesystemSupported(
+  codexHome: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (platform === "win32") {
+    const normalized = codexHome.replaceAll("/", "\\");
+    if (normalized.startsWith("\\\\?\\UNC\\")) return false;
+    if (normalized.startsWith("\\\\") && !normalized.startsWith("\\\\?\\")) return false;
+  }
+  if (
+    platform === "linux"
+    && (env.WSL_INTEROP !== undefined || env.WSL_DISTRO_NAME !== undefined)
+    && /^\/mnt\/[a-z](?:\/|$)/i.test(codexHome)
+  ) return false;
+  return true;
+}
+
+function publish(entry: OwnerEntry, snapshot: NativeMainOwnerSnapshot): void {
+  entry.snapshot = snapshot;
+  for (const listener of entry.listeners) {
+    try { listener({ ...snapshot }); } catch { /* an observer cannot forfeit process ownership */ }
+  }
+}
+
+function closeDatabase(entry: OwnerEntry): void {
+  const database = entry.database;
+  entry.database = undefined;
+  if (!database) return;
+  try { database.exec("ROLLBACK"); } catch { /* close still releases the OS-backed lock */ }
+  try { database.close(); } catch { /* the process exit path is best-effort */ }
+}
+
+function closeEntry(entry: OwnerEntry): void {
+  closeDatabase(entry);
+  try { entry.file?.close(); } catch { /* the process exit path is best-effort */ }
+  entry.file = undefined;
+}
+
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once("exit", () => {
+    for (const entry of entries.values()) {
+      if (entry.timer) clearTimeout(entry.timer);
+      closeEntry(entry);
+    }
+    for (const entry of detachedEntries) closeEntry(entry);
+    entries.clear();
+    detachedEntries.clear();
+  });
+}
+
+function scheduleRetry(entry: OwnerEntry, generation: number): void {
+  if (entry.closing || entry.refs === 0 || entry.timer) return;
+  entry.timer = setTimeout(() => {
+    entry.timer = undefined;
+    if (entry.generation !== generation || entry.closing || entry.refs === 0) return;
+    entry.drive = drive(entry, generation).finally(() => {
+      if (entry.generation === generation) entry.drive = undefined;
+    });
+  }, entry.options.retryMs);
+  entry.timer.unref?.();
+}
+
+async function prepareOwnerDatabase(entry: OwnerEntry): Promise<void> {
+  if (entry.prepared) return;
+  let file: StableLockFile | undefined;
+  let database: Database | undefined;
+  try {
+    file = openStableLockFile(entry.lockPath, entry.options.platform);
+    database = new Database(entry.lockPath, { create: true });
+    // The resolved platform is threaded into the DEFAULT hardener for the same
+    // reason the claim path does it: otherwise a test that forces `platform`
+    // here still exercises the host's branch, and the production default — the
+    // thing that actually hardens the owner's lock file — stays unproved. An
+    // audit replaced this fallback with a no-op and 91 tests stayed green.
+    if (entry.options.hardenPath) {
+      await entry.options.hardenPath(entry.lockPath);
+    } else {
+      await hardenStableLockFile(entry.lockPath, entry.options.platform, {
+        retryTimedOutOnce: entry.aclTimeoutRetryUsed,
+      });
+    }
+    assertStableLockFile(entry.lockPath, file);
+    entry.file = file;
+    file = undefined;
+  } catch (error) {
+    try { file?.close(); } catch { /* mapped by caller */ }
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* the caller publishes the hard failure */ }
+  }
+  entry.prepared = true;
+}
+
+async function drive(entry: OwnerEntry, generation: number): Promise<void> {
+  if (entry.closing || entry.refs === 0 || entry.generation !== generation || entry.database) return;
+  if (!nativeMainOwnerFilesystemSupported(
+    entry.context.codexHome,
+    entry.options.platform,
+    entry.options.env ?? process.env,
+  )) {
+    publish(entry, { status: "unavailable", homeId: entry.context.homeId, reason: "unsupported-filesystem" });
+    return;
+  }
+  let candidate: Database | undefined;
+  try {
+    await prepareOwnerDatabase(entry);
+    if (entry.closing || entry.refs === 0 || entry.generation !== generation) return;
+    candidate = new Database(entry.lockPath, { create: true });
+    candidate.exec("PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    assertStableLockFile(entry.lockPath, entry.file!);
+    if (entry.closing || entry.refs === 0 || entry.generation !== generation) {
+      try { candidate.exec("ROLLBACK"); } catch { /* close below */ }
+      candidate.close();
+      return;
+    }
+    entry.database = candidate;
+    candidate = undefined;
+    publish(entry, { status: "held", homeId: entry.context.homeId });
+  } catch (error) {
+    try { candidate?.close(); } catch { /* acquisition already failed */ }
+    if (entry.closing || entry.refs === 0 || entry.generation !== generation) return;
+    if (isBusy(error)) {
+      publish(entry, { status: "contended", homeId: entry.context.homeId });
+      scheduleRetry(entry, generation);
+      return;
+    }
+    if (errorCode(error) === "ETIMEDOUT" && !entry.aclTimeoutRetryUsed) {
+      entry.aclTimeoutRetryUsed = true;
+      // A timeout is neither ownership contention nor a permanent ACL denial.
+      // Stay fail-closed in `acquiring` and spend exactly one fresh-budget retry.
+      scheduleRetry(entry, generation);
+      return;
+    }
+    publish(entry, { status: "unavailable", homeId: entry.context.homeId, reason: "lock-unavailable" });
+  }
+}
+
+function entryFor(context: NativeProfileContext, options: NativeMainOwnerOptions): OwnerEntry {
+  const existing = entries.get(context.homeId);
+  if (existing) {
+    if (existing.context.codexHome !== context.codexHome) {
+      throw new NativeProfileError("CODEX_HOME_UNAVAILABLE", "The canonical native-main home changed unexpectedly.", 409);
+    }
+    return existing;
+  }
+  const entry: OwnerEntry = {
+    context,
+    lockPath: join(context.codexHome, NATIVE_MAIN_OWNER_DB),
+    options: {
+      retryMs: Math.max(1, options.retryMs ?? NATIVE_MAIN_OWNER_RETRY_MS),
+      platform: options.platform ?? process.platform,
+      env: options.env,
+      hardenPath: options.hardenPath,
+    },
+    refs: 0,
+    generation: 1,
+    snapshot: { status: "acquiring", homeId: context.homeId },
+    listeners: new Set(),
+    activeOperations: new Set(),
+    aclTimeoutRetryUsed: false,
+    prepared: false,
+    closing: false,
+  };
+  entries.set(context.homeId, entry);
+  installExitHook();
+  return entry;
+}
+
+export function retainNativeMainOwner(
+  context: NativeProfileContext,
+  options: NativeMainOwnerOptions = {},
+): NativeMainOwnerReference {
+  const entry = entryFor(context, options);
+  if (entry.closing) {
+    throw new NativeProfileError("NATIVE_MAIN_OWNER_BUSY", "Native-main ownership is closing.", 503, true);
+  }
+  entry.refs += 1;
+  if (!entry.drive && !entry.database && !entry.timer && entry.snapshot.status !== "unavailable") {
+    const generation = entry.generation;
+    entry.drive = drive(entry, generation).finally(() => {
+      if (entry.generation === generation) entry.drive = undefined;
+    });
+  }
+  let released = false;
+  return {
+    homeId: context.homeId,
+    snapshot: () => ({ ...entry.snapshot }),
+    subscribe(listener) {
+      entry.listeners.add(listener);
+      listener({ ...entry.snapshot });
+      return () => { entry.listeners.delete(listener); };
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      entry.refs = Math.max(0, entry.refs - 1);
+      if (entry.refs !== 0 || entry.closing) return;
+      entry.closing = true;
+      entry.generation += 1;
+      if (entry.timer) clearTimeout(entry.timer);
+      entry.timer = undefined;
+      publish(entry, { status: "closing", homeId: entry.context.homeId });
+      // Detach synchronously before the first await. startServer is synchronous,
+      // so a failed listen must be able to create a fresh reference immediately;
+      // SQLite will keep that successor contended until this entry finishes close.
+      if (entries.get(entry.context.homeId) === entry) entries.delete(entry.context.homeId);
+      detachedEntries.add(entry);
+      if (entry.drive) await Promise.allSettled([entry.drive]);
+      while (entry.activeOperations.size > 0) {
+        await Promise.allSettled([...entry.activeOperations]);
+      }
+      closeEntry(entry);
+      publish(entry, { status: "released", homeId: entry.context.homeId });
+      detachedEntries.delete(entry);
+    },
+  };
+}
+
+export function nativeMainOwnerSnapshot(context: NativeProfileContext): NativeMainOwnerSnapshot | null {
+  const entry = entries.get(context.homeId);
+  return entry ? { ...entry.snapshot } : null;
+}
+
+export function assertNativeMainOwner(context: NativeProfileContext): void {
+  const entry = entries.get(context.homeId);
+  if (entry?.snapshot.status === "held" && entry.database && !entry.closing) return;
+  const unavailable = entry?.snapshot.status === "unavailable";
+  throw new NativeProfileError(
+    unavailable ? "NATIVE_MAIN_OWNER_UNAVAILABLE" : "NATIVE_MAIN_OWNER_BUSY",
+    unavailable
+      ? "This process cannot establish native-main ownership for the effective CODEX_HOME."
+      : "Another OpenCodex process owns the physical native-main login for the effective CODEX_HOME.",
+    503,
+    true,
+  );
+}
+
+export async function withNativeMainOwnerOperation<T>(
+  context: NativeProfileContext,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const entry = entries.get(context.homeId);
+  // Direct manager unit tests and non-server library consumers retain the historical
+  // transaction-only behavior. Every live server registers an entry before listen.
+  if (!entry) return operation();
+  assertNativeMainOwner(context);
+  let tracked!: Promise<T>;
+  tracked = Promise.resolve().then(operation).finally(() => { entry.activeOperations.delete(tracked); });
+  entry.activeOperations.add(tracked);
+  return tracked;
+}