@openclaw/signal 2026.9.5 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/root-path-observation.d.ts

@@ -0,0 +1,62 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type DirectoryObservationGuard } from "./directory-guard.js";
+import { type NativeDirectoryObservationBackend, type NativeDirectoryObservationGuard } from "./native-directory-observation.js";
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type StatObservationReceipt } from "./stat-observation.js";
+export type RootPathObservationKind = "stat" | "directory";
+export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
+export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
+/** An exact receipt owned by one stat/list operation. Never cache it. */
+export type RootPathObservationReceipt = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryGuard: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath: string;
+    target: RootPathTargetObservation;
+};
+/** A failed initial target lookup must not discard its already admitted parent. */
+export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
+    kind: "stat-parent";
+};
+export type RootPathObservationRequest = {
+    kind: RootPathObservationKind;
+    rootGuard: DirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+};
+export type RootPathTraversalObservation = {
+    enabled: boolean;
+    request: RootPathObservationRequest;
+    targetIndex: number;
+    directoryIndex: number;
+    directoryGuard?: RootPathDirectoryObservationGuard;
+    directoryObserver?: NativeDirectoryObservationBackend;
+    targetPath?: string;
+    target?: RootPathTargetObservation;
+};
+export type RootPathObservedTraversalEntry = StatObservationReceipt | {
+    stat: fs.Stats | BigIntStats;
+    identity?: undefined;
+} | NativeDirectoryObservationGuard;
+export declare class RootPathObservationError extends Error {
+    readonly error: unknown;
+    readonly parentReceipt?: RootPathParentObservationReceipt | undefined;
+    readonly traversalFailure: boolean;
+    constructor(error: unknown, parentReceipt?: RootPathParentObservationReceipt | undefined, traversalFailure?: boolean);
+}
+export type RootPathTraversalContext = {
+    observationEligible: boolean;
+    rootPath: string;
+    rootCanonicalPath: string;
+    resolveParams: {
+        rootIdentity?: RootBoundaryIdentity;
+    };
+    state: {
+        finalComponentIndex: number;
+        relativePath: string;
+        segments: string[];
+    };
+};
+export declare function createRootPathTraversalObservation(context: RootPathTraversalContext, request?: RootPathObservationRequest): RootPathTraversalObservation | undefined;
+export declare function inspectRootPathTraversalEntry(pathname: string, directorySlot: boolean, observation: RootPathTraversalObservation): RootPathObservedTraversalEntry;
+export declare function captureRootPathObservedDirectory(observation: RootPathTraversalObservation, observed: RootPathObservedTraversalEntry, publicPath: string, canonicalPath: string, rootCanonicalPath: string, rootIdentity?: RootBoundaryIdentity): boolean;

package/node_modules/@openclaw/fs-safe/dist/root-path-observation.js

@@ -0,0 +1,180 @@
+import fs, {} from "node:fs";
+import { extendDirectoryObservationGuard, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { extendNativeDirectoryObservationGuard, inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
+import { admitPathInsideRoot, } from "./root-boundary.js";
+import { realpathSync } from "./realpath.js";
+import { inspectStatObservationSync } from "./stat-observation.js";
+// Observation-only failures happen after ordinary traversal has admitted the
+// name. Keep them distinguishable so Root preserves existing error precedence.
+export class RootPathObservationError extends Error {
+    error;
+    parentReceipt;
+    traversalFailure;
+    constructor(error, parentReceipt, traversalFailure = false) {
+        super("root path observation failed", { cause: error });
+        this.error = error;
+        this.parentReceipt = parentReceipt;
+        this.traversalFailure = traversalFailure;
+        this.name = "RootPathObservationError";
+    }
+}
+function straightTraversalPath(value) {
+    if (value.length === 0)
+        return false;
+    const windows = process.platform === "win32";
+    let segmentStart = 0;
+    for (let index = 0; index <= value.length; index += 1) {
+        const separator = index === value.length || value[index] === "/" ||
+            (windows && value[index] === "\\");
+        if (!separator)
+            continue;
+        const segmentLength = index - segmentStart;
+        if (segmentLength === 0 ||
+            (segmentLength === 1 && value.charCodeAt(segmentStart) === 0x2e) ||
+            (segmentLength === 2 && value.charCodeAt(segmentStart) === 0x2e &&
+                value.charCodeAt(segmentStart + 1) === 0x2e))
+            return false;
+        segmentStart = index + 1;
+    }
+    return true;
+}
+export function createRootPathTraversalObservation(context, request) {
+    const { state } = context;
+    const rootTraversal = state.finalComponentIndex < 0 &&
+        (state.relativePath === "" || state.relativePath === ".");
+    if (!request || !context.observationEligible ||
+        request.rootGuard.dir !== context.rootCanonicalPath ||
+        request.rootGuard.realPath !== context.rootCanonicalPath ||
+        context.rootPath !== context.rootCanonicalPath ||
+        (!rootTraversal && !straightTraversalPath(state.relativePath)) ||
+        (!rootTraversal && state.finalComponentIndex !== state.segments.length - 1))
+        return undefined;
+    if (state.finalComponentIndex >= 0) {
+        const directoryIndex = request.kind === "stat"
+            ? state.finalComponentIndex - 1
+            : state.finalComponentIndex;
+        return {
+            enabled: true,
+            request,
+            targetIndex: state.finalComponentIndex,
+            directoryIndex,
+            directoryGuard: directoryIndex < 0 ? request.rootGuard : undefined,
+            // A direct-child stat has no selected-directory slot at which the
+            // optional helper can establish a receipt. Keep its final Root fence on
+            // the established JavaScript path so helper unavailability cannot first
+            // appear after the target has been admitted.
+            directoryObserver: directoryIndex < 0 ? undefined : request.directoryObserver,
+        };
+    }
+    if (!rootTraversal)
+        return undefined;
+    let directoryGuard = request.rootGuard;
+    // Root-only stat likewise has no pre-admission helper observation. Root
+    // listing below does establish one and may safely retain the backend.
+    let directoryObserver = request.kind === "stat" ? undefined : request.directoryObserver;
+    if (request.kind === "directory") {
+        if (directoryObserver) {
+            try {
+                const observed = inspectNativeDirectoryObservation(directoryObserver, request.rootGuard.dir, request.rootGuard.identity);
+                const admitted = admitPathInsideRoot({
+                    rootPath: context.rootCanonicalPath,
+                    candidatePath: observed.realPath,
+                    rootIdentity: context.resolveParams.rootIdentity,
+                });
+                if (!admitted || admitted.relativePath !== "") {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+                observed.realPath = admitted.path;
+                directoryGuard = extendNativeDirectoryObservationGuard(observed, request.rootGuard.dir);
+            }
+            catch (error) {
+                if (error instanceof FsSafeError && error.code === "path-mismatch") {
+                    throw new RootPathObservationError(error);
+                }
+                directoryObserver = undefined;
+            }
+        }
+        if (!directoryObserver) {
+            try {
+                const admitted = admitPathInsideRoot({
+                    rootPath: context.rootCanonicalPath,
+                    candidatePath: realpathSync.native(request.rootGuard.dir),
+                    rootIdentity: context.resolveParams.rootIdentity,
+                });
+                if (!admitted || admitted.relativePath !== "") {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+            }
+            catch (error) {
+                throw new RootPathObservationError(error);
+            }
+        }
+    }
+    return {
+        enabled: true,
+        request,
+        targetIndex: -1,
+        directoryIndex: -1,
+        directoryGuard,
+        directoryObserver,
+        targetPath: context.rootCanonicalPath,
+        target: directoryGuard,
+    };
+}
+export function inspectRootPathTraversalEntry(pathname, directorySlot, observation) {
+    if (directorySlot && observation.directoryObserver) {
+        try {
+            return extendNativeDirectoryObservationGuard(inspectNativeDirectoryObservation(observation.directoryObserver, pathname), pathname);
+        }
+        catch {
+            // This directory has not been admitted yet. Preserve the established
+            // resolver and error ordering when the optional observation is unusable.
+            observation.directoryObserver = undefined;
+        }
+    }
+    const first = process.platform === "win32"
+        ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname);
+    if (first.isSymbolicLink() || (directorySlot && !first.isDirectory()))
+        return { stat: first };
+    try {
+        return inspectStatObservationSync(bigint => bigint
+            ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname), undefined, first);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new RootPathObservationError(error);
+        }
+        throw error;
+    }
+}
+export function captureRootPathObservedDirectory(observation, observed, publicPath, canonicalPath, rootCanonicalPath, rootIdentity) {
+    if (!isNativeDirectoryObservationGuard(observed) && !observed.stat.isDirectory())
+        return false;
+    let realPath;
+    try {
+        realPath = isNativeDirectoryObservationGuard(observed)
+            ? observed.realPath
+            : realpathSync.native(canonicalPath);
+    }
+    catch (error) {
+        throw new RootPathObservationError(error);
+    }
+    const admitted = admitPathInsideRoot({
+        rootPath: rootCanonicalPath,
+        candidatePath: realPath,
+        rootIdentity,
+    });
+    if (!admitted) {
+        throw new RootPathObservationError(new FsSafeError("outside-workspace", "directory is outside workspace root"));
+    }
+    if (isNativeDirectoryObservationGuard(observed)) {
+        observed.dir = publicPath;
+        observed.realPath = admitted.path;
+        observation.directoryGuard = observed;
+    }
+    else {
+        observation.directoryGuard = extendDirectoryObservationGuard(observed, publicPath, admitted.path);
+    }
+    return true;
+}

package/node_modules/@openclaw/fs-safe/dist/root-path-stat.d.ts

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+import type { RootPathObservationReceipt } from "./root-path.js";
+import type { PathStat } from "./types.js";
+export declare function statResolvedPathInRoot(root: RootContext, resolvedPath: string, receipt?: RootPathObservationReceipt): Promise<PathStat>;

package/node_modules/@openclaw/fs-safe/dist/root-path-stat.js

@@ -0,0 +1,151 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
+import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
+import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
+import { errorCauseOptions, fileNotFoundError } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertStatObservationSync } from "./stat-observation.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function singleLinkFileIdentity(stat) {
+    if (!stat?.isFile() || stat.isSymbolicLink() || (stat.nlink !== 1 && stat.nlink !== 1n))
+        return;
+    const exact = (value) => typeof value === "bigint" ? value : Number.isSafeInteger(value) ? BigInt(value) : undefined;
+    const dev = exact(stat.dev), ino = exact(stat.ino);
+    if (dev === undefined || ino === undefined || dev < 0n || ino < 0n ||
+        (process.platform === "win32" && (dev === 0n || ino === 0n)))
+        return;
+    return { dev, ino };
+}
+async function captureChangedObservedFile(error, pathname, before, observed, assertParents, proof) {
+    try {
+        const previous = singleLinkFileIdentity(before), current = singleLinkFileIdentity(observed);
+        if (!previous || !current || (previous.dev === current.dev && previous.ino === current.ino))
+            return;
+        await assertParents();
+        // A changed metadata probe grants only a fresh acquisition attempt, never ownership.
+        proof.failure = { error, kind: `stat-leaf-changed:${pathname}` };
+    }
+    catch {
+        // Ambiguous file or ancestry observations retain the original public error.
+    }
+}
+async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
+    const failure = new FsSafeError("path-mismatch", "file changed during operation", errorCauseOptions(cause));
+    if (hasNodeErrorCode(cause, "ENOENT") && before?.isFile() && !before.isSymbolicLink() &&
+        (before.nlink === 1 || before.nlink === 1n)) {
+        try {
+            await assertParents();
+            // Metadata loss permits discarding a probe, never reading or owning a file.
+            proof.failure = { error: failure, kind: `stat-leaf-missing:${pathname}` };
+        }
+        catch {
+            // Keep the public mismatch and withhold provenance when ancestry changed.
+        }
+    }
+    return failure;
+}
+export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
+    const proof = {};
+    try {
+        // Nested observations in a hook cannot grant this invocation discard authority.
+        return await fileObservation().run(() => statObservedPathInRoot(root, resolvedPath, proof, receipt));
+    }
+    catch (error) {
+        const failure = proof.failure;
+        if (failure && failure.error === error)
+            recordFileObservationFailure(error, failure.kind);
+        throw error;
+    }
+}
+async function statObservedPathInRoot(root, resolvedPath, proof, receipt) {
+    let admittedTarget = false;
+    try {
+        if (receipt) {
+            if (receipt.kind !== "stat" || receipt.targetPath !== resolvedPath) {
+                throw new FsSafeError("path-mismatch", "file observation receipt does not match target");
+            }
+            admittedTarget = true;
+            const beforeObservation = getFsSafeTestHooks()?.beforeRootStatObservation;
+            if (beforeObservation)
+                await beforeObservation(resolvedPath);
+            let observed;
+            let sample, samples = 0;
+            const comparison = fileObservation();
+            try {
+                observed = comparison.run(() => assertStatObservationSync(bigint => {
+                    sample = bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath);
+                    samples += 1;
+                    return sample;
+                }, receipt.target.identity));
+            }
+            catch (error) {
+                if (isNotFoundPathError(error)) {
+                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
+                }
+                if (comparison.has(error, "identity"))
+                    await captureChangedObservedFile(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, samples === 1 ? sample : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
+                throw error;
+            }
+            if (observed.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "file changed during operation");
+            }
+            assertRootPathObservationReceiptCurrent(root, receipt, observed);
+            return pathStatFromStats(observed);
+        }
+        const guardPath = resolvedPath === root.rootReal ? root.rootReal : path.dirname(resolvedPath);
+        const parentGuard = guardPath === root.rootReal && root.rootGuard
+            ? root.rootGuard
+            : await createRootDirectoryObservationGuard(root, guardPath);
+        let expected;
+        try {
+            const beforeInitialObservation = getFsSafeTestHooks()?.beforeRootStatInitialObservation;
+            if (beforeInitialObservation)
+                await beforeInitialObservation(resolvedPath);
+            expected = inspectFileIdentitySync(() => fsSync.lstatSync(resolvedPath, { bigint: true }));
+            if (expected.isSymbolicLink()) {
+                throw new FsSafeError("path-mismatch", "file changed during operation");
+            }
+        }
+        catch (error) {
+            // No initial target error is safe to expose until the admitted parent is
+            // proven current; a redirect must win over an ordinary lookup failure.
+            await assertRootDirectoryObservationGuard(root, parentGuard);
+            throw error;
+        }
+        admittedTarget = true;
+        const beforeObservation = getFsSafeTestHooks()?.beforeRootStatObservation;
+        if (beforeObservation)
+            await beforeObservation(resolvedPath);
+        let observed;
+        let sample, samples = 0;
+        const comparison = fileObservation();
+        try {
+            observed = comparison.run(() => inspectFileIdentitySync(() => {
+                sample = fsSync.lstatSync(resolvedPath, { bigint: true });
+                samples += 1;
+                return sample;
+            }, expected));
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
+            }
+            if (comparison.has(error, "identity"))
+                await captureChangedObservedFile(error, resolvedPath, expected, samples === 1 ? sample : undefined, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
+            throw error;
+        }
+        if (observed.isSymbolicLink()) {
+            throw new FsSafeError("path-mismatch", "file changed during operation");
+        }
+        await assertRootDirectoryObservationGuard(root, parentGuard);
+        return pathStatFromStats(observed);
+    }
+    catch (error) {
+        if (!admittedTarget && isNotFoundPathError(error)) {
+            throw fileNotFoundError(error instanceof Error ? error : undefined);
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type RootPathObservationReceipt, type RootPathObservationRequest } from "./root-path-observation.js";
+import type { RemovalPathReceipts } from "./root-remove-receipt.js";
+export { resolvePathViaExistingAncestorSync } from "./root-path-existing.js";
+export { RootPathObservationError, type RootPathDirectoryObservationGuard, type RootPathObservationKind, type RootPathObservationReceipt, type RootPathParentObservationReceipt, type RootPathObservationRequest, type RootPathTargetObservation, } from "./root-path-observation.js";
+type RootPathIntent = "read" | "write" | "create" | "delete" | "stat";
+export type RootPathAliasPolicy = {
+    allowFinalSymlinkForUnlink?: boolean;
+    allowFinalHardlinkForUnlink?: boolean;
+};
+export declare const ROOT_PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+type ResolveRootPathParams = {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    intent?: RootPathIntent;
+    policy?: RootPathAliasPolicy;
+    rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    rejectUnresolvedSymlinks?: boolean;
+    skipLexicalRootCheck?: boolean;
+    rootCanonicalPath?: string;
+    rootIdentity?: RootBoundaryIdentity;
+};
+type ResolvedRootPathKind = "missing" | "file" | "directory" | "symlink" | "other";
+export type ResolvedRootPath = {
+    absolutePath: string;
+    canonicalPath: string;
+    rootPath: string;
+    rootCanonicalPath: string;
+    relativePath: string;
+    exists: boolean;
+    kind: ResolvedRootPathKind;
+};
+export type ObservedRootPath = {
+    resolved: ResolvedRootPath;
+    receipt?: RootPathObservationReceipt;
+};
+export declare function resolveRootPath(params: ResolveRootPathParams): Promise<ResolvedRootPath>;
+export declare function resolveRootPathWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): Promise<ResolvedRootPath>;
+export declare function resolveRootPathWithObservation(params: ResolveRootPathParams, request: RootPathObservationRequest): Promise<ObservedRootPath>;
+export declare function resolveRootPathForRemoval(params: ResolveRootPathParams, receipts: RemovalPathReceipts): Promise<ResolvedRootPath>;
+export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
+export declare function resolveRootPathSyncWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): ResolvedRootPath;