@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/codex/inject.ts

@@ -7,7 +7,8 @@ import {
   subagentDefaultSyncEffective,
   websocketsEnabled,
 } from "../config";
-import { withCodexWriteLock } from "./codex-write-lock";
+import { CodexWriteLockSkipped, withCodexWriteLock } from "./codex-write-lock";
+import { shouldSyncCodexOnStart } from "./desired-state";
 import { resolveCodexHistoryTransition } from "./history-transition";
 import {
   buildInjectWitness,
@@ -22,6 +23,7 @@ import {
 } from "./inject-coordination";
 import { readIntegrationRecord } from "./integration-record";
 import { classifyNativeRoutedResidue } from "./native-residue";
+import { inspectNativeCodexOwnership } from "../integrations/native/ownership-preflight";
 import {
   resolveCodexCoordinatorDatabasePath,
   resolveEffectiveUserIdentity,
@@ -34,7 +36,7 @@ import {
 } from "./journal";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
 import { restoreCodexCatalogWithPermit } from "./catalog/sync";
-import { syncCodexHistoryProvider } from "./history-provider";
+import { syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
 import {
   deriveCodexHistoryOperation,
   resolveCodexHistoryJobTarget,
@@ -187,8 +189,13 @@ export function providerBaseHost(hostname: string | undefined): string {
 }
 
 export function shouldInjectApiAuthHeader(
-  config: Pick<OcxConfig, "hostname"> | undefined,
+  config: Pick<OcxConfig, "hostname" | "unauthenticatedLoopbackListener"> | undefined,
 ): boolean {
+  // The unauthenticated loopback listener is a loopback bind, so it admits without a
+  // credential (#1102). Emitting the env header anyway would be worse than useless: the
+  // directly-spawned app-server this exists for has no OPENCODEX_API_AUTH_TOKEN in its
+  // environment, and Codex would send an empty header value.
+  if (config?.unauthenticatedLoopbackListener?.enabled) return false;
   return !isLoopbackHostname(config?.hostname);
 }
 
@@ -618,6 +625,8 @@ export function chooseCatalogPathForInjection(
 export interface CodexInjectResult {
   success: boolean;
   message: string;
+  status?: "skipped";
+  skippedReason?: "desired_disabled" | "desired_enabled";
   nativeSubagentDefaultsWarning?: string;
 }
 
@@ -626,6 +635,17 @@ export async function injectCodexConfig(
   config?: OcxConfig,
   options: InjectCodexOptions = {},
 ): Promise<CodexInjectResult> {
+  // Point Codex at the unauthenticated loopback listener when it is enabled (#1102).
+  //
+  // Resolved here rather than at the call sites because every caller already passes the proxy
+  // port and the config together: startup sync, `ocx sync`, and the ensure path would each
+  // need the same two-line change, and a caller that missed it would silently emit a base_url
+  // requiring a credential the directly-spawned app-server does not have.
+  //
+  // The listener port is fixed in config, never OS-assigned, so this value survives restarts
+  // and matches what an already-running app-server read at startup.
+  const loopback = config?.unauthenticatedLoopbackListener;
+  if (loopback?.enabled) port = loopback.port;
   if (!existsSync(CODEX_CONFIG_PATH)) {
     return {
       success: false,
@@ -866,6 +886,14 @@ export async function injectCodexConfig(
   if (eligibility.kind === "legacy-uncoordinated") {
     // Unchanged behavior for homes the coordinator cannot yet adopt. Stated
     // rather than implied: this is the boundary, and adoption is its own phase.
+    if (!shouldSyncCodexOnStart(loadConfig())) {
+      return {
+        success: true,
+        status: "skipped",
+        skippedReason: "desired_disabled",
+        message: "Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
+      };
+    }
     applyNativeArtifacts();
   } else {
     const coordinated = await withCodexWriteLock(
@@ -883,6 +911,9 @@ export async function injectCodexConfig(
         }),
       },
       (ctx) => {
+        if (!shouldSyncCodexOnStart(loadConfig())) {
+          throw new CodexWriteLockSkipped("desired_disabled");
+        }
         /*
          * Publish BEFORE touching the filesystem. `assertPublished` runs after this
          * callback returns and throws unless a transition was recorded, so writing
@@ -965,6 +996,7 @@ export async function injectCodexConfig(
   // handed down fixed; the Worker never takes a direction from its caller.
   const historyOutcome = await runCodexHistoryJob({
     ...resolveCodexHistoryJobTarget(),
+    expectedDesiredEnabled: true,
     operation: deriveCodexHistoryOperation({
       direction: "apply",
       resumeHistory: config?.syncResumeHistory !== false,
@@ -1179,71 +1211,323 @@ export function removeCodexConfig(
   };
 }
 
+export type CodexRestoreArtifactState = "ok" | "skipped" | "failed";
+
+export interface CodexRestoreConfigResult {
+  state: CodexRestoreArtifactState;
+  changed: boolean;
+  action: "journal-restored" | "owned-fields-stripped" | "external-provider-preserved" | "failed";
+  message: string;
+}
+
+export interface CodexRestoreCatalogResult {
+  state: CodexRestoreArtifactState;
+  changed: boolean;
+  removed: number;
+  kept: number;
+  path: string | null;
+  message: string;
+}
+
+export interface CodexRestoreHistoryResult {
+  state: CodexRestoreArtifactState;
+  changed: boolean;
+  reason?: CodexHistoryFailureReason;
+  rows: number;
+  files: number;
+  ejectedRows: number;
+  message: string;
+}
+
+export interface CodexNativeRestoreResult {
+  success: boolean;
+  message: string;
+  externalProvider?: string;
+  artifacts: {
+    config: CodexRestoreConfigResult;
+    catalog: CodexRestoreCatalogResult;
+    history: CodexRestoreHistoryResult;
+  };
+}
+
+function failedHistoryRestore(reason?: CodexHistoryFailureReason): CodexRestoreHistoryResult {
+  return {
+    state: "failed",
+    changed: false,
+    ...(reason ? { reason } : {}),
+    rows: 0,
+    files: 0,
+    ejectedRows: 0,
+    message: reason === "permission"
+      ? "Codex resume history could NOT be restored because permission was denied."
+      : "Codex resume history could NOT be restored — the Codex app appears to be holding the history database.",
+  };
+}
+
+function externalProviderRestoreResult(activeProvider: string): CodexNativeRestoreResult {
+  const message = `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`;
+  return {
+    success: true,
+    message,
+    externalProvider: activeProvider,
+    artifacts: {
+      config: { state: "skipped", changed: false, action: "external-provider-preserved", message },
+      catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
+      history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
+    },
+  };
+}
+
+/** A foreign service claim is an authority boundary, including explicit CLI restore. */
+function foreignOwnershipRestoreRefusal(message: string): CodexNativeRestoreResult {
+  return {
+    success: false,
+    message: `Codex native restore refused: ${message}`,
+    artifacts: {
+      config: { state: "skipped", changed: false, action: "failed", message },
+      catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
+      history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
+    },
+  };
+}
+
+function desiredEnabledRestoreSkip(): CodexNativeRestoreResult {
+  const message = "Codex integration was re-enabled; native restore was skipped.";
+  return skippedRestoreEnvelope(true, message);
+}
+
 /**
- * Recover native Codex: strip opencodex from config.toml AND drop proxy-routed catalog entries,
- * so plain `codex` works when the proxy is stopped. Called by `ocx stop`, the proxy shutdown
- * handler, and `ocx restore`. Idempotent + atomic.
+ * A schema-complete all-skipped envelope for outcomes decided before any
+ * restore machinery runs. Every `restore --json` path must stay shape-stable
+ * with `CodexNativeRestoreResult`; consumers never special-case early exits.
  */
+export function skippedRestoreEnvelope(success: boolean, message: string): CodexNativeRestoreResult {
+  return {
+    success,
+    message,
+    artifacts: {
+      config: { state: "skipped", changed: false, action: "owned-fields-stripped", message },
+      catalog: { state: "skipped", changed: false, removed: 0, kept: 0, path: null, message },
+      history: { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message },
+    },
+  };
+}
+
+/** The config/profile half of a native restore, reported as one artifact. */
+function restoreCodexConfigInline(): CodexRestoreConfigResult {
+  try {
+    const journal = restoreJournalState();
+    const restored = journal.configRestored
+      ? { success: true, message: "Codex config restored from opencodex journal." }
+      : removeCodexConfig({ preserveProfile: journal.profileRestored || journal.profileChanged });
+    return restored.success
+      ? {
+          state: "ok",
+          changed: journal.configRestored || journal.profileRestored || journal.profileChanged || restored.message.startsWith("Removed"),
+          action: journal.configRestored ? "journal-restored" : "owned-fields-stripped",
+          message: restored.message,
+        }
+      : { state: "failed", changed: false, action: "failed", message: restored.message };
+  } catch (error) {
+    return { state: "failed", changed: false, action: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** The catalog half, always inside its own K acquisition. */
+function restoreCodexCatalogArtifact(revalidateDesiredState: boolean): CodexRestoreCatalogResult {
+  const owningCodexHome = getCodexHome();
+  try {
+    const restored = withCatalogWriteSerialization(owningCodexHome, permit =>
+      revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())
+        ? null
+        : restoreCodexCatalogWithPermit(permit, owningCodexHome));
+    return restored.kind === "completed" && restored.value !== null
+      ? { state: "ok", changed: restored.value.removed > 0, ...restored.value, message: "Codex catalog restored." }
+      : restored.kind === "completed"
+        ? {
+            state: "skipped", changed: false, removed: 0, kept: 0, path: null,
+            message: "Codex integration was re-enabled; native catalog restoration was skipped.",
+          }
+        : {
+            state: "failed", changed: false, removed: 0, kept: 0, path: DEFAULT_CATALOG_PATH,
+            message: `Codex catalog could not be restored: ${restored.reason}.`,
+          };
+  } catch (error) {
+    return {
+      state: "failed", changed: false, removed: 0, kept: 0, path: DEFAULT_CATALOG_PATH,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 /**
  * Restore native Codex, running history in a Worker under H.
  *
- * Prefer this everywhere. The synchronous variant below exists only for the
- * process-exit path, where awaiting a thread is its own hazard.
+ * On a coordinated home the config/profile restore happens INSIDE the Codex
+ * write lock, publishing a `remove` transition — the same serialization inject
+ * uses. Without it, an older restore could overwrite a config a concurrent
+ * enable had just written under the lock, and then honestly report success
+ * while desired intent said ON. The desired-state re-read under the lock turns
+ * that lost race into the discriminated `desired_enabled` skip.
  */
-export async function restoreNativeCodexAsync(): Promise<{
-  success: boolean;
-  message: string;
-}> {
-  const inline = restoreNativeCodex({ skipHistory: true });
+export async function restoreNativeCodexAsync(
+  options: { revalidateDesiredState?: boolean } = {},
+): Promise<CodexNativeRestoreResult> {
+  const activeProvider = currentExternalCodexModelProvider();
+  if (activeProvider) {
+    // External-provider courtesy: only the stale journal is removed. The
+    // history worker must not launch — it would turn a read-mostly courtesy
+    // result into a history mutation on a home we do not own.
+    removeJournal();
+    return externalProviderRestoreResult(activeProvider);
+  }
+
+  // `restore` normally honours a human request even when an unrelated
+  // service-manager probe is unavailable. A recorded FOREIGN home is not an
+  // unrelated probe: it is positive evidence another installation owns these
+  // native artifacts, so do not create profile/claim locks before refusing.
+  if (options.revalidateDesiredState) {
+    const ownership = inspectNativeCodexOwnership();
+    if (ownership.ownership === "foreign") return foreignOwnershipRestoreRefusal(ownership.reason);
+  }
+
+  const eligibility = codexWriteCoordinationEligibility({
+    coordinatorPath: () =>
+      resolveCodexCoordinatorDatabasePath(resolveEffectiveUserIdentity(), getCodexHome()),
+    residue: () => classifyNativeRoutedResidue(),
+    integrationRecord: () => readIntegrationRecord(),
+  });
+
+  let config: CodexRestoreConfigResult;
+  let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
+
+  if (eligibility.kind === "coordinated") {
+    // The restore has no candidate bytes to witness; freshness comes from the
+    // filesystem reads and the desired-state re-read performed under the lock.
+    const witness = { authoritySnapshotId: "codex-native-restore" };
+    const coordinated = await withCodexWriteLock(
+      {
+        timeoutMs: DEFAULT_INJECT_LOCK_TIMEOUT_MS,
+        admitted: witness,
+        readAdmissionUnderLock: () => witness,
+      },
+      (ctx) => {
+        if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
+          throw new CodexWriteLockSkipped("desired_enabled");
+        }
+        const published = ctx.coordinator.beginTransition(
+          {
+            nativeGeneration: ctx.expectation.nativeBefore,
+            currentTxId: ctx.currentTxId,
+          },
+          {
+            txId: ctx.expectation.txId,
+            direction: "remove",
+            authoritySnapshotId: ctx.admission.authoritySnapshotId,
+            nextRetryAt: new Date().toISOString(),
+          },
+        );
+        if (published.kind !== "updated") {
+          throw new CodexWriteConflictError(
+            `The Codex transition could not be published: ${published.kind}.`,
+          );
+        }
+        const preImages = captureCodexPreImages();
+        let restored: CodexRestoreConfigResult;
+        try {
+          restored = restoreCodexConfigInline();
+        } catch (error) {
+          const compensated = restoreCodexPreImages(preImages);
+          if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
+          throw error;
+        }
+        return {
+          config: restored,
+          receipt: {
+            nativeGeneration: ctx.expectation.nativeAfter,
+            currentTxId: ctx.expectation.txId,
+          },
+        };
+      },
+    );
+    if (coordinated.status === "skipped") return desiredEnabledRestoreSkip();
+    if (coordinated.status !== "acquired") {
+      config = {
+        state: "failed",
+        changed: false,
+        action: "failed",
+        message: coordinated.status === "busy"
+          ? `Another process is writing Codex configuration right now (waited ${coordinated.waitedMs}ms). Retry shortly.`
+          : `Codex configuration was not restored: ${coordinated.message}`,
+      };
+    } else {
+      config = coordinated.value.config;
+      transitionReceipt = coordinated.value.receipt;
+    }
+  } else {
+    // Legacy-uncoordinated (or unresolvable) homes keep the unserialized path
+    // they have always had; restore is the escape hatch and must not strand
+    // them. The plain re-read still honors an intervening re-enable.
+    if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
+      return desiredEnabledRestoreSkip();
+    }
+    config = restoreCodexConfigInline();
+  }
+
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
   const outcome = await runCodexHistoryJob({
     ...resolveCodexHistoryJobTarget(),
-    operation: deriveCodexHistoryOperation({
-      direction: "restore",
-      // Restore always returns history to native when it runs at all; the
-      // opt-out belongs to apply, which is what put opencodex there.
-      resumeHistory: true,
-      legacyMode: false,
-    }),
+    ...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
+    operation: deriveCodexHistoryOperation({ direction: "restore", resumeHistory: true, legacyMode: false }),
   });
-  const historyMsg =
-    outcome.kind === "converged"
-      ? outcome.rows > 0
-        ? ` Resume history restored from opencodex backup (${outcome.rows} thread(s)).`
-        : ""
-      : outcome.kind === "skipped"
-        ? ""
-        : // A lock we could not take is reported, never counted as nothing to do.
-          ` ⚠️ Codex resume history could NOT be restored — the Codex app appears to be holding the history database. Close Codex and run \`ocx restore\` again.`;
-  return { success: inline.success, message: `${inline.message}${historyMsg}` };
+  if (transitionReceipt) {
+    resolveCodexHistoryTransition(transitionReceipt, outcome);
+  }
+  const history: CodexRestoreHistoryResult = outcome.kind === "converged"
+    ? {
+        state: "ok", changed: outcome.rows > 0, rows: outcome.rows, files: outcome.files, ejectedRows: 0,
+        message: outcome.rows > 0
+          ? `Resume history restored from opencodex backup (${outcome.rows} thread(s)).`
+          : "Codex resume history was already native.",
+      }
+    : outcome.kind === "skipped"
+      ? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "Codex resume history was skipped." }
+      : outcome.kind === "blocked" && (outcome.reason === "desired_disabled" || outcome.reason === "desired_enabled")
+        ? {
+            state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
+            message: outcome.reason === "desired_disabled"
+              ? "Codex integration was disabled; history restoration was skipped."
+              : "Codex integration was enabled; history restoration was skipped.",
+          }
+      : outcome.kind === "blocked" && outcome.reason === "busy"
+        ? failedHistoryRestore("busy")
+        : outcome.kind === "failed"
+          ? failedHistoryRestore(outcome.historyFailureReason)
+          : failedHistoryRestore();
+  const base = catalog.removed > 0
+    ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
+    : config.message;
+  const success = config.state !== "failed"
+    && catalog.state !== "failed"
+    && history.state !== "failed";
+  return {
+    success,
+    message: `${base}${history.state === "failed" ? ` ⚠️ ${history.message}` : ""}`,
+    artifacts: { config, catalog, history },
+  };
 }
 
-export function restoreNativeCodex(options: { skipHistory?: boolean } = {}): {
-  success: boolean;
-  message: string;
-} {
+export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateDesiredState?: boolean } = {}): CodexNativeRestoreResult {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
     removeJournal();
-    return {
-      success: true,
-      message: `External Codex provider ${tomlString(activeProvider)} preserved; no native restore was needed.`,
-    };
+    return externalProviderRestoreResult(activeProvider);
   }
-  const journal = restoreJournalState();
-  const cfg = journal.configRestored
-    ? {
-        success: true,
-        message: "Codex config restored from opencodex journal.",
-      }
-    : removeCodexConfig({
-        preserveProfile: journal.profileRestored || journal.profileChanged,
-      });
-  const owningCodexHome = getCodexHome();
-  const restoredCatalog = withCatalogWriteSerialization(owningCodexHome, permit => restoreCodexCatalogWithPermit(permit, owningCodexHome));
-  const cat =
-    restoredCatalog.kind === "completed"
-      ? restoredCatalog.value
-      : { removed: 0, kept: 0, path: DEFAULT_CATALOG_PATH };
+  if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
+    return desiredEnabledRestoreSkip();
+  }
+  const config = restoreCodexConfigInline();
+  const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true);
   // Design B (loopback) steady state: threads are already tagged openai, so prove the
   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
   // (Windows: WAL writer lock -> seconds of stalling + a false warning on every stop).
@@ -1256,23 +1540,33 @@ export function restoreNativeCodex(options: { skipHistory?: boolean } = {}): {
   }
   // `skipHistory` is how the async wrapper takes this work for itself: the
   // native files come down here, and history runs in the Worker under H.
-  const history = options.skipHistory
+  const rawHistory = options.skipHistory
     ? { rows: 0, files: 0 }
     : syncCodexHistoryProvider("openai", undefined, undefined, {
         skipWhenProvablyNoop,
       });
-  const msg =
-    cat.removed > 0
-      ? `${cfg.message} Catalog restored to ${cat.kept} native model(s) (dropped ${cat.removed} proxy-routed).`
-      : cfg.message;
-  const historyMsg = history.failed
-    ? ` ⚠️ Codex resume history could NOT be restored — the Codex app appears to be holding the history DB. Close the Codex app/IDE and run 'ocx stop' again; until then routed threads stay hidden in the native app.`
-    : history.rows > 0
-      ? ` Resume history restored from opencodex backup (${history.rows} thread(s)).`
-      : history.ejectedRows
-        ? ` ${history.ejectedRows} opencodex history thread(s) were ejected to openai so native Codex can resume them.`
-        : "";
-  return { success: cfg.success, message: `${msg}${historyMsg}` };
+  const history: CodexRestoreHistoryResult = options.skipHistory
+    ? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "History restoration runs asynchronously." }
+    : rawHistory.failed
+      ? failedHistoryRestore(rawHistory.failureReason)
+      : {
+          state: "ok",
+          changed: rawHistory.rows > 0 || (rawHistory.ejectedRows ?? 0) > 0,
+          rows: rawHistory.rows,
+          files: rawHistory.files,
+          ejectedRows: rawHistory.ejectedRows ?? 0,
+          message: rawHistory.rows > 0
+            ? `Resume history restored from opencodex backup (${rawHistory.rows} thread(s)).`
+            : "Codex resume history was already native.",
+        };
+  const message = catalog.removed > 0
+    ? `${config.message} Catalog restored to ${catalog.kept} native model(s) (dropped ${catalog.removed} proxy-routed).`
+    : config.message;
+  return {
+    success: config.state !== "failed" && catalog.state !== "failed" && history.state !== "failed",
+    message,
+    artifacts: { config, catalog, history },
+  };
 }
 
 export function getCodexConfigPath(): string {

package/src/codex/internal/history-writer.ts

@@ -74,7 +74,7 @@ export function writeHistoryProviderTransition(
 export function writeLegacyOpenaiHistoryRecovery(
   permit: HistoryWritePermit,
   target: HistoryWriteTarget,
-): { rows: number; files: number; failed?: true } {
+): CodexHistorySyncResult {
   assertHistoryWritePermit(permit, target.canonicalStateDbPath);
   return restoreLegacyOpenaiHistory(target.canonicalStateDbPath);
 }

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

@@ -140,12 +140,16 @@ export function assertStableLockFile(path: string, handle: StableLockFile): void
 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 });
+    await hardenSecretPathAsync(path, {
+      required: true,
+      retryTimedOutOnce: options.retryTimedOutOnce,
+    });
     return;
   }
   // On POSIX the mode IS the mechanism, so a failure may not be swallowed.

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

@@ -53,6 +53,7 @@ interface OwnerEntry {
   timer?: ReturnType<typeof setTimeout>;
   drive?: Promise<void>;
   activeOperations: Set<Promise<unknown>>;
+  aclTimeoutRetryUsed: boolean;
   closing: boolean;
 }
 
@@ -149,8 +150,13 @@ async function prepareOwnerDatabase(entry: OwnerEntry): Promise<void> {
     // 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.
-    await (entry.options.hardenPath
-      ?? ((target: string) => hardenStableLockFile(target, entry.options.platform)))(entry.lockPath);
+    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;
@@ -196,6 +202,13 @@ async function drive(entry: OwnerEntry, generation: number): Promise<void> {
       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" });
   }
 }
@@ -222,6 +235,7 @@ function entryFor(context: NativeProfileContext, options: NativeMainOwnerOptions
     snapshot: { status: "acquiring", homeId: context.homeId },
     listeners: new Set(),
     activeOperations: new Set(),
+    aclTimeoutRetryUsed: false,
     prepared: false,
     closing: false,
   };
@@ -239,7 +253,7 @@ export function retainNativeMainOwner(
     throw new NativeProfileError("NATIVE_MAIN_OWNER_BUSY", "Native-main ownership is closing.", 503, true);
   }
   entry.refs += 1;
-  if (!entry.drive && !entry.database && !entry.timer) {
+  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;

package/src/codex/native-profile-manager.ts

@@ -913,6 +913,25 @@ export class NativeProfileManager {
     return { removed, live, cleanupFailed, plaintextMayRemain };
   }
 
+  /**
+   * Whether startup or the periodic cleaner has any stage state to inspect.
+   *
+   * Absence is the only lock-free result. Any entry or observation failure
+   * keeps the existing fail-closed sweep, so an unsafe/unreadable stage path
+   * can never be mistaken for an unused profile subsystem.
+   */
+  stageSweepRequired(): boolean {
+    for (const path of [this.context.stageRegistryPath, this.context.stagingRoot]) {
+      try {
+        lstatSync(path);
+        return true;
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") return true;
+      }
+    }
+    return false;
+  }
+
   async sweepStages(): Promise<NativeStageSweepResult> {
     return this.withLock(() => this.sweepStagesLocked());
   }

package/src/codex/native-profile-startup.ts

@@ -130,6 +130,14 @@ function ownerBlockedReason(owner: NativeMainOwnerSnapshot): "owner-conflict" |
 
 async function runOwnedStageSweep(entry: StartupEntry): Promise<boolean> {
   if (typeof (entry.manager as Partial<NativeProfileManager>).sweepStages !== "function") return true;
+  // A fresh installation has no stage registry or staging tree. Avoid creating
+  // and contending on the profile transaction database for an inert subsystem.
+  // Real managers treat every present or uncertain artifact as sweep-required;
+  // partial test/library managers without the preflight keep the old behavior.
+  if (
+    typeof (entry.manager as Partial<NativeProfileManager>).stageSweepRequired === "function"
+    && !entry.manager.stageSweepRequired()
+  ) return true;
   try {
     const result = await withNativeMainOwnerOperation(entry.manager.context, () => entry.manager.sweepStages());
     return !result.plaintextMayRemain;