@openclaw/signal 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/retained-file.js

@@ -0,0 +1,121 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+function freeze(result) {
+    return Object.freeze({ ...result, errors: Object.freeze(result.errors.map((error) => Object.freeze({ ...error }))) });
+}
+function unsupported(cause) {
+    return freeze({ status: "unsupported", phase: "admission", disposition: "not-attempted",
+        namespace: "not-observed", resources: "closed", persistence: "not-proven",
+        errors: [{ phase: "admission", code: "helper-unavailable",
+                message: "existing-file retention requires the maintained Windows native capability", cause }] });
+}
+function exact(value, name, zero = false) {
+    if (typeof value !== "bigint" || value < (zero ? 0n : 1n) || value > 0xffffffffffffffffn) {
+        throw new TypeError(`${name} must be an exact ${zero ? "nonnegative" : "positive"} unsigned 64-bit bigint`);
+    }
+    return value;
+}
+class Owner {
+    receipt;
+    #native;
+    #assert;
+    #result;
+    #running = false;
+    #reentered = false;
+    constructor(native, receipt, assertion) {
+        this.#native = native;
+        this.receipt = receipt;
+        this.#assert = assertion;
+        Object.freeze(this);
+    }
+    #settle(remove) {
+        if (this.#result)
+            return this.#result;
+        if (this.#running) {
+            this.#reentered = true;
+            throw new TypeError("retained-file settlement cannot be reentered");
+        }
+        this.#running = true;
+        let rejection;
+        if (remove) {
+            try {
+                assertSynchronousCallbackResult(this.#assert(), "assertBeforeMutation");
+                if (this.#reentered)
+                    throw new TypeError("retained-file authority reentered settlement");
+            }
+            catch (cause) {
+                rejection = { cause };
+            }
+        }
+        try {
+            const result = this.#native.settle(remove && !rejection);
+            this.#result = freeze(rejection ? { ...result, phase: "authority", errors: [
+                    { phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause },
+                    ...result.errors,
+                ] } : result);
+        }
+        catch (cause) {
+            // An unexpected binding exception cannot establish native effect or close.
+            // Do not retry or release a dependency on an unknown native outcome.
+            this.#result = freeze({ status: "indeterminate", phase: "binding", identity: this.receipt.identity,
+                disposition: remove && !rejection ? "indeterminate" : "not-attempted", namespace: "unknown",
+                resources: "close-failed", persistence: "not-proven", errors: [
+                    ...(rejection ? [{ phase: "authority", code: "denied-path", message: "current mutation authority rejected removal", cause: rejection.cause }] : []),
+                    { phase: "binding", code: "helper-failed", message: "native settlement did not return a result", cause },
+                ] });
+        }
+        return this.#result;
+    }
+    remove() { return this.#settle(true); }
+    dispose() { return this.#settle(false); }
+    [Symbol.dispose]() {
+        const result = this.dispose();
+        if (result.resources !== "closed") {
+            throw new FsSafeError("helper-failed", "retained-file resource settlement is uncertain", { details: { result } });
+        }
+    }
+}
+/** Retain one existing regular file on supported local Windows NTFS. No fallback. */
+export function retainFileInDirectory(options) {
+    // Snapshot once before any native resource admission or caller authority runs.
+    const directory = options.directory;
+    const basename = options.basename;
+    const sourceParent = options.parent;
+    const parent = Object.freeze({ dev: exact(sourceParent.dev, "parent.dev"), ino: exact(sourceParent.ino, "parent.ino") });
+    const source = options.expected;
+    const expected = Object.freeze({ dev: exact(source.dev, "expected.dev"), ino: exact(source.ino, "expected.ino"),
+        size: exact(source.size, "expected.size", true), mtimeNs: exact(source.mtimeNs, "expected.mtimeNs", true),
+        ctimeNs: exact(source.ctimeNs, "expected.ctimeNs", true), sha256: source.sha256 });
+    const assertion = options.assertBeforeMutation;
+    const maxBytes = options.maxBytes ?? 16 * 1024 * 1024;
+    if (typeof directory !== "string" || typeof basename !== "string" || typeof assertion !== "function"
+        || typeof expected.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(expected.sha256)
+        || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 64 * 1024 * 1024 || expected.size > BigInt(maxBytes)) {
+        throw new TypeError("invalid retained-file directory, authority or bounded expected-byte contract");
+    }
+    if (process.platform !== "win32")
+        return unsupported();
+    let binding;
+    try {
+        binding = getNativeBinding();
+    }
+    catch (cause) {
+        return unsupported(cause);
+    }
+    if (!binding?.retainWindowsFile)
+        return unsupported();
+    let native;
+    try {
+        native = binding.retainWindowsFile(directory, basename, parent.dev, parent.ino, expected.dev, expected.ino, expected.size, expected.mtimeNs, expected.ctimeNs, expected.sha256, maxBytes);
+    }
+    catch (cause) {
+        // Factory errors have no returned owner; never infer absence or deletion.
+        return freeze({ ...unsupported(cause), status: "indeterminate", resources: "close-failed" });
+    }
+    const admission = native.admission;
+    if (admission.status !== "retained")
+        return freeze(admission);
+    const receipt = Object.freeze({ directory, parent, basename, expected, identity: admission.identity });
+    return Object.freeze({ status: "retained", file: new Owner(native, receipt, assertion) });
+}

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

@@ -0,0 +1,29 @@
+export declare function sameNormalizedPathSpelling(left: string, right: string): boolean;
+export type RootBoundaryIdentity = Readonly<{
+    dev: number | bigint;
+    ino: number | bigint;
+}>;
+export type AdmittedRootPath = Readonly<{
+    path: string;
+    relativePath: string;
+    admission: "exact" | "identity";
+}>;
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export declare function admitPathInsideRoot(params: {
+    rootPath: string;
+    candidatePath: string;
+    rootIdentity?: RootBoundaryIdentity;
+    resolveCandidateRoot?: boolean;
+    identityCache?: Map<string, boolean>;
+    inspectCandidateRoot?: (candidateRootPath: string, expected: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>) => void;
+}): AdmittedRootPath | undefined;

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

@@ -0,0 +1,186 @@
+import path from "node:path";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
+export function sameNormalizedPathSpelling(left, right) {
+    // Preserve case on Windows, where individual directories can be case-sensitive.
+    return path.resolve(left) === path.resolve(right);
+}
+function windowsComparablePath(value, normalize) {
+    const original = normalize
+        ? path.win32.normalize(value.replaceAll("/", "\\"))
+        : value.replaceAll("/", "\\");
+    if (/^\\\\\?\\UNC\\/i.test(original)) {
+        return {
+            original,
+            comparison: `\\\\${original.slice(8)}`,
+            originalIndex: (comparisonIndex) => comparisonIndex + 6,
+        };
+    }
+    if (original.startsWith("\\\\?\\")) {
+        return {
+            original,
+            comparison: original.slice(4),
+            originalIndex: (comparisonIndex) => comparisonIndex + 4,
+        };
+    }
+    return { original, comparison: original, originalIndex: (comparisonIndex) => comparisonIndex };
+}
+function trimWindowsTrailingSeparators(value) {
+    const rootLength = path.win32.parse(value).root.length;
+    let end = value.length;
+    while (end > rootLength && value[end - 1] === "\\")
+        end -= 1;
+    return value.slice(0, end);
+}
+function trimWindowsLeadingSeparators(value) {
+    let start = 0;
+    while (value[start] === "\\")
+        start += 1;
+    return value.slice(start);
+}
+function exactWindowsRootPrefix(rootPath, candidatePath) {
+    const root = trimWindowsTrailingSeparators(rootPath.replaceAll("/", "\\"));
+    const candidate = candidatePath.replaceAll("/", "\\");
+    let relativePath;
+    if (candidate === root) {
+        relativePath = "";
+    }
+    else {
+        const rootWithSep = root.endsWith("\\") ? root : `${root}\\`;
+        if (!candidate.startsWith(rootWithSep))
+            return undefined;
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+    }
+    return {
+        admission: "exact",
+        candidateRootPath: root,
+        path: relativePath === "" ? root : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`,
+        relativePath,
+    };
+}
+function windowsRootPrefix(rootPath, candidatePath) {
+    const exact = exactWindowsRootPrefix(rootPath, candidatePath);
+    if (exact)
+        return exact;
+    const trusted = windowsComparablePath(rootPath, true);
+    const supplied = windowsComparablePath(candidatePath, false);
+    const root = trimWindowsTrailingSeparators(trusted.original);
+    const rootComparison = trimWindowsTrailingSeparators(trusted.comparison);
+    const candidate = supplied.comparison;
+    if (!path.win32.isAbsolute(supplied.original))
+        return undefined;
+    let relativePath;
+    let candidateRootPath;
+    let admission;
+    if (candidate === rootComparison) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "exact";
+    }
+    else if (candidate.toLowerCase() === rootComparison.toLowerCase()) {
+        relativePath = "";
+        candidateRootPath = supplied.original;
+        admission = "identity";
+    }
+    else {
+        const rootWithSep = rootComparison.endsWith("\\") ? rootComparison : `${rootComparison}\\`;
+        const candidatePrefix = candidate.slice(0, rootWithSep.length);
+        if (candidatePrefix === rootWithSep) {
+            admission = "exact";
+        }
+        else if (candidatePrefix.toLowerCase() === rootWithSep.toLowerCase()) {
+            admission = "identity";
+        }
+        else {
+            return undefined;
+        }
+        relativePath = trimWindowsLeadingSeparators(candidate.slice(rootWithSep.length));
+        candidateRootPath = supplied.original.slice(0, supplied.originalIndex(rootComparison.length));
+    }
+    const rebasedPath = relativePath === ""
+        ? root
+        : `${root}${root.endsWith("\\") ? "" : "\\"}${relativePath}`;
+    return { candidateRootPath, path: rebasedPath, relativePath, admission };
+}
+function exactRootIdentity(rootPath, expected) {
+    if (typeof expected?.dev === "bigint" && typeof expected.ino === "bigint") {
+        return { dev: expected.dev, ino: expected.ino };
+    }
+    const observed = inspectDirectoryIdentitySync(rootPath);
+    return { dev: observed.dev, ino: observed.ino };
+}
+/**
+ * Admit a path at a trusted directory boundary.
+ *
+ * On Windows, an exact structural prefix is allocation-only and performs no
+ * filesystem observation. A match which depends on case folding is accepted
+ * only when the candidate prefix names the exact trusted root object. Accepted
+ * paths are always returned under the trusted root spelling.
+ */
+export function admitPathInsideRoot(params) {
+    // Some platform-fallback tests intentionally spoof process.platform while
+    // retaining Node's POSIX path module. A single-slash absolute root remains
+    // unambiguously POSIX; double-slash and slash-backslash roots are reserved
+    // for the synthetic Windows namespace cases below.
+    const usesPosixBoundary = process.platform !== "win32" || (path.sep === "/" &&
+        params.rootPath.startsWith("/") &&
+        params.rootPath[1] !== "/" &&
+        params.rootPath[1] !== "\\");
+    if (usesPosixBoundary) {
+        if (params.rootPath.startsWith("/") &&
+            params.candidatePath.startsWith("/") &&
+            !params.candidatePath.includes("/..") &&
+            (params.candidatePath === params.rootPath ||
+                (params.candidatePath.startsWith(params.rootPath) &&
+                    (params.rootPath.endsWith("/") || params.candidatePath[params.rootPath.length] === "/")))) {
+            const relativeStart = params.rootPath.endsWith("/")
+                ? params.rootPath.length
+                : params.rootPath.length + 1;
+            return {
+                admission: "exact",
+                path: params.candidatePath,
+                relativePath: params.candidatePath === params.rootPath
+                    ? ""
+                    : params.candidatePath.slice(relativeStart),
+            };
+        }
+        const root = path.resolve(params.rootPath);
+        const candidate = path.resolve(params.candidatePath);
+        const relativePath = path.relative(root, candidate);
+        if (isPathRelativeEscape(relativePath))
+            return undefined;
+        return { path: candidate, relativePath: relativePath === "." ? "" : relativePath, admission: "exact" };
+    }
+    const match = windowsRootPrefix(params.rootPath, params.candidatePath);
+    if (!match)
+        return undefined;
+    const admitted = () => ({
+        admission: match.admission,
+        path: match.path,
+        relativePath: match.relativePath,
+    });
+    if (match.admission === "exact")
+        return admitted();
+    const cached = params.identityCache?.get(match.candidateRootPath);
+    if (cached !== undefined)
+        return cached ? admitted() : undefined;
+    try {
+        const expected = exactRootIdentity(params.rootPath, params.rootIdentity);
+        const candidateRootPath = params.resolveCandidateRoot
+            ? realpathSync.native(match.candidateRootPath)
+            : match.candidateRootPath;
+        if (params.inspectCandidateRoot) {
+            params.inspectCandidateRoot(candidateRootPath, expected);
+        }
+        else {
+            inspectDirectoryIdentitySync(candidateRootPath, expected);
+        }
+        params.identityCache?.set(match.candidateRootPath, true);
+        return admitted();
+    }
+    catch {
+        params.identityCache?.set(match.candidateRootPath, false);
+        return undefined;
+    }
+}

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

@@ -0,0 +1,43 @@
+import fs, { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard, type DirectoryObservationGuard } from "./directory-guard.js";
+export type RootContext = {
+    rootDir: string;
+    rootGuard?: AsyncDirectoryGuard<BigIntStats>;
+    rootIdentity: {
+        dev: number;
+        ino: number;
+    } | {
+        dev: bigint;
+        ino: bigint;
+    };
+    rootReal: string;
+    rootWithSep: string;
+};
+export declare const ensureTrailingSep: (value: string) => string;
+export declare function assertValidRootRelativePath(relativePath: string): void;
+export declare function assertValidRootDestinationPath(relativePath: string): void;
+export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
+export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
+export declare function rootRelativeReadPath(root: RootContext, filePath: string): string;
+export declare function assertRootIdentityCurrentSync(root: RootContext, observe?: (stat: fs.BigIntStats) => void): void;
+export declare function assertRootIdentityCurrent(root: RootContext, observe?: (stat: fs.BigIntStats) => void): Promise<void>;
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export declare function createRootObservationGuard(root: RootContext): Promise<DirectoryObservationGuard | undefined>;
+export declare function resolvePathInRoot(root: RootContext, relativePath: string, options?: {
+    aliasErrorCode?: "outside-workspace" | "path-alias";
+    allowFinalSymlink?: boolean;
+    rejectUnsafeDeviceReads?: boolean;
+    rejectSymlinks?: boolean;
+    rejectFinalSymlink?: boolean;
+    resolveCanonical?: boolean;
+    rejectAmbiguousParents?: boolean;
+}): Promise<{
+    rootReal: string;
+    rootWithSep: string;
+    resolved: string;
+}>;

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

@@ -0,0 +1,233 @@
+import fs, {} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { extendDirectoryObservationGuard, inspectDirectoryIdentitySync, inspectDirectoryObservationSync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions, outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
+import { isDriveRelativePath } from "./safe-path-segment.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function hasExactRootIdentity(identity) {
+    return typeof identity.dev === "bigint" && typeof identity.ino === "bigint";
+}
+export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
+export function assertValidRootRelativePath(relativePath) {
+    assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
+    assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
+}
+export function assertValidRootDestinationPath(relativePath) {
+    assertValidRootRelativePath(relativePath);
+    if (isDriveRelativePath(relativePath)) {
+        throw new FsSafeError("invalid-path", "relative path must not start with a drive letter");
+    }
+}
+let cachedHomePath;
+const POSIX_PARENT_COMPONENT = /(?:^|\/)\.\.(?:\/|$)/;
+const WINDOWS_PARENT_COMPONENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+export async function expandRelativePathWithHome(relativePath) {
+    const homeOnly = relativePath === "~";
+    const homePrefix = relativePath.startsWith("~/") || (path.sep === "\\" && relativePath.startsWith("~\\"));
+    if (!homeOnly && !homePrefix) {
+        assertNoWindowsPathAlias(relativePath, "filesystem", "relative path uses a Windows filesystem namespace alias");
+        return relativePath;
+    }
+    const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    assertNoWindowsPathAlias(rawHome, "filesystem", "home path uses a Windows filesystem namespace alias");
+    if (cachedHomePath?.raw !== rawHome) {
+        let realHome = rawHome;
+        try {
+            realHome = realpathSync.native(pathForWindowsFilesystem(rawHome));
+        }
+        catch {
+            // If the home dir cannot be canonicalized, keep lexical expansion behavior.
+        }
+        cachedHomePath = { raw: rawHome, real: realHome };
+    }
+    if (homeOnly) {
+        assertNoWindowsPathAlias(cachedHomePath.real, "filesystem", "home path uses a Windows filesystem namespace alias");
+        return cachedHomePath.real;
+    }
+    const expanded = `${ensureTrailingSep(cachedHomePath.real)}${relativePath.slice(2)}`;
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    return expanded;
+}
+export async function resolveRootContext(rootDir) {
+    assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
+    assertNoWindowsPathAlias(rootDir, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    const lexicalRoot = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(lexicalRoot, "filesystem", "root dir uses a Windows filesystem namespace alias");
+    let rootReal;
+    let rootStat;
+    let rootIdentity;
+    try {
+        rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal, "filesystem", "canonical root path uses a Windows filesystem namespace alias");
+        rootStat = await inspectFileIdentity(() => {
+            const stat = fs.statSync(rootReal, { bigint: true });
+            if (!stat.isDirectory())
+                throw new FsSafeError("invalid-path", "root dir is not a directory");
+            return stat;
+        });
+        rootIdentity = { dev: rootStat.dev, ino: rootStat.ino };
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            throw err;
+        }
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("not-found", "root dir not found");
+        }
+        throw err;
+    }
+    return {
+        rootDir: lexicalRoot,
+        rootGuard: { dir: rootReal, realPath: rootReal, stat: rootStat },
+        rootIdentity,
+        rootReal,
+        rootWithSep: ensureTrailingSep(rootReal),
+    };
+}
+export function rootRelativeReadPath(root, filePath) {
+    const absoluteInput = path.isAbsolute(filePath);
+    if (!absoluteInput)
+        return filePath;
+    const raw = process.platform === "win32" ? filePath.replaceAll("/", path.sep) : filePath;
+    const bases = root.rootDir === root.rootReal ? [root.rootReal] : [root.rootDir, root.rootReal];
+    for (const base of bases) {
+        if (process.platform === "win32") {
+            const admitted = admitPathInsideRoot({
+                rootPath: base,
+                candidatePath: raw,
+                rootIdentity: root.rootIdentity,
+                resolveCandidateRoot: base === root.rootDir && root.rootDir !== root.rootReal,
+            });
+            if (admitted)
+                return `.${path.sep}${admitted.relativePath}`;
+            continue;
+        }
+        const prefix = ensureTrailingSep(base);
+        const matches = raw.startsWith(prefix);
+        if (matches) {
+            let start = prefix.length;
+            while (raw[start] === path.sep)
+                start += 1;
+            // An admitted absolute tail stays literal, including a leading home marker.
+            return `.${path.sep}${raw.slice(start)}`;
+        }
+    }
+    return raw;
+}
+export function assertRootIdentityCurrentSync(root, observe) {
+    let current;
+    try {
+        if (typeof root.rootIdentity.dev === "bigint" && typeof root.rootIdentity.ino === "bigint") {
+            const stat = inspectDirectoryIdentitySync(root.rootReal, { dev: root.rootIdentity.dev, ino: root.rootIdentity.ino });
+            observe?.(stat);
+            return;
+        }
+        current = fs.lstatSync(root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        !sameFileIdentity(current, root.rootIdentity)) {
+        throw rootPathChangedError();
+    }
+}
+export async function assertRootIdentityCurrent(root, observe) {
+    assertRootIdentityCurrentSync(root, observe);
+}
+/**
+ * Observe the current Root with an exact, operation-local receipt.
+ *
+ * This is deliberately separate from {@link assertRootIdentityCurrent}: callers
+ * must not retain the returned guard beyond the operation that requested it.
+ */
+export async function createRootObservationGuard(root) {
+    const rootIdentity = root.rootIdentity;
+    if (!hasExactRootIdentity(rootIdentity)) {
+        await assertRootIdentityCurrent(root);
+        return undefined;
+    }
+    try {
+        const observed = await inspectDirectoryObservationSync(root.rootReal, rootIdentity);
+        return extendDirectoryObservationGuard(observed, root.rootReal, root.rootReal);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+}
+export async function resolvePathInRoot(root, relativePath, options) {
+    assertValidRootRelativePath(relativePath);
+    await assertRootIdentityCurrent(root);
+    const expanded = await expandRelativePathWithHome(relativePath);
+    assertNoWindowsPathAlias(expanded, "filesystem", "expanded path uses a Windows filesystem namespace alias");
+    let resolved = resolvePathFromBasePreservingWindowsRoot(root.rootWithSep, expanded);
+    assertNoWindowsPathAlias(resolved, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+    if (!options?.resolveCanonical && !isPathInside(root.rootWithSep, resolved)) {
+        throw outsideWorkspaceError();
+    }
+    if (options?.rejectUnsafeDeviceReads === true) {
+        assertNoUnsafeDeviceReadPath(resolved);
+    }
+    const rawAbsolutePath = path.isAbsolute(expanded)
+        ? expanded
+        : `${root.rootWithSep}${expanded}`;
+    assertNoWindowsPathAlias(rawAbsolutePath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+    try {
+        const resolution = {
+            absolutePath: rawAbsolutePath,
+            rootPath: root.rootReal,
+            rootCanonicalPath: root.rootReal,
+            rootIdentity: root.rootIdentity,
+            boundaryLabel: "root",
+            policy: options?.allowFinalSymlink ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            rejectSymlinks: options?.rejectSymlinks,
+            rejectFinalSymlink: options?.rejectFinalSymlink,
+        };
+        const checked = await resolveRootPath(resolution);
+        const parentComponent = process.platform === "win32" ? WINDOWS_PARENT_COMPONENT : POSIX_PARENT_COMPONENT;
+        if (options?.rejectAmbiguousParents && parentComponent.test(expanded) &&
+            path.relative(checked.canonicalPath, resolved) !== "") {
+            const normalized = await resolveRootPath({ ...resolution, absolutePath: resolved });
+            if (path.relative(checked.canonicalPath, normalized.canonicalPath) !== "") {
+                throw new FsSafeError("path-alias", "parent traversal resolves differently through a symlink");
+            }
+        }
+        if (options?.resolveCanonical) {
+            resolved = checked.canonicalPath;
+        }
+        else {
+            // resolveRootPath preserves ordinary caller spelling as part of its
+            // public receipt. Re-admit the exact normalized spelling before it is
+            // reused for Root I/O: on a case-sensitive Windows directory it may
+            // otherwise name a distinct case-folded sibling after raw traversal.
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: checked.absolutePath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            resolved = admitted.path;
+        }
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "symlink") {
+            throw error;
+        }
+        if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
+        }
+        const code = options?.aliasErrorCode ?? "outside-workspace";
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
+    }
+    return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
+}

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

@@ -0,0 +1,16 @@
+import type { PinnedWriteInput } from "./pinned-write-types.js";
+import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+declare const exclusiveSidecarCreate: unique symbol;
+export declare const sidecarExclusiveCreate: Readonly<{
+    [exclusiveSidecarCreate]: true;
+}>;
+export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
+    relativePath: string;
+    data: string | Buffer | AsyncIterable<Uint8Array>;
+    strictFileSync?: boolean;
+    [exclusiveSidecarCreate]?: true;
+};
+export declare function rethrowCreateInputError(error: unknown): never;
+export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
+export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
+export {};