@openclaw/signal 2026.9.5 → 2026.9.6

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 {};

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

@@ -0,0 +1,47 @@
+/** Preserve the legacy, first-registration-wins protocol across package copies. */
+export function ensureSidecarLockCleanupRegistered(keys, cleanup, marker) {
+    const state = globalThis;
+    if (state[keys.registered])
+        return state[keys.registered];
+    // process.on emits newListener synchronously; reentry cannot wait for it.
+    if (state[keys.registering])
+        throw keys.reentryError();
+    const registration = {};
+    const commit = () => {
+        state[keys.handler] = cleanup;
+        if (keys.retainAware)
+            state[keys.retainAware] = true;
+        state[keys.registered] = marker;
+    };
+    state[keys.registering] = registration;
+    try {
+        process.on(keys.event, cleanup);
+        commit();
+        return marker;
+    }
+    catch (error) {
+        if (process.listeners(keys.event).includes(cleanup)) {
+            try {
+                process.off(keys.event, cleanup);
+            }
+            catch {
+                // Reconcile the marker with the actual listener below.
+            }
+        }
+        if (process.listeners(keys.event).includes(cleanup)) {
+            commit();
+        }
+        else {
+            if (state[keys.handler] === cleanup)
+                delete state[keys.handler];
+            // Only the before-exit lifecycle has an individually owned marker.
+            if (marker !== true && state[keys.registered] === marker)
+                delete state[keys.registered];
+        }
+        throw error;
+    }
+    finally {
+        if (state[keys.registering] === registration)
+            delete state[keys.registering];
+    }
+}

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

@@ -0,0 +1,2 @@
+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>;

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

@@ -0,0 +1,79 @@
+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 {
+            const probe = fileObservation();
+            try {
+                const current = await probe.run(() => lockRoot.stat(relative));
+                if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
+                    throw error;
+            }
+            catch (probeError) {
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found") &&
+                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`) &&
+                    !probe.has(probeError, `stat-leaf-changed:${expectedRealPath}`))
+                    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-stale-admission.d.ts

@@ -0,0 +1,38 @@
+import { type SidecarReclaimGuard } from "./sidecar-lock-reclaim.js";
+import { type SidecarLockParserState } from "./sidecar-lock-admission-parser.js";
+import type { Root } from "./root-impl.js";
+import type { SidecarLockAcquireOptions } from "./sidecar-lock-types.js";
+type SidecarAdmissionRunner = {
+    hasToken(): boolean;
+    run<T>(callback: () => T): T;
+};
+type StaleOptions = Pick<SidecarLockAcquireOptions<Record<string, unknown>>, "shouldReclaim" | "shouldRemoveStaleLock" | "staleRecovery">;
+export type SidecarLockStaleOptionsState = {
+    shouldReclaimObserved?: boolean;
+    shouldReclaim?: StaleOptions["shouldReclaim"];
+    shouldRemoveObserved?: boolean;
+    shouldRemove?: StaleOptions["shouldRemoveStaleLock"];
+    staleRecoveryObserved?: boolean;
+    staleRecovery?: StaleOptions["staleRecovery"];
+};
+/** Handle one historical EEXIST attempt while its canonical admission is held. */
+export declare function handleStaleSidecarAdmission<TPayload extends Record<string, unknown>>(params: {
+    admission: SidecarAdmissionRunner;
+    assertToken(): void;
+    currentHeld(): unknown;
+    lockPath: string;
+    lockRoot?: Root;
+    normalizedTargetPath: string;
+    options: SidecarLockAcquireOptions<TPayload>;
+    parserState: SidecarLockParserState;
+    reclaimGuardPath: string;
+    reclaimGuards: Set<string>;
+    setReclaimGuard(guard: SidecarReclaimGuard): void;
+    releaseReclaimGuard(): Promise<void>;
+    staleOptionsState: SidecarLockStaleOptionsState;
+    staleMs: number;
+    withinDenialBudget(): boolean;
+    retryOrRethrowDenial(error: unknown): Promise<void>;
+    waitForRetry(): Promise<void>;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,228 @@
+import { defaultSidecarLockShouldReclaim, isTransientLockFileDenial, sidecarLockStale } from "./sidecar-lock-policy.js";
+import { readSidecarLockRawSnapshot, removeStaleSidecarLockIfAllowed, sidecarLockSnapshotStillPresent, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { observeSidecarLockParser, parseSidecarLockSnapshotUnderAdmission, scopedSidecarLockParser, } from "./sidecar-lock-admission-parser.js";
+/** Handle one historical EEXIST attempt while its canonical admission is held. */
+export async function handleStaleSidecarAdmission(params) {
+    const { admission, lockPath, normalizedTargetPath, options } = params;
+    const holderChanged = {};
+    const assertUnheld = () => {
+        params.assertToken();
+        if (params.currentHeld())
+            throw holderChanged;
+    };
+    const retryHolderChange = async (error) => {
+        if (error !== holderChanged)
+            return false;
+        await params.waitForRetry();
+        return true;
+    };
+    const retryChangedBoundary = async () => {
+        try {
+            assertUnheld();
+            return false;
+        }
+        catch (error) {
+            if (await retryHolderChange(error))
+                return true;
+            throw error;
+        }
+    };
+    let rawSnapshot;
+    let lockFileOpenDenied = false;
+    try {
+        rawSnapshot = await admission.run(async () => await readSidecarLockRawSnapshot(lockPath, {
+            lockRoot: params.lockRoot,
+            rejectNonFile: true,
+            discardObservation: "changed",
+            onOpenFailure: (error) => {
+                lockFileOpenDenied = isTransientLockFileDenial(error, lockPath);
+            },
+        }));
+    }
+    catch (error) {
+        if (await retryChangedBoundary())
+            return;
+        if (!lockFileOpenDenied || !params.withinDenialBudget())
+            throw error;
+        await params.retryOrRethrowDenial(error);
+        return;
+    }
+    params.assertToken();
+    if (params.currentHeld()) {
+        await params.waitForRetry();
+        return;
+    }
+    let snapshot;
+    try {
+        observeSidecarLockParser(params.parserState, admission, () => options.parsePayload, assertUnheld);
+        snapshot = parseSidecarLockSnapshotUnderAdmission(rawSnapshot, params.parserState, admission, assertUnheld);
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        await params.waitForRetry();
+        return;
+    }
+    const staleOptions = params.staleOptionsState;
+    try {
+        if (!staleOptions.shouldReclaimObserved) {
+            assertUnheld();
+            staleOptions.shouldReclaim = admission.run(() => options.shouldReclaim);
+            staleOptions.shouldReclaimObserved = true;
+            assertUnheld();
+        }
+        if (!staleOptions.shouldRemoveObserved) {
+            assertUnheld();
+            staleOptions.shouldRemove = admission.run(() => options.shouldRemoveStaleLock);
+            staleOptions.shouldRemoveObserved = true;
+            assertUnheld();
+        }
+        if (!staleOptions.staleRecoveryObserved) {
+            assertUnheld();
+            staleOptions.staleRecovery = admission.run(() => options.staleRecovery);
+            staleOptions.staleRecoveryObserved = true;
+            assertUnheld();
+        }
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    const shouldReclaim = staleOptions.shouldReclaim ?? defaultSidecarLockShouldReclaim;
+    let reclaim;
+    try {
+        reclaim = await admission.run(async () => {
+            assertUnheld();
+            try {
+                return await Reflect.apply(shouldReclaim, undefined, [{
+                        lockPath,
+                        normalizedTargetPath,
+                        payload: snapshot.payload ?? null,
+                        staleMs: params.staleMs,
+                        nowMs: Date.now(),
+                        heldByThisProcess: false,
+                    }]);
+            }
+            finally {
+                assertUnheld();
+            }
+        });
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!reclaim) {
+        await params.waitForRetry();
+        return;
+    }
+    let stillPresent;
+    try {
+        stillPresent = await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
+            lockRoot: params.lockRoot,
+            parsePayload: scopedSidecarLockParser(params.parserState, admission, assertUnheld),
+        });
+        assertUnheld();
+    }
+    catch (error) {
+        if (await retryHolderChange(error))
+            return;
+        if (await retryChangedBoundary())
+            return;
+        throw error;
+    }
+    if (!stillPresent) {
+        await params.waitForRetry();
+        return;
+    }
+    if ((staleOptions.staleRecovery ?? "fail-closed") === "remove-if-unchanged") {
+        const acquiredGuard = await admission.run(() => tryAcquireSidecarReclaimGuard(params.reclaimGuards, params.reclaimGuardPath, params.lockRoot));
+        if (acquiredGuard)
+            params.setReclaimGuard(acquiredGuard);
+        params.assertToken();
+        if (params.currentHeld()) {
+            if (acquiredGuard) {
+                await params.releaseReclaimGuard();
+            }
+            await params.waitForRetry();
+            return;
+        }
+        if (!acquiredGuard) {
+            await params.waitForRetry();
+            return;
+        }
+        const shouldRemove = staleOptions.shouldRemove;
+        const assertRemovalAuthorized = assertUnheld;
+        const guardedShouldRemove = shouldRemove && function (staleSnapshot) {
+            return admission.run(async () => {
+                assertRemovalAuthorized();
+                try {
+                    return await Reflect.apply(shouldRemove, this, [staleSnapshot]);
+                }
+                finally {
+                    assertRemovalAuthorized();
+                }
+            });
+        };
+        let removal;
+        try {
+            removal = await removeStaleSidecarLockIfAllowed({
+                lockPath,
+                normalizedTargetPath,
+                snapshot,
+                assertGuardHeld: acquiredGuard.assertHeld && (() => admission.run(async () => {
+                    assertUnheld();
+                    await acquiredGuard.assertHeld();
+                    assertUnheld();
+                })),
+                shouldRemoveStaleLock: guardedShouldRemove,
+                lockRoot: params.lockRoot,
+                parsePayload: scopedSidecarLockParser(params.parserState, admission, assertRemovalAuthorized),
+                assertAuthorized: assertRemovalAuthorized,
+            });
+        }
+        catch (error) {
+            if (error !== holderChanged) {
+                try {
+                    assertRemovalAuthorized();
+                }
+                catch (boundaryError) {
+                    if (boundaryError !== holderChanged)
+                        throw boundaryError;
+                }
+                if (!params.currentHeld())
+                    throw error;
+            }
+            await params.releaseReclaimGuard();
+            await params.waitForRetry();
+            return;
+        }
+        params.assertToken();
+        if (params.currentHeld()) {
+            await params.releaseReclaimGuard();
+            await params.waitForRetry();
+            return;
+        }
+        if (removal === "removed")
+            return;
+        if (removal === "changed") {
+            await params.waitForRetry();
+            return;
+        }
+        await params.releaseReclaimGuard();
+    }
+    throw sidecarLockStale(lockPath, normalizedTargetPath);
+}

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

@@ -0,0 +1,7 @@
+import type { Root } from "./root-impl.js";
+export declare function isCwdIndependentAbsolutePath(filePath: string): boolean;
+export declare function resolveSidecarTargetPath(resolved: string, lockRoot?: Root): Promise<string>;
+export declare function resolveSidecarLockPaths(targetPath: string, explicitLockPath: string | undefined, lockRoot: Root | undefined): Promise<{
+    lockPath: string;
+    normalizedTargetPath: string;
+}>;

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

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
+import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+export function isCwdIndependentAbsolutePath(filePath) {
+    if (!path.isAbsolute(filePath))
+        return false;
+    // A leading separator on Windows is rooted on the process's current drive.
+    return process.platform !== "win32" || path.parse(filePath).root.length > 1;
+}
+export async function resolveSidecarTargetPath(resolved, lockRoot) {
+    assertNoWindowsPathAlias(resolved);
+    const dir = path.dirname(resolved);
+    if (lockRoot) {
+        // The target is an arbitration key, not necessarily inside the lock Root.
+        await lockRoot.resolve(".");
+        const parent = await canonicalPathFromExistingAncestor(dir);
+        await lockRoot.resolve(".");
+        assertNoWindowsPathAlias(parent);
+        const normalized = path.join(parent, path.basename(resolved));
+        assertNoWindowsPathAlias(normalized);
+        return normalized;
+    }
+    await fs.mkdir(recursiveMkdirPath(dir), { recursive: true });
+    let parent;
+    try {
+        parent = realpathSync.native(dir);
+    }
+    catch {
+        return resolved;
+    }
+    assertNoWindowsPathAlias(parent);
+    const normalized = path.join(parent, path.basename(resolved));
+    assertNoWindowsPathAlias(normalized);
+    return normalized;
+}
+export async function resolveSidecarLockPaths(targetPath, explicitLockPath, lockRoot) {
+    const anchoredTargetPath = anchorWindowsDriveRelativePath(targetPath);
+    assertNoWindowsPathAlias(anchoredTargetPath);
+    const resolvedTargetPath = path.resolve(anchoredTargetPath);
+    let resolvedLockPath;
+    if (explicitLockPath !== undefined) {
+        const anchoredLockPath = anchorWindowsDriveRelativePath(explicitLockPath);
+        assertNoWindowsPathAlias(anchoredLockPath);
+        resolvedLockPath = isCwdIndependentAbsolutePath(explicitLockPath)
+            ? explicitLockPath
+            : path.resolve(anchoredLockPath);
+    }
+    const normalizedTargetPath = await resolveSidecarTargetPath(resolvedTargetPath, lockRoot);
+    const lockPath = resolvedLockPath ?? `${normalizedTargetPath}.lock`;
+    assertNoWindowsPathAlias(lockPath);
+    return { lockPath, normalizedTargetPath };
+}

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

@@ -0,0 +1,68 @@
+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 SidecarLockOptionFields<T> = {
+    [K in keyof T]: T[K];
+};
+export type SidecarLockCommonAcquireOptions = {
+    lockPath?: string;
+    timeoutMs?: number;
+    retry?: SidecarLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
+    reentrantOwner?: string;
+    parsePayload?: (raw: string) => unknown;
+    lockRoot?: Root;
+    onCompromised?: (info: SidecarLockCompromisedInfo) => void;
+    compromiseCheckIntervalMs?: number;
+};
+export type SidecarLockReclaimParams<Held extends boolean = boolean> = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    payload: unknown;
+    staleMs: number;
+    nowMs: number;
+    heldByThisProcess: Held;
+};
+export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = SidecarLockOptionFields<SidecarLockCommonAcquireOptions & {
+    targetPath: string;
+    staleMs: number;
+    payload: () => TPayload | Promise<TPayload>;
+    shouldReclaim?: (params: SidecarLockReclaimParams) => boolean | Promise<boolean>;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
+    metadata?: Record<string, unknown>;
+    /**
+     * 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;
+}>;
+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;
+};

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

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

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

@@ -0,0 +1,13 @@
+import type { SidecarLockAcquireOptions, SidecarLockHandle, SidecarLockHeldEntry, WithSidecarLockOptions } from "./sidecar-lock-types.js";
+export type { SidecarLockStaleSnapshot } from "./sidecar-lock-reclaim.js";
+export type { SidecarLockAcquireOptions, SidecarLockCompromisedInfo, SidecarLockHandle, SidecarLockHeldEntry, SidecarLockRetryOptions, SidecarLockStaleRecovery, WithSidecarLockOptions, } from "./sidecar-lock-types.js";
+/** True when a retain-unaware package copy registered the process-exit handlers first. */
+export declare function exitCleanupCannotRetain(): boolean;
+export declare function createSidecarLockManager(key: string): {
+    acquire: <TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>) => Promise<SidecarLockHandle>;
+    withLock: <T, TPayload extends Record<string, unknown>>(options: SidecarLockAcquireOptions<TPayload>, fn: () => Promise<T>) => Promise<T>;
+    drain: () => Promise<void>;
+    reset: () => void;
+    heldEntries: () => SidecarLockHeldEntry[];
+};
+export declare function withSidecarLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: WithSidecarLockOptions<TPayload>, fn: () => Promise<T>): Promise<T>;