@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-acquisition.js

@@ -0,0 +1,98 @@
+import { getSyncLockAdmissions } from "./file-lock-sync-admission.js";
+import { isTransientLockFileDenial, maxTransientLockDenials, sidecarLockRetryDelay, sidecarLockTimeout, } from "./sidecar-lock-policy.js";
+import { sleepSync } from "./timing.js";
+/** Owns local arbitration and retry state, independently of filesystem authority. */
+export class SyncLockAcquisition {
+    lockPath;
+    normalizedTargetPath;
+    retry;
+    timeoutMs;
+    #admissions = getSyncLockAdmissions();
+    #token = {};
+    #owns = false;
+    #startedAt = performance.now();
+    #attempt = 0;
+    #transientDenials = 0;
+    constructor(lockPath, normalizedTargetPath, retry, timeoutMs) {
+        this.lockPath = lockPath;
+        this.normalizedTargetPath = normalizedTargetPath;
+        this.retry = retry;
+        this.timeoutMs = timeoutMs;
+    }
+    get owns() { return this.#owns; }
+    hasToken() { return this.#admissions.get(this.normalizedTargetPath) === this.#token; }
+    assert() {
+        if (!this.hasToken())
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+    }
+    reserve() {
+        if (this.#owns)
+            return;
+        // An existing synchronous owner can finish only after this stack unwinds.
+        if (this.#admissions.has(this.normalizedTargetPath)) {
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+        }
+        this.#admissions.set(this.normalizedTargetPath, this.#token);
+        this.#owns = true;
+    }
+    release() {
+        if (this.#owns && this.hasToken())
+            this.#admissions.delete(this.normalizedTargetPath);
+        this.#owns = false;
+    }
+    run(callback) {
+        this.assert();
+        try {
+            return callback();
+        }
+        finally {
+            this.assert();
+        }
+    }
+    waitForRetry() {
+        this.release();
+        const delay = sidecarLockRetryDelay(this.retry, this.timeoutMs, performance.now() - this.#startedAt, this.#attempt);
+        if (delay === undefined)
+            throw sidecarLockTimeout(this.lockPath, this.normalizedTargetPath);
+        sleepSync(delay);
+        this.#attempt += 1;
+    }
+    retryDenial(error) {
+        if (!isTransientLockFileDenial(error, this.lockPath) ||
+            ++this.#transientDenials > maxTransientLockDenials)
+            return false;
+        try {
+            this.waitForRetry();
+        }
+        catch (waitError) {
+            // Exhausted backoff must preserve the filesystem denial diagnosis.
+            if (waitError.code === "file_lock_timeout")
+                throw error;
+            throw waitError;
+        }
+        return true;
+    }
+    monitor(held, handle, callback, interval, receiver, recordTimer) {
+        if (!callback || (interval ?? 0) <= 0)
+            return;
+        const { lockPath, normalizedTargetPath } = this;
+        const timer = setInterval(() => {
+            let stillHeld;
+            try {
+                stillHeld = handle.verifyStillHeld();
+            }
+            catch {
+                stillHeld = false;
+            }
+            if (!stillHeld && held.timer) {
+                clearInterval(held.timer);
+                held.timer = undefined;
+                Reflect.apply(callback, receiver, [{ lockPath, normalizedTargetPath }]);
+            }
+        }, interval);
+        // Root cleanup retains a separate provisional receipt before unref can fail.
+        recordTimer?.(timer);
+        held.timer = timer;
+        timer.unref();
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-admission.d.ts

@@ -0,0 +1,17 @@
+import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+export type SyncHeldLock = {
+    fd: number | undefined;
+    lockPath: string;
+    normalizedTargetPath: string;
+    parsePayload?: (raw: string) => unknown;
+    refCount: number;
+    reentrantOwner?: string;
+    snapshot: SidecarLockSnapshot;
+    timer?: NodeJS.Timeout;
+};
+export declare function foreignSyncHeldLock(route: "raw" | "root", target: string): object | undefined;
+export declare function getSyncHeldLocks(): Map<string, SyncHeldLock>;
+export declare function getSyncLockAdmissions(): Map<string, object>;
+export declare function defaultSyncShouldReclaim(snapshot: SidecarLockSnapshot, staleMs: number, nowMs: number): boolean;
+export declare function syncReclaimGuardExists(reclaimGuardPath: string): boolean;
+export declare function ensureSyncLockExitCleanupRegistered(cleanup: () => void, lockPath: string, normalizedTargetPath: string): void;

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-admission.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import { sidecarLockPayloadCreatedAtMs, sidecarLockTimeout } from "./sidecar-lock-policy.js";
+import { ensureSidecarLockCleanupRegistered } from "./sidecar-lock-registration.js";
+const SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncSidecarLocks");
+const SYNC_ADMISSIONS_KEY = Symbol.for("fsSafe.syncSidecarLockAdmissions");
+const SYNC_CLEANUP_REGISTERED_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistered");
+const SYNC_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupHandler");
+const SYNC_CLEANUP_REGISTRATION_KEY = Symbol.for("fsSafe.syncSidecarLockCleanupRegistration");
+const ROOT_SYNC_HELD_LOCKS_KEY = Symbol.for("fsSafe.syncRootSidecarLocks.v1");
+export function foreignSyncHeldLock(route, target) {
+    const key = route === "raw" ? ROOT_SYNC_HELD_LOCKS_KEY : SYNC_HELD_LOCKS_KEY;
+    const state = globalThis;
+    return state[key]?.get(target);
+}
+export function getSyncHeldLocks() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_HELD_LOCKS_KEY]) {
+        globalWithState[SYNC_HELD_LOCKS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_HELD_LOCKS_KEY];
+}
+export function getSyncLockAdmissions() {
+    const globalWithState = globalThis;
+    if (!globalWithState[SYNC_ADMISSIONS_KEY]) {
+        globalWithState[SYNC_ADMISSIONS_KEY] = new Map();
+    }
+    return globalWithState[SYNC_ADMISSIONS_KEY];
+}
+export function defaultSyncShouldReclaim(snapshot, staleMs, nowMs) {
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(snapshot.payload);
+    if (createdAtMs !== null)
+        return nowMs - createdAtMs > staleMs;
+    return !snapshot.stat || nowMs - snapshot.stat.mtimeMs > staleMs;
+}
+export function syncReclaimGuardExists(reclaimGuardPath) {
+    try {
+        fs.lstatSync(reclaimGuardPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function ensureSyncLockExitCleanupRegistered(cleanup, lockPath, normalizedTargetPath) {
+    ensureSidecarLockCleanupRegistered({
+        event: "exit",
+        registered: SYNC_CLEANUP_REGISTERED_KEY,
+        registering: SYNC_CLEANUP_REGISTRATION_KEY,
+        handler: SYNC_CLEANUP_HANDLER_KEY,
+        reentryError: () => sidecarLockTimeout(lockPath, normalizedTargetPath),
+    }, cleanup, true);
+}

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-root-acquire.d.ts

@@ -0,0 +1,3 @@
+import type { FileLockSyncAcquireOptions, FileLockSyncHandle } from "./file-lock-sync.js";
+import type { Root } from "./root-impl.js";
+export declare function acquireFileLockSyncWithRoot<TPayload extends Record<string, unknown>>(targetPath: string, inputOptions: FileLockSyncAcquireOptions<TPayload>, lockRoot: Root): FileLockSyncHandle;

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-root-acquire.js

@@ -0,0 +1,303 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { captureRootSyncAcquireOptions } from "./file-lock-sync-root-options.js";
+import { defaultSyncShouldReclaim, foreignSyncHeldLock } from "./file-lock-sync-admission.js";
+import { isTransientLockFileDenial, sidecarLockStale } from "./sidecar-lock-policy.js";
+import { serializeSidecarLockPayload, } from "./sidecar-lock-reclaim.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { SyncLockAcquisition } from "./file-lock-sync-acquisition.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { admitFileLockSyncRootPath, assertFileLockSyncRootPathsCurrent, captureFileLockSyncRootAuthority, normalizeFileLockSyncTargetWithRoot, } from "./file-lock-sync-root.js";
+import { cleanupCreatedRootSyncLock, FileLockSyncRootArbitrationCollision, tryReuseCurrentRootSyncHeldLock, } from "./file-lock-sync-root-arbitration.js";
+import { fileLockSyncRootSnapshotStillCurrent, } from "./file-lock-sync-root-io.js";
+import { createFileLockSyncRootDirectory, createFileLockSyncRootFile, fileLockSyncRootGuardExists, fileLockSyncRootDirectoryReceiptStillCurrent, refreshFileLockSyncRootFileReceipt, removeFileLockSyncRootDirectory, removeFileLockSyncRootFile, } from "./file-lock-sync-root-mutation.js";
+import { createRootSyncHeldLockHandle, ensureRootSyncExitCleanupRegistered, getRootSyncHeldLocks, readRootSidecarSnapshotSync, } from "./file-lock-sync-root-held.js";
+export function acquireFileLockSyncWithRoot(targetPath, inputOptions, lockRoot) {
+    // The public dispatcher already read lockRoot exactly once. Validate and
+    // snapshot that genuine Root before any remaining option or retry getter can
+    // mutate its defaults or retained policy inputs.
+    const authority = captureFileLockSyncRootAuthority(lockRoot);
+    const options = captureRootSyncAcquireOptions(inputOptions);
+    ensureRootSyncExitCleanupRegistered();
+    assertNoWindowsPathAlias(targetPath);
+    if (options.lockPath !== undefined)
+        assertNoWindowsPathAlias(options.lockPath);
+    const resolvedTargetPath = path.resolve(targetPath);
+    const normalizedTargetPath = normalizeFileLockSyncTargetWithRoot(authority, resolvedTargetPath);
+    const requestedLockPath = path.resolve(options.lockPath ?? `${normalizedTargetPath}.lock`);
+    const lockRootPath = admitFileLockSyncRootPath(authority, requestedLockPath);
+    // A followed final alias and its admitted canonical spelling name the same
+    // sidecar. Derive their arbitration guard from that shared admitted path,
+    // then independently admit the derived mutation target under Root policy.
+    const reclaimRootPath = admitFileLockSyncRootPath(authority, `${lockRootPath.path}.reclaim`);
+    const guardedPaths = Object.freeze([lockRootPath, reclaimRootPath]);
+    const lockPath = lockRootPath.path;
+    const heldLocks = getRootSyncHeldLocks();
+    const currentTargetHolder = () => heldLocks.get(normalizedTargetPath) ??
+        foreignSyncHeldLock("root", normalizedTargetPath);
+    const arbitration = Object.freeze({
+        authority,
+        heldLocks,
+        lockRootPath,
+        normalizedTargetPath,
+        reentrantOwner: options.reentrantOwner,
+    });
+    if (heldLocks.has(normalizedTargetPath) && !foreignSyncHeldLock("root", normalizedTargetPath)) {
+        assertFileLockSyncRootPathsCurrent(guardedPaths);
+        const initiallyReusable = tryReuseCurrentRootSyncHeldLock(arbitration);
+        if (initiallyReusable)
+            return initiallyReusable;
+    }
+    const acquisition = new SyncLockAcquisition(lockPath, normalizedTargetPath, options.retry, options.timeoutMs);
+    let ownedReclaimGuard;
+    let reclaimCleanupAttempted = false;
+    const reuseCurrentHeld = () => ownedReclaimGuard ? undefined : tryReuseCurrentRootSyncHeldLock(arbitration);
+    const releaseReclaimGuard = () => {
+        const receipt = ownedReclaimGuard;
+        if (!receipt)
+            return;
+        reclaimCleanupAttempted = true;
+        if (!removeFileLockSyncRootDirectory(reclaimRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "owned sidecar reclaim guard changed before release");
+        }
+        ownedReclaimGuard = undefined;
+        reclaimCleanupAttempted = false;
+    };
+    const assertOwnedReclaimGuardCurrent = () => {
+        const receipt = ownedReclaimGuard;
+        if (!receipt || !fileLockSyncRootDirectoryReceiptStillCurrent(reclaimRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "owned sidecar reclaim guard changed during acquisition");
+        }
+    };
+    try {
+        while (true) {
+            acquisition.reserve();
+            acquisition.assert();
+            assertFileLockSyncRootPathsCurrent(guardedPaths);
+            acquisition.assert();
+            if (ownedReclaimGuard)
+                assertOwnedReclaimGuardCurrent();
+            if (!ownedReclaimGuard && fileLockSyncRootGuardExists(reclaimRootPath)) {
+                acquisition.waitForRetry();
+                continue;
+            }
+            if (currentTargetHolder() !== undefined) {
+                const reused = reuseCurrentHeld();
+                if (reused)
+                    return reused;
+            }
+            const payload = Reflect.apply(options.payload, options.optionsReceiver, []);
+            acquisition.assert();
+            const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
+            acquisition.assert();
+            if (ownedReclaimGuard)
+                assertOwnedReclaimGuardCurrent();
+            if (currentTargetHolder() !== undefined) {
+                const reused = reuseCurrentHeld();
+                if (reused)
+                    return reused;
+                acquisition.waitForRetry();
+                continue;
+            }
+            let fd;
+            let rootReceipt;
+            let unpublishedTimer;
+            let lockFileCreateOpenFailure;
+            try {
+                const created = createFileLockSyncRootFile(lockRootPath, {
+                    assertBeforeOpen: () => {
+                        acquisition.assert();
+                        if (ownedReclaimGuard)
+                            assertOwnedReclaimGuardCurrent();
+                        if (currentTargetHolder() !== undefined)
+                            throw new FileLockSyncRootArbitrationCollision();
+                    },
+                    onOpenFailure: (error) => {
+                        lockFileCreateOpenFailure = { error };
+                    },
+                });
+                fd = created.fd;
+                rootReceipt = created.receipt;
+                fs.writeFileSync(fd, raw, "utf8");
+                fs.fsyncSync(fd);
+                const snapshot = {
+                    raw,
+                    payload,
+                    ownershipToken,
+                };
+                if (ownedReclaimGuard)
+                    releaseReclaimGuard();
+                rootReceipt = refreshFileLockSyncRootFileReceipt(lockRootPath, rootReceipt);
+                const createdHeld = {
+                    fd,
+                    lockPath,
+                    normalizedTargetPath,
+                    parsePayload: options.parsePayload,
+                    refCount: 1,
+                    reentrantOwner: options.reentrantOwner,
+                    releaseState: "active",
+                    revision: 0,
+                    rootAuthority: authority,
+                    rootPath: lockRootPath,
+                    rootReceipt,
+                    snapshot,
+                };
+                const returnedHandle = createRootSyncHeldLockHandle(createdHeld);
+                acquisition.monitor(createdHeld, returnedHandle, options.onCompromised, options.compromiseCheckIntervalMs, options.optionsReceiver, (timer) => { unpublishedTimer = timer; });
+                if (currentTargetHolder() !== undefined) {
+                    throw new FileLockSyncRootArbitrationCollision();
+                }
+                acquisition.assert();
+                heldLocks.set(normalizedTargetPath, createdHeld);
+                fd = undefined;
+                unpublishedTimer = undefined;
+                return returnedHandle;
+            }
+            catch (error) {
+                if (fd !== undefined && rootReceipt) {
+                    const cleanupFd = fd;
+                    const cleanupReceipt = rootReceipt;
+                    const cleanupTimer = unpublishedTimer;
+                    fd = undefined;
+                    rootReceipt = undefined;
+                    unpublishedTimer = undefined;
+                    try {
+                        cleanupCreatedRootSyncLock(lockRootPath, cleanupFd, cleanupReceipt, cleanupTimer);
+                    }
+                    catch (cleanupError) {
+                        throw createSuppressedError(error, cleanupError, "file lock acquisition and Root cleanup both failed");
+                    }
+                }
+                if (error instanceof FileLockSyncRootArbitrationCollision) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                const fromLockFileOpen = lockFileCreateOpenFailure !== undefined &&
+                    lockFileCreateOpenFailure.error === error;
+                if (fromLockFileOpen && acquisition.retryDenial(error))
+                    continue;
+                if (!fromLockFileOpen || error.code !== "EEXIST")
+                    throw error;
+                if (ownedReclaimGuard) {
+                    releaseReclaimGuard();
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                if (currentTargetHolder() !== undefined) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                let lockFileOpenDenied = false;
+                let current;
+                try {
+                    current = readRootSidecarSnapshotSync(lockRootPath, options.parsePayload, (openError) => {
+                        lockFileOpenDenied = isTransientLockFileDenial(openError, lockPath);
+                    });
+                }
+                catch (readError) {
+                    if (lockFileOpenDenied && acquisition.retryDenial(readError))
+                        continue;
+                    throw readError;
+                }
+                if (currentTargetHolder() !== undefined) {
+                    const reused = reuseCurrentHeld();
+                    if (reused)
+                        return reused;
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                acquisition.assert();
+                if (!current) {
+                    acquisition.waitForRetry();
+                    continue;
+                }
+                const snapshot = current.snapshot;
+                const nowMs = Date.now();
+                let reclaim;
+                if (options.shouldReclaim) {
+                    reclaim = Reflect.apply(options.shouldReclaim, options.optionsReceiver, [{
+                            lockPath,
+                            normalizedTargetPath,
+                            payload: snapshot.payload,
+                            staleMs: options.staleMs,
+                            nowMs,
+                            heldByThisProcess: false,
+                        }]);
+                    assertSynchronousCallbackResult(reclaim, "shouldReclaim");
+                    acquisition.assert();
+                    if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
+                        throw new FsSafeError("path-mismatch", "sidecar changed during reclaim policy callback");
+                    }
+                }
+                else {
+                    reclaim = defaultSyncShouldReclaim(snapshot, options.staleMs, nowMs);
+                }
+                if (reclaim) {
+                    if (options.staleRecovery === "remove-if-unchanged" &&
+                        snapshot.raw !== undefined &&
+                        options.shouldRemoveStaleLock) {
+                        const guard = createFileLockSyncRootDirectory(reclaimRootPath);
+                        if (!guard) {
+                            acquisition.waitForRetry();
+                            continue;
+                        }
+                        ownedReclaimGuard = guard;
+                        reclaimCleanupAttempted = false;
+                        const approved = Reflect.apply(options.shouldRemoveStaleLock, options.optionsReceiver, [{
+                                lockPath,
+                                normalizedTargetPath,
+                                raw: snapshot.raw,
+                                payload: snapshot.payload,
+                            }]);
+                        assertSynchronousCallbackResult(approved, "shouldRemoveStaleLock");
+                        acquisition.assert();
+                        assertOwnedReclaimGuardCurrent();
+                        if (approved) {
+                            const removed = removeFileLockSyncRootFile(lockRootPath, current.receipt, snapshot, () => {
+                                acquisition.assert();
+                                assertOwnedReclaimGuardCurrent();
+                                if (currentTargetHolder() !== undefined)
+                                    throw new FileLockSyncRootArbitrationCollision();
+                            });
+                            if (!removed) {
+                                throw new FsSafeError("path-mismatch", "stale sidecar changed before removal");
+                            }
+                            continue;
+                        }
+                        if (!fileLockSyncRootSnapshotStillCurrent(lockRootPath, current)) {
+                            throw new FsSafeError("path-mismatch", "sidecar changed during stale-removal policy callback");
+                        }
+                        releaseReclaimGuard();
+                    }
+                    throw sidecarLockStale(lockPath, normalizedTargetPath);
+                }
+                acquisition.waitForRetry();
+            }
+        }
+    }
+    catch (error) {
+        if (ownedReclaimGuard && !reclaimCleanupAttempted) {
+            try {
+                releaseReclaimGuard();
+            }
+            catch (cleanupError) {
+                throw createSuppressedError(error, cleanupError, "file lock acquisition and reclaim cleanup both failed");
+            }
+        }
+        throw error;
+    }
+    finally {
+        acquisition.release();
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-root-arbitration.d.ts

@@ -0,0 +1,17 @@
+import { FsSafeError } from "./errors.js";
+import type { FileLockSyncHandle } from "./file-lock-sync.js";
+import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
+import type { FileLockSyncRootFileReceipt } from "./file-lock-sync-root-io.js";
+import { type RootSyncHeldLock } from "./file-lock-sync-root-held.js";
+export declare class FileLockSyncRootArbitrationCollision extends FsSafeError {
+    constructor();
+}
+export type FileLockSyncRootArbitration = Readonly<{
+    authority: FileLockSyncRootAuthority;
+    heldLocks: Map<string, RootSyncHeldLock>;
+    lockRootPath: FileLockSyncRootPath;
+    normalizedTargetPath: string;
+    reentrantOwner?: string;
+}>;
+export declare function tryReuseCurrentRootSyncHeldLock(arbitration: FileLockSyncRootArbitration): FileLockSyncHandle | undefined;
+export declare function cleanupCreatedRootSyncLock(lockRootPath: FileLockSyncRootPath, fd: number, receipt: FileLockSyncRootFileReceipt, timer?: NodeJS.Timeout): void;

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-root-arbitration.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import { foreignSyncHeldLock } from "./file-lock-sync-admission.js";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import {} from "./file-lock-sync-root.js";
+import { removeFileLockSyncRootFile } from "./file-lock-sync-root-mutation.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { createRootSyncHeldLockHandle, verifyRootSyncHeldLock, } from "./file-lock-sync-root-held.js";
+export class FileLockSyncRootArbitrationCollision extends FsSafeError {
+    constructor() {
+        super("path-mismatch", "file lock arbitration changed during local creation");
+    }
+}
+function sameRootLockPath(left, right) {
+    return left.relativePath === right.relativePath && path.relative(left.path, right.path) === "";
+}
+export function tryReuseCurrentRootSyncHeldLock(arbitration) {
+    const held = arbitration.heldLocks.get(arbitration.normalizedTargetPath);
+    const reusable = held && !foreignSyncHeldLock("root", arbitration.normalizedTargetPath) &&
+        arbitration.reentrantOwner !== undefined &&
+        held.reentrantOwner !== undefined &&
+        arbitration.reentrantOwner === held.reentrantOwner &&
+        arbitration.authority.adapter === held.rootAuthority.adapter &&
+        sameRootLockPath(arbitration.lockRootPath, held.rootPath) &&
+        held.releaseState !== "released";
+    if (!reusable)
+        return undefined;
+    if (!verifyRootSyncHeldLock(held)) {
+        throw new FsSafeError("path-mismatch", "held sidecar lock changed before reentrant reuse");
+    }
+    // Verification can invoke a custom parser. Re-fetch the exact entry before
+    // granting a reference, while retaining supported releasing/exit states.
+    if (arbitration.heldLocks.get(arbitration.normalizedTargetPath) !== held ||
+        held.releaseState === "released" || foreignSyncHeldLock("root", arbitration.normalizedTargetPath)) {
+        throw new FsSafeError("path-mismatch", "held sidecar lock changed during reentrant reuse");
+    }
+    held.refCount += 1;
+    held.revision += 1;
+    return createRootSyncHeldLockHandle(held);
+}
+export function cleanupCreatedRootSyncLock(lockRootPath, fd, receipt, timer) {
+    let timerCleanupFailed = false;
+    let timerCleanupError;
+    try {
+        if (timer)
+            clearInterval(timer);
+    }
+    catch (error) {
+        timerCleanupFailed = true;
+        timerCleanupError = error;
+    }
+    try {
+        fs.closeSync(fd);
+        if (!removeFileLockSyncRootFile(lockRootPath, receipt)) {
+            throw new FsSafeError("path-mismatch", "created sidecar lock changed before cleanup");
+        }
+    }
+    catch (fileCleanupError) {
+        if (timerCleanupFailed) {
+            throw createSuppressedError(timerCleanupError, fileCleanupError, "unpublished lock timer and file cleanup both failed");
+        }
+        throw fileCleanupError;
+    }
+    if (timerCleanupFailed)
+        throw timerCleanupError;
+}

package/node_modules/@openclaw/fs-safe/dist/file-lock-sync-root-held.d.ts

@@ -0,0 +1,32 @@
+import type { FileLockSyncHandle } from "./file-lock-sync.js";
+import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import { type FileLockSyncRootAuthority, type FileLockSyncRootPath } from "./file-lock-sync-root.js";
+import { type FileLockSyncRootFileReceipt, type FileLockSyncRootSnapshot } from "./file-lock-sync-root-io.js";
+type RootSyncHeldLockReleaseState = "active" | "releasing" | "exit-cleaning" | "released";
+type RootSyncHeldLockHandleDisposition = {
+    held: RootSyncHeldLock;
+    released: boolean;
+};
+export type RootSyncHeldLock = {
+    deferredExitReleases?: Set<RootSyncHeldLockHandleDisposition>;
+    fd: number | undefined;
+    lockPath: string;
+    normalizedTargetPath: string;
+    parsePayload?: (raw: string) => unknown;
+    refCount: number;
+    reentrantOwner?: string;
+    releaseState: RootSyncHeldLockReleaseState;
+    revision: number;
+    rootAuthority: FileLockSyncRootAuthority;
+    rootPath: FileLockSyncRootPath;
+    rootReceipt: FileLockSyncRootFileReceipt;
+    snapshot: SidecarLockSnapshot;
+    timer?: NodeJS.Timeout;
+};
+export declare function readRootSidecarSnapshotSync(rootPath: FileLockSyncRootPath, parsePayload?: (raw: string) => unknown, onOpenFailure?: (error: unknown) => void, expectedReceipt?: FileLockSyncRootFileReceipt): FileLockSyncRootSnapshot | null;
+export declare function getRootSyncHeldLocks(): Map<string, RootSyncHeldLock>;
+export declare function ensureRootSyncExitCleanupRegistered(): void;
+export declare function verifyRootSyncHeldLock(held: RootSyncHeldLock): boolean;
+export declare function createRootSyncHeldLockHandle(held: RootSyncHeldLock): FileLockSyncHandle;
+export declare function withSyncHeldLockHandle<T>(lock: FileLockSyncHandle, fn: () => T): T;
+export {};