@openclaw/openshell-sandbox 2026.9.2 → 2026.9.3

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

@@ -0,0 +1,42 @@
+import { sidecarLockSnapshotStillPresent, } from "./sidecar-lock-reclaim.js";
+export function createSidecarLockHandle(params) {
+    let released = false;
+    let releasePromise;
+    let releaseStarted = false;
+    const release = async () => {
+        if (released)
+            return;
+        if (!releasePromise) {
+            const retry = releaseStarted;
+            releaseStarted = true;
+            releasePromise = (async () => {
+                await params.release({ retry });
+                released = true;
+            })();
+        }
+        try {
+            await releasePromise;
+        }
+        finally {
+            releasePromise = undefined;
+        }
+    };
+    return {
+        lockPath: params.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+        verifyStillHeld: params.verifyStillHeld,
+        release,
+        [Symbol.asyncDispose]: release,
+    };
+}
+export function createHeldSidecarLockHandle(params) {
+    return createSidecarLockHandle({
+        lockPath: params.held.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+        verifyStillHeld: async () => await sidecarLockSnapshotStillPresent(params.held.lockPath, params.held.snapshot, {
+            lockRoot: params.held.lockRoot,
+            parsePayload: params.held.parsePayload,
+        }),
+        release: (options) => params.release(options),
+    });
+}

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

@@ -0,0 +1,14 @@
+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 computeSidecarLockDelayMs(retry: SidecarLockRetryOptions, attempt: number): number;
+export declare const maxTransientLockDenials = 8;
+export declare function isTransientLockFileDenial(error: unknown, lockPath: string): boolean;
+export declare function sidecarLockPayloadCreatedAtMs(payload: unknown): number | null;
+export declare function defaultSidecarLockShouldReclaim(params: {
+    lockPath: string;
+    payload: unknown;
+    staleMs: number;
+    nowMs: number;
+}): Promise<boolean>;
+//# sourceMappingURL=sidecar-lock-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-policy.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAQvE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAkBpF;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGhF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjG;AASD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnB"}

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

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+function assertFiniteNonNegative(value, label) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${label} must be a finite non-negative number`);
+    }
+}
+export function validateSidecarLockRetryOptions(retry) {
+    if (retry.retries !== undefined && (!Number.isSafeInteger(retry.retries) || retry.retries < 0)) {
+        throw new RangeError("lock retry.retries must be a non-negative safe integer");
+    }
+    if (retry.factor !== undefined)
+        assertFiniteNonNegative(retry.factor, "lock retry.factor");
+    if (retry.minTimeout !== undefined) {
+        assertFiniteNonNegative(retry.minTimeout, "lock retry.minTimeout");
+    }
+    if (retry.maxTimeout !== undefined) {
+        assertFiniteNonNegative(retry.maxTimeout, "lock retry.maxTimeout");
+    }
+    if (retry.minTimeout !== undefined &&
+        retry.maxTimeout !== undefined &&
+        retry.minTimeout > retry.maxTimeout) {
+        throw new RangeError("lock retry.minTimeout must not exceed retry.maxTimeout");
+    }
+}
+export function validateSidecarLockTimeoutMs(timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs === Number.POSITIVE_INFINITY)
+        return;
+    assertFiniteNonNegative(timeoutMs, "lock timeoutMs");
+}
+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));
+    const jitter = retry.randomize ? 1 + Math.random() : 1;
+    return Math.min(maxTimeout, Math.round(base * jitter));
+}
+// 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
+// holder's snapshot. The next attempt succeeds, so this is contention rather
+// than a permission failure. The error must name the lock file itself: the
+// exclusive-create helper opens the parent directory first, and a denial from
+// that setup step carries no teardown evidence and has to reach the caller.
+export const maxTransientLockDenials = 8;
+export function isTransientLockFileDenial(error, lockPath) {
+    const denial = error;
+    return process.platform === "win32" && denial?.code === "EPERM" && denial.path === lockPath;
+}
+export function sidecarLockPayloadCreatedAtMs(payload) {
+    const createdAt = payload &&
+        typeof payload === "object" &&
+        "createdAt" in payload &&
+        typeof payload.createdAt === "string"
+        ? payload.createdAt
+        : "";
+    const createdAtMs = Date.parse(createdAt);
+    return Number.isFinite(createdAtMs) ? createdAtMs : null;
+}
+export async function defaultSidecarLockShouldReclaim(params) {
+    const createdAtMs = sidecarLockPayloadCreatedAtMs(params.payload);
+    if (createdAtMs !== null)
+        return params.nowMs - createdAtMs > params.staleMs;
+    try {
+        return params.nowMs - (await fs.stat(params.lockPath)).mtimeMs > params.staleMs;
+    }
+    catch {
+        return true;
+    }
+}

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

@@ -0,0 +1,63 @@
+import { type Stats } from "node:fs";
+import type { Root } from "./root-impl.js";
+export type SidecarLockStaleSnapshot = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    raw: string;
+    payload: unknown;
+};
+export type SidecarLockSnapshot = {
+    raw?: string;
+    payload: unknown;
+    stat?: Stats;
+    ownershipToken?: string;
+};
+type SidecarLockRawSnapshot = Omit<SidecarLockSnapshot, "payload"> & {
+    raw: string;
+};
+export declare function parseSidecarLockSnapshot(snapshot: SidecarLockRawSnapshot | null, parser?: (raw: string) => unknown): SidecarLockSnapshot | null;
+export declare function readSidecarLockOwnershipToken(raw: string): string | undefined;
+export declare function serializeSidecarLockPayload(payload: Record<string, unknown>): {
+    raw: string;
+    ownershipToken: string;
+};
+export declare function relativeSidecarLockPath(lockRoot: Root, lockPath: string): string;
+export declare function parseSidecarLockPayload(raw: string, parser?: (raw: string) => unknown): unknown;
+export declare function readSidecarLockSnapshot(lockPath: string, options?: Parameters<typeof readSidecarLockRawSnapshot>[1] & {
+    parsePayload?: (raw: string) => unknown;
+}): Promise<SidecarLockSnapshot | null>;
+export declare function readSidecarLockRawSnapshot(lockPath: string, options?: {
+    lockRoot?: Root;
+    rejectNonFile?: boolean;
+    allowDescriptorIdentityDrift?: boolean;
+    discardObservation?: "unlinked" | "changed";
+    onOpenFailure?: (error: unknown) => void;
+}): Promise<SidecarLockRawSnapshot | null>;
+export declare function readSidecarLockSnapshotSync(lockPath: string, parsePayload?: (raw: string) => unknown, options?: Parameters<typeof readSidecarLockRawSnapshotSync>[1]): SidecarLockSnapshot | null;
+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 removeSidecarLockIfUnchanged(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
+    lockRoot?: Root;
+    parsePayload?: (raw: string) => unknown;
+}): Promise<boolean>;
+export declare function sidecarLockSnapshotStillPresent(lockPath: string, observed: SidecarLockSnapshot | null, options?: {
+    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 declare function removeStaleSidecarLockIfAllowed(params: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    snapshot: SidecarLockSnapshot;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
+    lockRoot?: Root;
+    parsePayload?: (raw: string) => unknown;
+}): Promise<"removed" | "changed" | "not-approved">;
+export {};
+//# sourceMappingURL=sidecar-lock-reclaim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-reclaim.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-reclaim.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,305 @@
+import { randomBytes } from "node:crypto";
+import fsSync, {} from "node:fs";
+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 { resolveReadOpenFlags } from "./read-open-flags.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
+import { getFsSafeTestHooks } from "./test-hooks.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;
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX = "\t".repeat(8);
+const SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN = new RegExp(`\\n(${SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX}[ \\t]{${SIDECAR_LOCK_OWNERSHIP_TOKEN_BITS}})\\n$`);
+export function parseSidecarLockSnapshot(snapshot, parser) {
+    return snapshot && { ...snapshot, payload: parseSidecarLockPayload(snapshot.raw, parser) };
+}
+function createSidecarLockOwnershipToken() {
+    let token = SIDECAR_LOCK_OWNERSHIP_TOKEN_PREFIX;
+    for (const byte of randomBytes(SIDECAR_LOCK_OWNERSHIP_TOKEN_BYTES)) {
+        for (let bit = 7; bit >= 0; bit -= 1) {
+            token += byte & (1 << bit) ? "\t" : " ";
+        }
+    }
+    return token;
+}
+export function readSidecarLockOwnershipToken(raw) {
+    return SIDECAR_LOCK_OWNERSHIP_TOKEN_PATTERN.exec(raw)?.[1];
+}
+export function serializeSidecarLockPayload(payload) {
+    const ownershipToken = createSidecarLockOwnershipToken();
+    const raw = `${JSON.stringify(payload, null, 2)}\n${ownershipToken}\n`;
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_LOCK_PAYLOAD_BYTES) {
+        throw new FsSafeError("too-large", `sidecar lock payload exceeds limit of ${MAX_LOCK_PAYLOAD_BYTES} bytes (got ${bytes})`);
+    }
+    return { raw, ownershipToken };
+}
+export function relativeSidecarLockPath(lockRoot, lockPath) {
+    const resolved = path.resolve(lockPath);
+    const lexicalRelative = path.relative(lockRoot.rootDir, resolved);
+    const relative = lexicalRelative !== ".." &&
+        !lexicalRelative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(lexicalRelative)
+        ? lexicalRelative
+        : path.relative(lockRoot.rootReal, resolved);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new FsSafeError("outside-workspace", "sidecar lock path is outside lockRoot");
+    }
+    return relative.split(path.sep).join(path.posix.sep);
+}
+export function parseSidecarLockPayload(raw, parser) {
+    if (parser) {
+        return parser(raw);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function missingSnapshotPath(error) {
+    if (error.code === "ENOENT")
+        return null;
+    throw error;
+}
+export async function readSidecarLockSnapshot(lockPath, options = {}) {
+    return parseSidecarLockSnapshot(await readSidecarLockRawSnapshot(lockPath, options), options.parsePayload);
+}
+export async function readSidecarLockRawSnapshot(lockPath, options = {}) {
+    let handle;
+    try {
+        if (options.lockRoot) {
+            const lockRoot = options.lockRoot;
+            const relative = relativeSidecarLockPath(lockRoot, lockPath);
+            const opened = await openSidecarRoot(lockRoot, relative, options.discardObservation, options.onOpenFailure);
+            if (!opened)
+                return null;
+            try {
+                const raw = (await readFileHandleBounded(opened.handle, MAX_LOCK_PAYLOAD_BYTES)).toString("utf8");
+                return {
+                    raw,
+                    stat: opened.stat,
+                };
+            }
+            finally {
+                await opened.handle.close().catch(() => undefined);
+            }
+        }
+        const before = await fs.lstat(lockPath).catch(missingSnapshotPath);
+        if (!before)
+            return null;
+        if (!before.isFile() || before.isSymbolicLink()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        await getFsSafeTestHooks()?.beforeSidecarLockSnapshotOpen?.(lockPath);
+        const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+            ? fsSync.constants.O_NOFOLLOW
+            : 0;
+        try {
+            handle = await fs.open(lockPath, fsSync.constants.O_RDONLY |
+                noFollow |
+                (typeof fsSync.constants.O_NONBLOCK === "number" ? fsSync.constants.O_NONBLOCK : 0));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            if (options.rejectNonFile && error.code === "ELOOP") {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`, {
+                    cause: error,
+                });
+            }
+            options.onOpenFailure?.(error);
+            throw error;
+        }
+        const opened = await handle.stat();
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        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);
+        if (!after || !after.isFile() || !sameFileIdentity(before, after))
+            return null;
+        return { raw, stat: after };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function lstatSidecarLockSync(lockPath) {
+    try {
+        return fsSync.lstatSync(lockPath);
+    }
+    catch (error) {
+        return missingSnapshotPath(error);
+    }
+}
+export function readSidecarLockSnapshotSync(lockPath, parsePayload, options = {}) {
+    return parseSidecarLockSnapshot(readSidecarLockRawSnapshotSync(lockPath, options), parsePayload);
+}
+export function readSidecarLockRawSnapshotSync(lockPath, options = {}) {
+    let fd;
+    try {
+        const before = lstatSidecarLockSync(lockPath);
+        if (!before)
+            return null;
+        if (!before.isFile() || before.isSymbolicLink()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        try {
+            fd = fsSync.openSync(lockPath, resolveReadOpenFlags());
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            options.onOpenFailure?.(error);
+            throw error;
+        }
+        const opened = fsSync.fstatSync(fd);
+        if (!opened.isFile()) {
+            if (options.rejectNonFile) {
+                throw new FsSafeError("not-file", `sidecar lock is not a regular file: ${lockPath}`);
+            }
+            return null;
+        }
+        const raw = readFileDescriptorBoundedSync(fd, MAX_LOCK_PAYLOAD_BYTES).toString("utf8");
+        const after = lstatSidecarLockSync(lockPath);
+        if (!after || !sameFileIdentity(before, opened) || !sameFileIdentity(opened, after))
+            return null;
+        return {
+            raw,
+            stat: after,
+            ownershipToken: readSidecarLockOwnershipToken(raw),
+        };
+    }
+    finally {
+        if (fd !== undefined)
+            fsSync.closeSync(fd);
+    }
+}
+export function removeSidecarLockIfUnchangedSync(lockPath, observed) {
+    const current = readSidecarLockSnapshotSync(lockPath);
+    if (!current || !sidecarLockSnapshotMatches(current, observed))
+        return false;
+    fsSync.rmSync(lockPath);
+    return true;
+}
+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);
+    }
+    if (observed.stat && current.stat && !sameFileIdentity(observed.stat, current.stat)) {
+        return false;
+    }
+    if (observed.raw !== undefined) {
+        return current.raw === observed.raw;
+    }
+    return observed.stat !== undefined && current.stat !== undefined;
+}
+export async function removeSidecarLockIfUnchanged(lockPath, observed, options = {}) {
+    const current = await readSidecarLockSnapshot(lockPath, {
+        ...options,
+        allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
+    });
+    if (!current || !observed || !sidecarLockSnapshotMatches(current, observed)) {
+        return false;
+    }
+    if (options.lockRoot) {
+        await options.lockRoot.remove(relativeSidecarLockPath(options.lockRoot, lockPath));
+    }
+    else {
+        await fs.rm(lockPath, { force: true });
+    }
+    return true;
+}
+export async function sidecarLockSnapshotStillPresent(lockPath, observed, options = {}) {
+    const current = await readSidecarLockSnapshot(lockPath, {
+        ...options,
+        allowDescriptorIdentityDrift: observed?.ownershipToken !== undefined,
+    });
+    return !!current && !!observed && sidecarLockSnapshotMatches(current, observed);
+}
+export async function sidecarReclaimGuardExists(pathname) {
+    try {
+        await fs.lstat(pathname);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function tryAcquireSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
+    try {
+        await fs.mkdir(reclaimGuardPath);
+        reclaimGuards.add(reclaimGuardPath);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function releaseSidecarReclaimGuard(reclaimGuards, reclaimGuardPath) {
+    await fs.rmdir(reclaimGuardPath);
+    reclaimGuards.delete(reclaimGuardPath);
+}
+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))) {
+        return "changed";
+    }
+    if (!(await params.shouldRemoveStaleLock({
+        lockPath: params.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+        raw: params.snapshot.raw,
+        payload: params.snapshot.payload,
+    }))) {
+        return "not-approved";
+    }
+    if (!(await sidecarLockSnapshotStillPresent(params.lockPath, params.snapshot, ioOptions))) {
+        return "changed";
+    }
+    try {
+        if (params.lockRoot) {
+            await params.lockRoot.remove(relativeSidecarLockPath(params.lockRoot, params.lockPath));
+        }
+        else {
+            await fs.rm(params.lockPath);
+        }
+        return "removed";
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return "changed";
+        }
+        throw err;
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { OpenResult, Root } from "./root-impl.js";
+export declare function openSidecarRoot(lockRoot: Root, relative: string, discardObservation?: "unlinked" | "changed", onOpenFailure?: (error: unknown) => void): Promise<OpenResult | null>;
+//# sourceMappingURL=sidecar-lock-root.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAuD5B"}

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

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveRootPath } from "./root-path.js";
+export async function openSidecarRoot(lockRoot, relative, discardObservation, onOpenFailure) {
+    const resolved = await lockRoot.resolve(relative);
+    const canonicalPath = async () => (await resolveRootPath({
+        absolutePath: resolved,
+        rootPath: lockRoot.rootReal,
+        rootCanonicalPath: lockRoot.rootReal,
+        boundaryLabel: "sidecar lock root",
+    })).canonicalPath;
+    const expectedRealPath = await canonicalPath();
+    if (expectedRealPath === lockRoot.rootReal)
+        throw new FsSafeError("not-file", "sidecar lock is a directory");
+    const parents = [];
+    let completeParents = true;
+    if (discardObservation) {
+        // Follow permitted in-root aliases first; receipts cover canonical ancestry.
+        for (let dir = path.dirname(expectedRealPath);; dir = path.dirname(dir)) {
+            try {
+                parents.push({ dir, stat: await inspectDirectoryIdentity(dir) });
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                completeParents = false;
+            }
+            if (dir === lockRoot.rootReal)
+                break;
+        }
+    }
+    const observation = fileObservation();
+    try {
+        const opened = await observation.run(() => lockRoot.open(relative));
+        if (opened.realPath !== expectedRealPath) {
+            await opened.handle.close().catch(() => undefined);
+            throw new FsSafeError("path-mismatch", "sidecar lock path changed during open");
+        }
+        return opened;
+    }
+    catch (error) {
+        const openFailed = observation.has(error, `open:${resolved}`);
+        if (openFailed)
+            onOpenFailure?.(error);
+        const missing = openFailed && error instanceof FsSafeError && error.code === "not-found";
+        if (missing && !discardObservation)
+            return null;
+        const discardable = observation.has(error, `unlinked:${resolved}`) ||
+            (discardObservation === "changed" && observation.has(error, `changed:${resolved}`));
+        if (!discardObservation || (!missing && (!completeParents || !discardable)))
+            throw error;
+        try {
+            try {
+                const current = await lockRoot.stat(relative);
+                if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
+                    throw error;
+            }
+            catch (probeError) {
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found"))
+                    throw probeError;
+            }
+            for (const { dir, stat } of parents)
+                await inspectDirectoryIdentity(dir, stat);
+            await lockRoot.resolve(relative);
+            if (await canonicalPath() === expectedRealPath)
+                return null;
+        }
+        catch {
+            // Keep the original failure when directory or confinement proof fails.
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,63 @@
+import type { Root } from "./root-impl.js";
+import type { SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
+export type SidecarLockRetryOptions = {
+    retries?: number;
+    factor?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    randomize?: boolean;
+};
+export type SidecarLockStaleRecovery = "fail-closed" | "remove-if-unchanged";
+export type SidecarLockCompromisedInfo = {
+    lockPath: string;
+    normalizedTargetPath: string;
+};
+export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
+    targetPath: string;
+    lockPath?: string;
+    staleMs: number;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
+    reentrantOwner?: string;
+    payload: () => TPayload | Promise<TPayload>;
+    shouldReclaim?: (params: {
+        lockPath: string;
+        normalizedTargetPath: string;
+        payload: unknown;
+        staleMs: number;
+        nowMs: number;
+        heldByThisProcess: boolean;
+    }) => boolean | Promise<boolean>;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
+    metadata?: Record<string, unknown>;
+    parsePayload?: (raw: string) => unknown;
+    lockRoot?: Root;
+    /**
+     * Keep the lock file when the process exits naturally. Default `false`:
+     * process-exit handlers release held locks. Set only for deliberately
+     * retained ownership records (for example, fail-closed build locks) whose
+     * liveness is governed by the caller's own stale policy.
+     */
+    retainOnExit?: boolean;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    compromiseCheckIntervalMs?: number;
+};
+export type SidecarLockHandle = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    verifyStillHeld: () => Promise<boolean>;
+    release: () => Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type SidecarLockHeldEntry = {
+    normalizedTargetPath: string;
+    lockPath: string;
+    acquiredAt: number;
+    metadata: Record<string, unknown>;
+    forceRelease: () => Promise<boolean>;
+};
+export type WithSidecarLockOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath"> & {
+    managerKey?: string;
+};
+//# sourceMappingURL=sidecar-lock-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-lock-types.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-types.ts"],"names":[],"mappings":"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"}

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

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