@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-context.js

@@ -0,0 +1,60 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const EMPTY_ANCESTRY = Object.freeze([]);
+const GLOBAL_CONTEXT_KEY = Symbol.for("fsSafe.sidecarLockAdmissionAsyncContext");
+function admissionContext() {
+    const shared = globalThis;
+    return shared[GLOBAL_CONTEXT_KEY] ??=
+        new AsyncLocalStorage();
+}
+/** Capture active ancestry now; later lifecycle changes cannot reclassify this call. */
+export function captureSidecarAdmissionAncestry() {
+    const current = admissionContext().getStore();
+    if (!current)
+        return EMPTY_ANCESTRY;
+    const active = current.ancestry.filter((entry) => entry.active);
+    if (current.active)
+        active.push(current);
+    return active.length === 0 ? EMPTY_ANCESTRY : active;
+}
+export function ancestryHasSidecarAdmission(ancestry, admissions, normalizedTargetPath) {
+    return ancestry.some((entry) => entry.admissions === admissions && entry.normalizedTargetPath === normalizedTargetPath);
+}
+function createSidecarAdmissionScope(ancestry, admissions, normalizedTargetPath, token) {
+    return { active: false, admissions, ancestry, normalizedTargetPath, started: false, token };
+}
+function activateSidecarAdmissionScope(scope) {
+    if (scope.started)
+        throw new Error("sidecar admission scope cannot be reactivated");
+    scope.started = true;
+    scope.active = true;
+}
+function deactivateSidecarAdmissionScope(scope) {
+    if (scope)
+        scope.active = false;
+}
+function runInSidecarAdmissionScope(scope, callback) {
+    return scope?.active ? admissionContext().run(scope, callback) : callback();
+}
+export function createSidecarAdmissionController(ancestry, admissions, normalizedTargetPath) {
+    let scope;
+    const hasToken = () => scope !== undefined && admissions.get(normalizedTargetPath) === scope.token;
+    return {
+        get owns() { return scope !== undefined; },
+        hasToken,
+        release() {
+            deactivateSidecarAdmissionScope(scope);
+            if (hasToken())
+                admissions.delete(normalizedTargetPath);
+            scope = undefined;
+        },
+        reserve() {
+            const token = {};
+            scope = createSidecarAdmissionScope(ancestry, admissions, normalizedTargetPath, token);
+            admissions.set(normalizedTargetPath, token);
+            activateSidecarAdmissionScope(scope);
+        },
+        run(callback) {
+            return runInSidecarAdmissionScope(scope, callback);
+        },
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-parser.d.ts

@@ -0,0 +1,42 @@
+import type { Root } from "./root-impl.js";
+import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
+import { readSidecarLockRawSnapshot, type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+type SidecarAdmissionRunner = {
+    hasToken(): boolean;
+    run<T>(callback: () => T): T;
+};
+export declare function runSidecarAdmissionBoundary<T>(admission: SidecarAdmissionRunner, assertCurrent: () => void, callback: () => T): T;
+export declare function awaitSidecarAdmissionBoundary<T>(admission: SidecarAdmissionRunner, assertCurrent: () => void, callback: () => T | PromiseLike<T>): Promise<{
+    readonly value: Awaited<T>;
+}>;
+export type SidecarLockParserState = {
+    observed: boolean;
+    parser?: (raw: string) => unknown;
+};
+export declare function observeSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, accessor: () => ((raw: string) => unknown) | undefined, assertCurrent: () => void): void;
+export declare function scopedSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, assertCurrent: () => void): ((raw: string) => unknown) | undefined;
+/** Cleanup may outlive its reservation; never invoke user code after authority is lost. */
+export declare function conditionalSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, isCurrent: () => boolean): ((raw: string) => unknown) | undefined;
+export declare function parseSidecarLockSnapshotUnderAdmission(raw: Awaited<ReturnType<typeof readSidecarLockRawSnapshot>>, state: SidecarLockParserState, admission: SidecarAdmissionRunner, assertCurrent: () => void): SidecarLockSnapshot | null;
+export type HeldSidecarParserObservation = {
+    kind: "observed";
+} | {
+    kind: "holder-changed";
+} | {
+    kind: "read-error";
+    error: unknown;
+    transientDenial: boolean;
+};
+/** Emulate the historical EEXIST read/parser boundary without opening another sidecar. */
+export declare function observeHeldSidecarParser(params: {
+    admission: SidecarAdmissionRunner;
+    assertToken(): void;
+    currentHeld(): HeldSidecarLock | undefined;
+    held: HeldSidecarLock;
+    lockPath: string;
+    lockRoot?: Root;
+    parserState: SidecarLockParserState;
+    parserAccessor(): ((raw: string) => unknown) | undefined;
+    isTransientDenial(error: unknown): boolean;
+}): Promise<HeldSidecarParserObservation>;
+export {};

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-parser.js

@@ -0,0 +1,113 @@
+import { parseSidecarLockSnapshot, readSidecarLockRawSnapshot, } from "./sidecar-lock-reclaim.js";
+export function runSidecarAdmissionBoundary(admission, assertCurrent, callback) {
+    assertCurrent();
+    try {
+        return admission.run(callback);
+    }
+    finally {
+        assertCurrent();
+    }
+}
+export async function awaitSidecarAdmissionBoundary(admission, assertCurrent, callback) {
+    assertCurrent();
+    try {
+        return await admission.run(async () => {
+            const boxed = Object.create(null);
+            Object.defineProperty(boxed, "value", {
+                value: undefined, enumerable: true, writable: true,
+            });
+            boxed.value = await callback();
+            return boxed;
+        });
+    }
+    finally {
+        assertCurrent();
+    }
+}
+export function observeSidecarLockParser(state, admission, accessor, assertCurrent) {
+    assertCurrent();
+    if (state.observed)
+        return;
+    try {
+        state.parser = admission.run(accessor);
+    }
+    finally {
+        assertCurrent();
+    }
+    state.observed = true;
+}
+export function scopedSidecarLockParser(state, admission, assertCurrent) {
+    const parser = state.parser;
+    return parser && ((raw) => admission.run(() => {
+        assertCurrent();
+        try {
+            return Reflect.apply(parser, undefined, [raw]);
+        }
+        finally {
+            assertCurrent();
+        }
+    }));
+}
+/** Cleanup may outlive its reservation; never invoke user code after authority is lost. */
+export function conditionalSidecarLockParser(state, admission, isCurrent) {
+    const parser = state.parser;
+    return parser && ((raw) => {
+        if (!isCurrent())
+            return undefined;
+        return admission.run(() => {
+            if (!isCurrent())
+                return undefined;
+            let parsed;
+            try {
+                parsed = Reflect.apply(parser, undefined, [raw]);
+            }
+            catch (error) {
+                if (!isCurrent())
+                    return undefined;
+                throw error;
+            }
+            return isCurrent() ? parsed : undefined;
+        });
+    });
+}
+export function parseSidecarLockSnapshotUnderAdmission(raw, state, admission, assertCurrent) {
+    return parseSidecarLockSnapshot(raw, scopedSidecarLockParser(state, admission, assertCurrent));
+}
+/** Emulate the historical EEXIST read/parser boundary without opening another sidecar. */
+export async function observeHeldSidecarParser(params) {
+    const holderChanged = {};
+    const assertCurrentHolder = () => {
+        params.assertToken();
+        if (params.currentHeld() !== params.held || params.held.releasePromise) {
+            throw holderChanged;
+        }
+    };
+    let transientDenial = false;
+    let raw;
+    try {
+        raw = await params.admission.run(async () => await readSidecarLockRawSnapshot(params.lockPath, {
+            lockRoot: params.lockRoot,
+            rejectNonFile: true,
+            discardObservation: "changed",
+            onOpenFailure: (error) => { transientDenial = params.isTransientDenial(error); },
+        }));
+    }
+    catch (error) {
+        return { kind: "read-error", error, transientDenial };
+    }
+    params.assertToken();
+    if (params.currentHeld() !== params.held || params.held.releasePromise) {
+        return { kind: "holder-changed" };
+    }
+    try {
+        observeSidecarLockParser(params.parserState, params.admission, params.parserAccessor, assertCurrentHolder);
+        parseSidecarLockSnapshotUnderAdmission(raw, params.parserState, params.admission, assertCurrentHolder);
+        assertCurrentHolder();
+    }
+    catch (error) {
+        if (error === holderChanged)
+            return { kind: "holder-changed" };
+        throw error;
+    }
+    return { kind: "observed" };
+}

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

@@ -0,0 +1,31 @@
+import type { NativeFileHandle } from "./native-operations.js";
+import type { Root } from "./root-impl.js";
+import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+import type { SidecarLockHandle } from "./sidecar-lock-types.js";
+export type HeldSidecarLock = {
+    refCount: number;
+    reentrantOwner?: string;
+    handle: NativeFileHandle;
+    lockPath: string;
+    snapshot: SidecarLockSnapshot;
+    acquiredAt: number;
+    metadata: Record<string, unknown>;
+    releasePromise?: Promise<void>;
+    lockRoot?: Root;
+    retainOnExit?: boolean;
+    parsePayload?: (raw: string) => unknown;
+    compromiseTimer?: NodeJS.Timeout;
+};
+export type SidecarLockAcquisitionContext = {
+    held: Map<string, HeldSidecarLock>;
+    admissions: Map<string, object>;
+    reclaimGuards: Set<string>;
+    ensureExitCleanupRegistered(): {
+        armed: boolean;
+    };
+    armExitCleanup(lifecycle: {
+        armed: boolean;
+    }): void;
+    assertRetainOnExitSupported(retainOnExit: boolean | undefined): void;
+    handleForHeldLock(normalizedTargetPath: string, held: HeldSidecarLock): SidecarLockHandle;
+};

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

@@ -0,0 +1 @@
+export {};

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-handle.d.ts

@@ -1,6 +1,9 @@
 import type { Root } from "./root-impl.js";
 import { type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
+export declare function stopSidecarLockMonitoring(held: {
+    compromiseTimer?: NodeJS.Timeout;
+}): void;
 export declare function createSidecarLockHandle(params: {
     lockPath: string;
     normalizedTargetPath: string;
@@ -21,4 +24,3 @@ export declare function createHeldSidecarLockHandle(params: {
         retry?: boolean;
     }) => Promise<unknown>;
 }): SidecarLockHandle;
-//# sourceMappingURL=sidecar-lock-handle.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-handle.js

@@ -1,4 +1,10 @@
 import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
+export function stopSidecarLockMonitoring(held) {
+    const timer = held.compromiseTimer;
+    held.compromiseTimer = undefined;
+    if (timer)
+        clearInterval(timer);
+}
 export function createSidecarLockHandle(params) {
     let released = false;
     let releasePromise;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-policy.d.ts

@@ -1,7 +1,13 @@
 import type { SidecarLockRetryOptions } from "./sidecar-lock-types.js";
 export declare function validateSidecarLockRetryOptions(retry: SidecarLockRetryOptions): void;
 export declare function validateSidecarLockTimeoutMs(timeoutMs: number | undefined): void;
+export declare function validateSidecarLockStaleMs(staleMs: number | undefined): void;
+export declare function validateSidecarLockCompromiseCheckIntervalMs(intervalMs: number | undefined): void;
 export declare function computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
+export declare function sidecarLockTimeout(lockPath: string, normalizedTargetPath: string): Error;
+export declare function sidecarLockStale(lockPath: string, normalizedTargetPath: string): Error;
+/** Undefined means the deadline or retry count is exhausted. */
+export declare function sidecarLockRetryDelay(retry: SidecarLockRetryOptions, timeoutMs: number | undefined, elapsed: number, attempt: number): number | undefined;
 export declare const maxTransientLockDenials = 8;
 export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
 export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
@@ -11,4 +17,3 @@ export declare function defaultSidecarLockShouldReclaim(params: {
     staleMs: number;
     nowMs: number;
 }): Promise<boolean>;
-//# sourceMappingURL=sidecar-lock-policy.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-policy.js

@@ -1,4 +1,5 @@
-import fs from "node:fs/promises";
+import fsSync from "node:fs";
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
 function assertFiniteNonNegative(value, label) {
     if (!Number.isFinite(value) || value < 0) {
         throw new RangeError(`${label} must be a finite non-negative number`);
@@ -27,15 +28,56 @@ export function validateSidecarLockTimeoutMs(timeoutMs) {
         return;
     assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
 }
+export function validateSidecarLockStaleMs(staleMs) {
+    // The lower-level sidecar manager historically treats an omitted threshold
+    // as disabling age-based reclamation. Its public type requires a number, but
+    // retain that fail-closed runtime behavior for JavaScript callers and older
+    // consumers.
+    if (staleMs === undefined || staleMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(staleMs, "lock staleMs");
+}
+export function validateSidecarLockCompromiseCheckIntervalMs(intervalMs) {
+    if (intervalMs === undefined || intervalMs === 0)
+        return;
+    if (!Number.isFinite(intervalMs) || intervalMs < 1 || intervalMs > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`lock compromiseCheckIntervalMs must be 0 or a finite number between 1 and ${MAX_TIMER_DELAY_MS}`);
+    }
+}
 export function computeSidecarLockDelayMs(retry, attempt) {
     validateSidecarLockRetryOptions(retry);
     const minTimeout = retry.minTimeout ?? 50;
     const maxTimeout = retry.maxTimeout ?? 1000;
     const factor = retry.factor ?? 1;
-    const base = Math.min(maxTimeout, Math.max(minTimeout, minTimeout * factor ** attempt));
+    // Zero times an overflowing power is NaN, which makes Atomics.wait unbounded.
+    const scaled = minTimeout === 0 ? 0 : minTimeout * factor ** attempt;
+    const base = Math.min(maxTimeout, Math.max(minTimeout, scaled));
     const jitter = retry.randomize ? 1 + Math.random() : 1;
     return Math.min(maxTimeout, Math.round(base * jitter));
 }
+export function sidecarLockTimeout(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+        code: "file_lock_timeout",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
+export function sidecarLockStale(lockPath, normalizedTargetPath) {
+    return Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+        code: "file_lock_stale",
+        lockPath,
+        normalizedTargetPath,
+    });
+}
+/** Undefined means the deadline or retry count is exhausted. */
+export function sidecarLockRetryDelay(retry, timeoutMs, elapsed, attempt) {
+    if ((timeoutMs !== undefined && elapsed >= timeoutMs) ||
+        (retry.retries !== undefined && attempt >= retry.retries))
+        return undefined;
+    const remaining = timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY
+        ? Number.POSITIVE_INFINITY : Math.max(0, timeoutMs - elapsed);
+    return Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
+}
 // Windows denies access to a lock file while a just-unlinked directory entry
 // is still being torn down, so a contended acquire sees EPERM on a name that is
 // already gone -- both when creating it exclusively and when reading the
@@ -63,7 +105,7 @@ export async function defaultSidecarLockShouldReclaim(params) {
     if (createdAtMs !== null)
         return params.nowMs - createdAtMs > params.staleMs;
     try {
-        return params.nowMs - (await fs.stat(params.lockPath)).mtimeMs > params.staleMs;
+        return params.nowMs - fsSync.statSync(params.lockPath).mtimeMs > params.staleMs;
     }
     catch {
         return true;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-reclaim.d.ts

@@ -38,8 +38,8 @@ export declare function readSidecarLockRawSnapshotSync(lockPath: string, options
     rejectNonFile?: boolean;
     onOpenFailure?: (error: unknown) => void;
 }): SidecarLockRawSnapshot | null;
-export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot): boolean;
-export declare function sidecarLockSnapshotMatches(current: SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
+export declare function removeSidecarLockIfUnchangedSync(lockPath: string, observed: SidecarLockSnapshot, assertAuthorized?: () => void): boolean;
+export declare function sidecarLockSnapshotMatches(current: SidecarLockRawSnapshot | SidecarLockSnapshot, observed: SidecarLockSnapshot): boolean;
 export declare function removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
@@ -48,9 +48,12 @@ export declare function sidecarLockSnapshotStillPresent(lockPath: string, observ
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
 }): Promise<boolean>;
-export declare function sidecarReclaimGuardExists(pathname: string): Promise<boolean>;
-export declare function tryAcquireSidecarReclaimGuard(reclaimGuards: Set<string>, reclaimGuardPath: string): Promise<boolean>;
-export declare function releaseSidecarReclaimGuard(reclaimGuards: Set<string>, reclaimGuardPath: string): Promise<void>;
+export type SidecarReclaimGuard = {
+    assertHeld?(): Promise<void>;
+    release(): Promise<void>;
+};
+export declare function sidecarReclaimGuardExists(pathname: string, lockRoot?: Root): Promise<boolean>;
+export declare function tryAcquireSidecarReclaimGuard(reclaimGuards: Set<string>, pathname: string, lockRoot?: Root): Promise<SidecarReclaimGuard | undefined>;
 export declare function removeStaleSidecarLockIfAllowed(params: {
     lockPath: string;
     normalizedTargetPath: string;
@@ -58,6 +61,7 @@ export declare function removeStaleSidecarLockIfAllowed(params: {
     shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     lockRoot?: Root;
     parsePayload?: (raw: string) => unknown;
+    assertAuthorized?: () => void;
+    assertGuardHeld?: () => Promise<void>;
 }): Promise<"removed" | "changed" | "not-approved">;
 export {};
-//# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-reclaim.js

@@ -4,10 +4,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { sameFileIdentity, sameFileIdentityForCleanup } from "./file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { sidecarExclusiveCreate } from "./root-create-input.js";
 const MAX_LOCK_PAYLOAD_BYTES = 1024 * 1024;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES = 16;
 const SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS = SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES * 8;
@@ -70,6 +71,12 @@ function missingSnapshotPath(error) {
 export async function readSidecarLockSnapshot(lockPath, options = {}) {
     return parseSidecarLockSnapshot(await readSidecarLockRawSnapshot(lockPath, options), options.parsePayload);
 }
+async function readSidecarLockComparisonSnapshot(lockPath, options) {
+    const snapshot = await readSidecarLockRawSnapshot(lockPath, options);
+    const parsePayload = options?.parsePayload;
+    // Ownership uses raw bytes and identity, but custom parsers retain their effects.
+    return parsePayload ? parseSidecarLockSnapshot(snapshot, parsePayload) : snapshot;
+}
 export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
     let handle;
     try {
@@ -90,7 +97,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
                 await opened.handle.close().catch(() => undefined);
             }
         }
-        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let before;
+        try {
+            before = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            before = missingSnapshotPath(error);
+        }
         if (!before)
             return null;
         if (!before.isFile() || before.isSymbolicLink()) {
@@ -119,7 +132,7 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
             options.onOpenFailure?.(error);
             throw error;
         }
-        const opened = await handle.stat();
+        const opened = fsSync.fstatSync(handle.fd);
         if (!opened.isFile()) {
             if (options.rejectNonFile) {
                 throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
@@ -129,7 +142,13 @@ export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
         if (!options.allowDescriptorIdentityDrift && !sameFileIdentity(before, opened))
             return null;
         const raw = (await readFileHandleBounded(handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
-        const after = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        let after;
+        try {
+            after = fsSync.lstatSync(lockPath);
+        }
+        catch (error) {
+            after = missingSnapshotPath(error);
+        }
         if (!after || !after.isFile() || !sameFileIdentity(before, after))
             return null;
         return { raw, stat: after };
@@ -184,7 +203,6 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
         return {
             raw,
             stat: after,
-            ownershipToken: readSidecarLockOwnershipToken(raw),
         };
     }
     finally {
@@ -192,10 +210,13 @@ export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
             fsSync.closeSync(fd);
     }
 }
-export function removeSidecarLockIfUnchangedSync(lockPath, observed) {
-    const current = readSidecarLockSnapshotSync(lockPath);
+export function removeSidecarLockIfUnchangedSync(lockPath, observed, assertAuthorized) {
+    assertAuthorized?.();
+    const current = readSidecarLockRawSnapshotSync(lockPath);
+    assertAuthorized?.();
     if (!current || !sidecarLockSnapshotMatches(current, observed))
         return false;
+    assertAuthorized?.();
     fsSync.rmSync(lockPath);
     return true;
 }
@@ -203,12 +224,12 @@ export function sidecarLockSnapshotMatches(current, observed) {
     if (observed.ownershipToken !== undefined) {
         return (current.stat?.isFile() === true &&
             current.raw !== undefined &&
-            observed.raw !== undefined &&
-            readSidecarLockOwnershipToken(current.raw) === observed.ownershipToken &&
-            readSidecarLockOwnershipToken(observed.raw) === observed.ownershipToken &&
-            current.raw === observed.raw);
+            current.raw === observed.raw &&
+            readSidecarLockOwnershipToken(current.raw) === observed.ownershipToken);
     }
-    if (observed.stat && current.stat && !sameFileIdentity(observed.stat, current.stat)) {
+    if (observed.stat &&
+        current.stat &&
+        !sameFileIdentityForCleanup(observed.stat, current.stat)) {
         return false;
     }
     if (observed.raw !== undefined) {
@@ -217,7 +238,7 @@ export function sidecarLockSnapshotMatches(current, observed) {
     return observed.stat !== undefined && current.stat !== undefined;
 }
 export async function removeSidecarLockIfUnchanged(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, {
+    const current = await readSidecarLockComparisonSnapshot(lockPath, {
         ...options,
         allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
     });
@@ -233,47 +254,90 @@ export async function removeSidecarLockIfUnchanged(lockPath, observed, options =
     return true;
 }
 export async function sidecarLockSnapshotStillPresent(lockPath, observed, options = {}) {
-    const current = await readSidecarLockSnapshot(lockPath, {
+    const current = await readSidecarLockComparisonSnapshot(lockPath, {
         ...options,
         allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
     });
     return !!current && !!observed && sidecarLockSnapshotMatches(current, observed);
 }
-export async function sidecarReclaimGuardExists(pathname) {
+export async function sidecarReclaimGuardExists(pathname, lockRoot) {
     try {
-        await fs.lstat(pathname);
+        if (lockRoot)
+            await lockRoot.stat(relativeSidecarLockPath(lockRoot, pathname));
+        else
+            fsSync.lstatSync(pathname);
         return true;
     }
-    catch (err) {
-        if (err.code === "ENOENT") {
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT" || (lockRoot && code === "not-found"))
             return false;
-        }
-        throw err;
+        throw error;
     }
 }
-export async function tryAcquireSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
+export async function tryAcquireSidecarReclaimGuard(reclaimGuards, pathname, lockRoot) {
+    if (lockRoot) {
+        const relative = relativeSidecarLockPath(lockRoot, pathname);
+        const payload = { pid: process.pid, createdAt: new Date().toISOString() };
+        const snapshot = { ...serializeSidecarLockPayload(payload), payload };
+        try {
+            await lockRoot.create(relative, snapshot.raw, { ...sidecarExclusiveCreate, mkdir: false, mode: 0o600, durable: false });
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "already-exists")
+                return;
+            // A raw reclaimer can create its directory after our occupancy check.
+            if (error instanceof FsSafeError && error.code === "not-file") {
+                await sidecarReclaimGuardExists(pathname, lockRoot);
+                return;
+            }
+            throw error;
+        }
+        // This attempt owns only its minted token and exact bytes. Root guards
+        // never enter raw exit cleanup; interrupted/ambiguous operations preserve them.
+        let released = false;
+        const changed = () => new FsSafeError("path-mismatch", "sidecar reclaim guard ownership changed");
+        return {
+            async assertHeld() {
+                if (released || !await sidecarLockSnapshotStillPresent(pathname, snapshot, { lockRoot }))
+                    throw changed();
+            },
+            async release() {
+                if (released)
+                    return;
+                if (!await removeSidecarLockIfUnchanged(pathname, snapshot, { lockRoot }))
+                    throw changed();
+                released = true;
+            },
+        };
+    }
     try {
-        await fs.mkdir(reclaimGuardPath);
-        reclaimGuards.add(reclaimGuardPath);
-        return true;
+        await fs.mkdir(pathname);
     }
-    catch (err) {
-        if (err.code === "EEXIST") {
-            return false;
-        }
-        throw err;
+    catch (error) {
+        if (error?.code === "EEXIST")
+            return;
+        throw error;
     }
-}
-export async function releaseSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
-    await fs.rmdir(reclaimGuardPath);
-    reclaimGuards.delete(reclaimGuardPath);
+    reclaimGuards.add(pathname);
+    let released = false;
+    return { async release() {
+            if (released)
+                return;
+            await fs.rmdir(pathname);
+            reclaimGuards.delete(pathname);
+            released = true;
+        } };
 }
 export async function removeStaleSidecarLockIfAllowed(params) {
     if (!params.shouldRemoveStaleLock || params.snapshot.raw === undefined) {
         return "not-approved";
     }
     const ioOptions = { lockRoot: params.lockRoot, parsePayload: params.parsePayload };
-    if (!(await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot, ioOptions))) {
+    params.assertAuthorized?.();
+    const presentBeforeApproval = await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot, ioOptions);
+    params.assertAuthorized?.();
+    if (!presentBeforeApproval) {
         return "changed";
     }
     if (!(await params.shouldRemoveStaleLock({
@@ -284,12 +348,18 @@ export async function removeStaleSidecarLockIfAllowed(params) {
     }))) {
         return "not-approved";
     }
-    if (!(await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot, ioOptions))) {
+    params.assertAuthorized?.();
+    const presentBeforeRemoval = await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot, ioOptions);
+    params.assertAuthorized?.();
+    if (!presentBeforeRemoval) {
         return "changed";
     }
+    if (params.assertGuardHeld)
+        await params.assertGuardHeld();
+    params.assertAuthorized?.();
     try {
         if (params.lockRoot) {
-            await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath));
+            await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath), { assertBeforeMutation: params.assertAuthorized });
         }
         else {
             await fs.rm(params.lockPath);

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-registration.d.ts

@@ -0,0 +1,13 @@
+type CleanupRegistration = {
+    event: "exit" | "beforeExit";
+    registered: symbol;
+    registering: symbol;
+    handler: symbol;
+    retainAware?: symbol;
+    reentryError(): Error;
+};
+/** Preserve the legacy, first-registration-wins protocol across package copies. */
+export declare function ensureSidecarLockCleanupRegistered<T extends true | {
+    armed: boolean;
+}>(keys: CleanupRegistration, cleanup: () => void, marker: T): T;
+export {};