@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/service/cli.ts

@@ -13,7 +13,8 @@ import { resolveServiceListenPort, reportServiceServing } from "./health";
 import { platformOps, proxyStillLiveAfterStop, stopTrackedProxyForServiceCommand, installServiceSafely, installFreshWindowsSchedulerSafely, removeServiceInstallState, isServiceInstalled } from "./orchestration";
 import { repairService } from "./repair";
 import type { ServiceRepairVerb } from "./repair";
-import { TASK, plistPath, readServiceBackend } from "./state";
+import { TASK, plistPath, readServiceBackend, releaseServiceOwner, resolveServiceOwnership } from "./state";
+import { foreignServiceOwnerRefusal, unknownServiceOwnerRefusal } from "./repair";
 import type { ServiceBackend } from "./state";
 import { unitPath } from "./systemd";
 import { inspectWindowsSchedulerServiceStatus, schtasksErrorDetail, probeWindowsSchedulerTask } from "./windows-scheduler";
@@ -233,6 +234,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     case "install":
       assertServiceEnvironmentMatchesInstall();
       assertServiceAuthEnvironment();
+      // The install may advance provenance, but it may take back only the owner it observed
+      // before touching the registration. A desktop successor that claims ownership while
+      // the install is running must survive the late release below.
+      const ownershipBeforeInstall = resolveServiceOwnership();
+      if (ownershipBeforeInstall.kind === "unknown") {
+        console.error(`❌ ${unknownServiceOwnerRefusal(ownershipBeforeInstall.reason, "install")}`);
+        process.exitCode = 1;
+        break;
+      }
       // A manually started proxy can still own the configured port while the service
       // registration is absent or unloaded. Stop both the registered manager and any
       // tracked standalone listener before loading the freshly written service assets.
@@ -258,6 +268,23 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         process.exitCode = 1;
         break;
       }
+      // ONLY now. `install` is the verb that takes the runtime back, and it does so after the
+      // registration exists — releasing first meant a cancelled UAC prompt, a failed
+      // registration or an aborted cleanup left the retained npm registration looking
+      // CLI-owned, so the next incidental repair would reactivate it.
+      //
+      // `repair` and `restart` refuse under a foreign owner precisely because they run
+      // incidentally — from a tray helper, from `ocx update`, from a doctor suggestion — and
+      // undoing a takeover the user consented to must be something the user asked for.
+      {
+        const released = releaseServiceOwner(ownershipBeforeInstall, { allowRevisionAdvance: true });
+        if (released) {
+          console.log(
+            `ℹ️  The desktop app owned the background runtime (install ${released.installId}, `
+            + `consent generation ${released.consentGeneration}); this install took it back.`,
+          );
+        }
+      }
       // The wrapper was written moments ago in this process, so the configured port
       // and the baked one cannot have diverged yet — unlike `start`, which reads the
       // installed artifact instead.
@@ -269,15 +296,34 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       // Same one-time marker and same guards (TTY, gh auth, agent deferral) apply.
       await maybeShowStarPrompt();
       break;
-    case "start":
+    case "start": {
       // The installed launcher preserves the recorded CODEX_SQLITE_HOME: a
       // changed sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME would start the service
       // on the recorded database while this shell resolves another, splitting
       // native Codex history between databases. Same guard `stop` already runs.
       assertServiceEnvironmentMatchesInstall();
+      // `start` activates the npm registration, so it refuses on the same terms repair does.
+      // The Windows tray starts the service automatically, which would otherwise put a second
+      // proxy beside the one the desktop app is running without anyone asking for it.
+      // `stop` and `uninstall` are deliberately NOT gated: they deactivate.
+      //
+      // Reported rather than thrown: the tray drives this through `runTrayProxyStart`, which
+      // does not catch, and a refusal is a decision rather than a crash.
+      const ownership = resolveServiceOwnership();
+      const refusal = ownership.kind === "unknown"
+        ? unknownServiceOwnerRefusal(ownership.reason, "start")
+        : ownership.kind === "owned" && ownership.ownership.owner !== "cli"
+          ? foreignServiceOwnerRefusal(ownership.ownership, "start")
+          : null;
+      if (refusal) {
+        console.error(`❌ ${refusal}`);
+        process.exitCode = 1;
+        break;
+      }
       ops.start();
       await reportServiceServing("started");
       break;
+    }
     case "stop": {
       assertServiceEnvironmentMatchesInstall();
       // Only stop what is actually installed. The unguarded call ran a real `launchctl unload`

package/src/service/health.ts

@@ -32,9 +32,10 @@ export function resolveServiceListenPort(override?: number): number {
   return 10100;
 }
 
-export function buildServiceShellCommand(bun: string, cli: string, port = resolveServiceListenPort()): string {
+export function buildServiceShellCommand(bun: string, cli: string | null, port = resolveServiceListenPort()): string {
   const tokenFile = serviceApiTokenFilePath();
-  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${shellQuote(cli)} start --port ${port}`;
+  const args = cli ? `${shellQuote(cli)} start` : "start";
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${args} --port ${port}`;
 }
 
 /**

package/src/service/install-state-contract.d.mts

@@ -0,0 +1,27 @@
+export type {
+  AuthoritativeServiceStateRecord,
+  ServiceInstallStateRecord,
+  ServiceOwnershipRecord as OwnershipClaim,
+  ServiceStateRecordEvidence as InstallStateEvidence,
+} from "./state-record.mjs";
+
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+} from "./state-record.mjs";
+
+import type { ServiceStateRecordEvidence } from "./state-record.mjs";
+
+export type OwnershipResolution =
+  | { readonly kind: "none"; readonly revision: number; readonly needsRepair?: boolean }
+  | { readonly kind: "owned"; readonly ownership: { owner: string; installId: string; consentGeneration: number }; readonly revision: number }
+  | { readonly kind: "unknown"; readonly reason: string };
+
+export declare const SERVICE_STATE_FILE: "service-state.json";
+export declare function parseOwnershipClaim(value: unknown): import("./state-record.mjs").ServiceOwnershipRecord | null;
+export declare function parseInstallStateRecord(value: unknown): import("./state-record.mjs").ServiceInstallStateRecord | null;
+export declare function inspectInstallStateBytes(path: string, read: (path: string) => string): ServiceStateRecordEvidence;
+export declare function resolveOwnershipFromEvidence(evidence: readonly ServiceStateRecordEvidence[]): OwnershipResolution;
+export declare function serviceStateFilesFor(opencodexHomeDir: string, defaultHomeDir: string, platform?: NodeJS.Platform): string[];

package/src/service/install-state-contract.mjs

@@ -0,0 +1,34 @@
+/** Compatibility surface for the shared install-state contract landed before C2 hardening. */
+import {
+  inspectServiceStateRecords,
+  parseServiceInstallStateRecord,
+  parseServiceOwnershipRecord,
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+  serviceStatePathsForHomes,
+} from "./state-record.mjs";
+
+export const SERVICE_STATE_FILE = "service-state.json";
+export const parseOwnershipClaim = parseServiceOwnershipRecord;
+export const parseInstallStateRecord = parseServiceInstallStateRecord;
+export const serviceStateFilesFor = serviceStatePathsForHomes;
+export {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+  selectAuthoritativeServiceState,
+  serviceStateFingerprint,
+};
+
+export function inspectInstallStateBytes(path, read) {
+  return inspectServiceStateRecords([path], read)[0];
+}
+
+export function resolveOwnershipFromEvidence(evidence) {
+  const selected = selectAuthoritativeServiceState(evidence);
+  if (selected.kind === "unknown" || selected.kind === "none") return selected;
+  return selected.state.ownership
+    ? { kind: "owned", ownership: selected.state.ownership, revision: selected.revision }
+    : { kind: "none", revision: selected.revision };
+}

package/src/service/launchd.ts

@@ -160,7 +160,7 @@ function launchdServiceCommand(
  */
 export function expectedLaunchdCommand(
   port: number,
-  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string } } = {},
+  deps: { state?: ServiceInstallState | null; entry?: { bun: string; cli: string | null } } = {},
 ): string {
   const state = deps.state === undefined ? readServiceInstallState() : deps.state;
   if (state?.launcherPath) return buildServiceLauncherShellCommand(state.launcherPath, port);

package/src/service/orchestration.ts

@@ -11,7 +11,7 @@ import type { ServiceDiagnostic } from "./diagnostics";
 import { assertServiceEnvironmentMatchesInstall } from "./guards";
 import { runLaunchctl, launchdEvictionTargets, launchctlBootoutBenign, probeLaunchdLoadState, installLaunchd, startLaunchd, stopLaunchd, statusLaunchd, uninstallLaunchd } from "./launchd";
 import { assertSchedulerRegistrationBeforeStart } from "./repair";
-import { SERVICE_MANAGED_ENV, TASK, plistPath, serviceStatePaths, writeServiceInstallState } from "./state";
+import { SERVICE_MANAGED_ENV, TASK, plistPath, removeServiceInstallStateRecords, writeServiceInstallState } from "./state";
 import type { ServiceBackend } from "./state";
 import { unitPath, isSystemd, installSystemd, startSystemd, stopSystemd, statusSystemd, uninstallSystemd, systemdServiceInstallCleanupOps } from "./systemd";
 import { writeWindowsSchedulerAssets, stageWindowsSchedulerRegistrationXml, removeWindowsSchedulerRegistrationStage, registerFreshWindowsSchedulerTask, recordWindowsSchedulerOwnership, removeNativeWindowsServiceForScheduler, installWindows, installWindowsNative, startWindows, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, statusWindows, statusWindowsXml, killWindowsServiceWrapperProcesses, uninstallWindows, classifyWindowsServiceStop } from "./windows-ops";
@@ -527,9 +527,7 @@ export function stopServiceIfInstalledDetailed(): ServiceStopOutcome {
 
 /** Delete install-state files; stale state would make `ocx update` "reinstall" a service that no longer exists. */
 export function removeServiceInstallState(): void {
-  for (const path of serviceStatePaths()) {
-    try { if (existsSync(path)) unlinkSync(path); } catch { /* best-effort */ }
-  }
+  removeServiceInstallStateRecords();
 }
 
 type UninstallServiceHooksForTests = {

package/src/service/ownership-compatibility.ts

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { parseStrictSemver } from "../lib/strict-semver";
+import type {
+  ServiceInstallState,
+  ServiceOwnershipSubject,
+} from "./state";
+import {
+  SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+} from "./install-state-contract.mjs";
+
+export type ManagingCliRole = "service-registration" | "path";
+
+export type ManagingCliObservation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "observed"; readonly version: string; readonly identity: string };
+
+export type RegisteredManagingCliInvocation =
+  | { readonly status: "absent" }
+  | { readonly status: "unknown"; readonly reason: string }
+  | { readonly status: "resolved"; readonly executable: string; readonly args: readonly string[] };
+
+/** Resolve the exact command baked into the preserved service registration. */
+export function registeredManagingCliInvocation(
+  state: ServiceInstallState | null,
+): RegisteredManagingCliInvocation {
+  if (!state) return { status: "absent" };
+  if (state.launcherPath) {
+    return isAbsolute(state.launcherPath)
+      ? { status: "resolved", executable: state.launcherPath, args: [] }
+      : { status: "unknown", reason: "the recorded service launcher is not absolute" };
+  }
+  if (!state.bunPath || !isAbsolute(state.bunPath)) {
+    return { status: "unknown", reason: "the registered service executable is missing or not absolute" };
+  }
+  if (state.cliPath === null) return { status: "resolved", executable: state.bunPath, args: [] };
+  if (typeof state.cliPath === "string" && isAbsolute(state.cliPath)) {
+    return { status: "resolved", executable: state.bunPath, args: [state.cliPath] };
+  }
+  return { status: "unknown", reason: "the registered service CLI path is missing or not absolute" };
+}
+
+export interface ServiceTakeoverCompatibilityInput {
+  readonly state: ServiceInstallState | null;
+  readonly subject: ServiceOwnershipSubject;
+  readonly managers: Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
+}
+
+export type ServiceTakeoverCompatibility =
+  | {
+      readonly kind: "supported";
+      readonly protocolVersion: typeof SERVICE_OWNERSHIP_PROTOCOL_VERSION;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+      /** Opaque binding over the approved subject and both managing-CLI observations. */
+      readonly token: string;
+    }
+  | {
+      readonly kind: "blocked";
+      readonly reason:
+        | "managing-cli-unknown"
+        | "managing-cli-unsupported"
+        | "managing-cli-unobserved"
+        | "service-protocol-unsupported";
+      readonly detail: string;
+      readonly minimumCliVersion: typeof SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION;
+    };
+
+function comparePrerelease(left: readonly (bigint | string)[], right: readonly (bigint | string)[]): number {
+  if (left.length === 0 || right.length === 0) return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === undefined || b === undefined) return a === b ? 0 : a === undefined ? -1 : 1;
+    if (a === b) continue;
+    if (typeof a === "bigint" && typeof b === "bigint") return a < b ? -1 : 1;
+    if (typeof a === "bigint") return -1;
+    if (typeof b === "bigint") return 1;
+    return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+function versionSupportsOwnership(value: string): boolean {
+  const actual = parseStrictSemver(value);
+  const minimum = parseStrictSemver(SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION);
+  if (!actual || !minimum) return false;
+  for (let index = 0; index < actual.core.length; index += 1) {
+    if (actual.core[index] !== minimum.core[index]) return actual.core[index]! > minimum.core[index]!;
+  }
+  return comparePrerelease(actual.prerelease, minimum.prerelease) >= 0;
+}
+
+function compatibilityToken(input: ServiceTakeoverCompatibilityInput): string {
+  return createHash("sha256").update(JSON.stringify({
+    subject: input.subject,
+    protocolVersion: input.state?.ownershipProtocolVersion ?? null,
+    managers: {
+      "service-registration": input.managers["service-registration"],
+      path: input.managers.path,
+    },
+  })).digest("hex");
+}
+
+/**
+ * Decide whether permanent desktop ownership can be offered.
+ *
+ * Both managing surfaces are mandatory observations. `absent` is a trustworthy answer;
+ * `unknown` is not. An observed service registration additionally needs the protocol marker
+ * written by a CLI whose start/repair/update paths honor the ownership claim. This is what
+ * keeps the preserved registration from starting an older runtime at the next login.
+ */
+export function assessServiceTakeoverCompatibility(
+  input: ServiceTakeoverCompatibilityInput,
+): ServiceTakeoverCompatibility {
+  const observed = Object.entries(input.managers) as Array<[ManagingCliRole, ManagingCliObservation]>;
+  const unknown = observed.find(([, manager]) => manager.status === "unknown");
+  if (unknown) return {
+    kind: "blocked",
+    reason: "managing-cli-unknown",
+    detail: `${unknown[0]} compatibility could not be determined`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const present = observed.filter(([, manager]) => manager.status === "observed") as Array<[
+    ManagingCliRole,
+    Extract<ManagingCliObservation, { status: "observed" }>,
+  ]>;
+  if (present.length === 0) return {
+    kind: "blocked",
+    reason: "managing-cli-unobserved",
+    detail: "no managing OpenCodex CLI installation was observed",
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  const unsupported = present.find(([, manager]) => !versionSupportsOwnership(manager.version));
+  if (unsupported) return {
+    kind: "blocked",
+    reason: "managing-cli-unsupported",
+    detail: `${unsupported[0]} uses OpenCodex ${unsupported[1].version}; ${SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION} or later is required`,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+  };
+  if (input.managers["service-registration"].status === "observed"
+    && input.state?.ownershipProtocolVersion !== SERVICE_OWNERSHIP_PROTOCOL_VERSION) {
+    return {
+      kind: "blocked",
+      reason: "service-protocol-unsupported",
+      detail: "the preserved service registration was not written by an ownership-aware CLI",
+      minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    };
+  }
+  return {
+    kind: "supported",
+    protocolVersion: SERVICE_OWNERSHIP_PROTOCOL_VERSION,
+    minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
+    token: compatibilityToken(input),
+  };
+}
+
+export function sameServiceTakeoverCompatibility(
+  left: ServiceTakeoverCompatibility,
+  right: ServiceTakeoverCompatibility,
+): boolean {
+  return left.kind === "supported" && right.kind === "supported" && left.token === right.token;
+}

package/src/service/ownership-mutation-lease.d.mts

@@ -0,0 +1,32 @@
+export interface OwnershipMutationLeaseOptions {
+  readonly waitMs?: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => void;
+  readonly processAlive?: (pid: number) => boolean;
+  readonly beforeRelease?: (lockPath: string) => void;
+  readonly joinToken?: string;
+}
+
+export interface OwnershipMutationLease { readonly token: string; release(): void }
+
+export declare const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV: "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export declare function ownershipMutationLeaseChildEnvironment(
+  environment: NodeJS.ProcessEnv,
+  token: string,
+): NodeJS.ProcessEnv;
+
+export declare function unprivilegedOwnershipMutationEnvironment(
+  environment: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv;
+
+export declare function acquireOwnershipMutationLease(
+  statePaths: readonly string[],
+  options?: OwnershipMutationLeaseOptions,
+): OwnershipMutationLease;
+
+export declare function withOwnershipMutationLease<T>(
+  statePaths: readonly string[],
+  run: () => T,
+  options?: OwnershipMutationLeaseOptions,
+): T;

package/src/service/ownership-mutation-lease.mjs

@@ -0,0 +1,211 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const WAIT_MS = 2_000;
+const POLL_MS = 20;
+const STALE_MS = 30_000;
+const PROCESS_INSTANCE = randomUUID();
+const held = new Map();
+const delegatedTokens = new Map();
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+export const OWNERSHIP_MUTATION_LEASE_TOKEN_ENV = "OCX_OWNERSHIP_MUTATION_LEASE_TOKEN";
+
+export function ownershipMutationLeaseChildEnvironment(environment, token) {
+  return { ...environment, [OWNERSHIP_MUTATION_LEASE_TOKEN_ENV]: token };
+}
+
+export function unprivilegedOwnershipMutationEnvironment(environment) {
+  const child = { ...environment };
+  delete child[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  return child;
+}
+
+function sleep(ms) { Atomics.wait(sleeper, 0, 0, ms); }
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code !== "ESRCH"; }
+}
+
+function leasePath(statePaths) {
+  const authority = statePaths.at(-1);
+  if (!authority) throw new Error("cannot acquire ownership mutation lease without a service-state path");
+  try { return `${realpathSync.native(authority)}.mutation.lock`; }
+  catch {
+    try { return join(realpathSync.native(dirname(authority)), `${basename(authority)}.mutation.lock`); }
+    catch { return `${authority}.mutation.lock`; }
+  }
+}
+
+function ownerName(record) {
+  return `v1-${record.pid}-${record.processInstance}-${record.token}.json`;
+}
+
+function parseOwnerName(name) {
+  const match = /^v1-([1-9][0-9]*)-[0-9a-f-]+-[0-9a-f-]+[.]json$/i.exec(name);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+function readOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length !== 1) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    if (!owner.isFile() || owner.size > 4096) return null;
+    const record = JSON.parse(readFileSync(ownerPath, "utf8"));
+    if (record?.version !== 1 || !Number.isSafeInteger(record.pid) || record.pid <= 0
+      || typeof record.processInstance !== "string" || !record.processInstance
+      || typeof record.token !== "string" || !record.token
+      || !Number.isFinite(record.createdAt) || entries[0] !== ownerName(record)) return null;
+    const currentLock = lstatSync(path);
+    const currentOwner = lstatSync(ownerPath);
+    if (currentLock.dev !== lock.dev || currentLock.ino !== lock.ino
+      || currentOwner.dev !== owner.dev || currentOwner.ino !== owner.ino
+      || currentOwner.size !== owner.size) return null;
+    return { path, ownerPath, record, lockDev: lock.dev, lockIno: lock.ino, ownerDev: owner.dev, ownerIno: owner.ino, ownerSize: owner.size, mtimeMs: owner.mtimeMs };
+  } catch { return null; }
+}
+
+function sameOwner(left, right) {
+  return left.record.token === right.record.token
+    && left.record.pid === right.record.pid
+    && left.record.processInstance === right.record.processInstance
+    && left.lockDev === right.lockDev && left.lockIno === right.lockIno
+    && left.ownerDev === right.ownerDev && left.ownerIno === right.ownerIno
+    && left.ownerSize === right.ownerSize;
+}
+
+function readIncompleteOwner(path) {
+  try {
+    const lock = lstatSync(path);
+    if (!lock.isDirectory()) return null;
+    const entries = readdirSync(path);
+    if (entries.length === 0) return { path, ownerPath: null, pid: null, mtimeMs: lock.mtimeMs };
+    if (entries.length !== 1) return null;
+    const pid = parseOwnerName(entries[0]);
+    if (!pid) return null;
+    const ownerPath = join(path, entries[0]);
+    const owner = lstatSync(ownerPath);
+    return owner.isFile() ? { path, ownerPath, pid, mtimeMs: owner.mtimeMs } : null;
+  } catch { return null; }
+}
+
+function reclaim(path, now, alive) {
+  const observed = readOwner(path);
+  const incomplete = observed ? null : readIncompleteOwner(path);
+  if (!observed && !incomplete) return false;
+  const createdAt = observed ? Math.max(observed.record.createdAt, observed.mtimeMs) : incomplete.mtimeMs;
+  const pid = observed?.record.pid ?? incomplete.pid;
+  if (now() - createdAt <= STALE_MS || (pid !== null && alive(pid))) return false;
+  if (observed) {
+    const current = readOwner(path);
+    if (!current || !sameOwner(observed, current)) return false;
+  }
+  try {
+    const ownerPath = observed?.ownerPath ?? incomplete.ownerPath;
+    if (ownerPath) unlinkSync(ownerPath);
+    rmdirSync(path);
+    return true;
+  } catch { return false; }
+}
+
+export function acquireOwnershipMutationLease(
+  statePaths,
+  options = {},
+) {
+  const path = leasePath(statePaths);
+  const nested = held.get(path);
+  if (nested) {
+    nested.depth += 1;
+    return { token: nested.snapshot.record.token, release: () => release(path, options) };
+  }
+  const now = options.now ?? Date.now;
+  const alive = options.processAlive ?? processAlive;
+  const explicitJoinToken = options.joinToken;
+  const envJoinToken = process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  const joinToken = explicitJoinToken ?? envJoinToken ?? delegatedTokens.get(path);
+  if (joinToken) {
+    const owner = readOwner(path);
+    if (owner?.record.token === joinToken && alive(owner.record.pid)) {
+      delegatedTokens.set(path, joinToken);
+      if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+      held.set(path, { depth: 1, snapshot: owner, delegated: true });
+      return { token: joinToken, release: () => release(path, options) };
+    }
+    delegatedTokens.delete(path);
+    if (envJoinToken === joinToken) delete process.env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+    if (explicitJoinToken) throw new Error("ownership mutation lease delegation is invalid or no longer live");
+  }
+  const wait = options.waitMs ?? WAIT_MS;
+  const deadline = now() + wait;
+  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  for (;;) {
+    const record = { version: 1, pid: process.pid, processInstance: PROCESS_INSTANCE, token: randomUUID(), createdAt: now() };
+    const ownerPath = join(path, ownerName(record));
+    let madeDirectory = false;
+    let descriptor = null;
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      madeDirectory = true;
+      descriptor = openSync(ownerPath, "wx", 0o600);
+      writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = null;
+      const snapshot = readOwner(path);
+      if (!snapshot || snapshot.record.token !== record.token) throw new Error("ownership mutation lease could not be verified");
+      held.set(path, { depth: 1, snapshot, delegated: false });
+      return { token: record.token, release: () => release(path, options) };
+    } catch (error) {
+      if (descriptor !== null) { try { closeSync(descriptor); } catch { /* stale recovery owns uncertain cleanup */ } }
+      if (madeDirectory) {
+        try { unlinkSync(ownerPath); } catch { /* partial owner is recovered after dead-PID proof */ }
+        try { rmdirSync(path); } catch { /* owner entry or successor keeps the directory live */ }
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (reclaim(path, now, alive)) continue;
+      if (now() >= deadline) throw new Error(`another process owns the runtime mutation lease at ${path}`);
+      (options.sleep ?? sleep)(POLL_MS);
+    }
+  }
+}
+
+function release(path, options) {
+  const currentHeld = held.get(path);
+  if (!currentHeld) return;
+  currentHeld.depth -= 1;
+  if (currentHeld.depth > 0) return;
+  held.delete(path);
+  if (currentHeld.delegated) return;
+  options.beforeRelease?.(path);
+  try {
+    const current = readOwner(path);
+    if (!current || !sameOwner(currentHeld.snapshot, current)) return;
+    unlinkSync(currentHeld.snapshot.ownerPath);
+    rmdirSync(path);
+  } catch { /* token-specific stale recovery handles an uncertain release */ }
+}
+
+export function withOwnershipMutationLease(statePaths, run, options = {}) {
+  const lease = acquireOwnershipMutationLease(statePaths, options);
+  try { return run(); }
+  finally { lease.release(); }
+}