@openclaw/openshell-sandbox 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/windows-security-command.js

@@ -0,0 +1,414 @@
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { FsSafeError } from "./errors.js";
+import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
+import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { parseWindowsOwnerAndDaclFacts, parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const TERMINATION_GRACE_MS = 1_000;
+const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+export const WINDOWS_SECURITY_BATCH_MAX_BYTES = 16 * 1024 * 1024;
+function isFullIdentity(identity) {
+    return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
+}
+function assertIdentity(identity) {
+    if (!isFullIdentity(identity)) {
+        throw new TypeError("Windows security operation requires a complete file identity");
+    }
+}
+function command(operation, params) {
+    const targetPath = params.targetPath ?? "";
+    // Preserve native EINVAL before child-process environment validation runs.
+    if (targetPath.includes("\0")) {
+        throw Object.assign(new Error("Windows path contains a NUL byte"), { code: "EINVAL" });
+    }
+    if (params.fd !== undefined || operation === "descriptor" || operation === "protect-file" || operation === "verify-file") {
+        if (typeof params.fd !== "number" || !Number.isInteger(params.fd) || params.fd < 0 || params.fd > 0x7fff_ffff) {
+            unverified("Windows security inspection requires a valid descriptor");
+        }
+    }
+    if (params.expectedParentIdentity !== undefined)
+        assertIdentity(params.expectedParentIdentity);
+    if (params.expectedFileIdentity !== undefined)
+        assertIdentity(params.expectedFileIdentity);
+    if (params.expectedLinks !== undefined &&
+        (!Number.isInteger(params.expectedLinks) || params.expectedLinks < 1 || params.expectedLinks > 0xffff_ffff)) {
+        throw new TypeError("Windows security operation requires a positive uint32 link count");
+    }
+    const script = fileURLToPath(new URL("./windows-security-bridge.ps1", import.meta.url));
+    return {
+        file: resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`),
+        args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", script, "-Operation", operation],
+        // Preserve Windows UTF-16 spelling and leave long paths out of the bounded
+        // command line. This overrides any inherited value only in this child.
+        env: {
+            ...process.env,
+            FS_SAFE_WINDOWS_SECURITY_PATH: targetPath,
+            FS_SAFE_WINDOWS_SECURITY_REQUIRE_PRIVATE: params.requirePrivate ? "1" : "0",
+            FS_SAFE_WINDOWS_SECURITY_PARENT_IDENTITY: params.expectedParentIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_FILE_IDENTITY: params.expectedFileIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_EXPECTED_LINKS: String(params.expectedLinks ?? 1),
+        },
+    };
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReply(stdout, operation) {
+    try {
+        return parseReplyValue(stdout, operation);
+    }
+    catch (error) {
+        if (operation === "create" && error instanceof Error && error.code !== "EEXIST") {
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        }
+        throw error;
+    }
+}
+function parseReplyValue(stdout, operation) {
+    let response;
+    try {
+        response = JSON.parse(stdout.trim());
+    }
+    catch (cause) {
+        unverified("Windows security command returned invalid data", cause);
+    }
+    if (!record(response) || typeof response.ok !== "boolean") {
+        unverified("Windows security command returned an incomplete response");
+    }
+    if (!response.ok) {
+        if (operation === "paths" &&
+            (response.code === "helper-unavailable" || response.code === "too-large") && typeof response.message === "string") {
+            throw new FsSafeError(response.code, response.message);
+        }
+        const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
+        if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
+            unverified("Windows security command returned an invalid failure");
+        }
+        throw Object.assign(new Error(response.message), { code: response.code });
+    }
+    if (operation === "create" && (!record(response.result) || response.result.created !== true || !isFullIdentity(response.result.identity))) {
+        unverified("Windows security command did not verify private-directory creation");
+    }
+    return response.result;
+}
+function executeSync(operation, params) {
+    const { file, args, env } = command(operation, params);
+    const startedAt = performance.now();
+    const result = spawnSync(file, args, {
+        encoding: "utf8", windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"],
+        timeout: DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: MAX_OUTPUT_BYTES,
+    });
+    if (result.error || result.status !== 0) {
+        const error = new PermissionCommandError(file, performance.now() - startedAt, {
+            cause: result.error, code: result.status,
+            signal: result.error?.code === "ETIMEDOUT" ? "SIGKILL" : result.signal,
+            stderr: result.stderr,
+            killed: result.error?.code === "ETIMEDOUT",
+            ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+        });
+        if (operation === "create")
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        throw error;
+    }
+    return parseReply(result.stdout, operation);
+}
+class WindowsSecurityCommandError extends PermissionCommandError {
+    timedOut;
+    creationOutcome;
+    processExitConfirmed;
+    constructor(file, durationMs, receipt, timedOut, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+        super(file, durationMs, receipt, timeoutMs);
+        this.timedOut = timedOut;
+        this.creationOutcome = receipt.creationOutcome;
+        this.processExitConfirmed = receipt.processExitConfirmed;
+        if (timedOut)
+            this.message = `Windows permission inspection timed out after ${timeoutMs}ms`;
+        if (!receipt.processExitConfirmed)
+            this.message += "; process exit was not confirmed";
+        else if (!receipt.outputClosed)
+            this.message += "; command output did not close";
+        if (receipt.creationOutcome)
+            this.message += "; private-directory creation outcome is unconfirmed";
+    }
+}
+/** Cleanup must preserve stages still reachable by an unsettled command. */
+export function hasUnsettledWindowsSecurityCommand(error) {
+    const pending = [error];
+    const seen = new Set();
+    for (let inspected = 0; pending.length && inspected < 32; inspected++) {
+        const current = pending.pop();
+        if (current === null || typeof current !== "object" || seen.has(current))
+            continue;
+        seen.add(current);
+        try {
+            if (current instanceof WindowsSecurityCommandError && !current.processExitConfirmed)
+                return true;
+            const cause = Object.getOwnPropertyDescriptor(current, "cause");
+            if (cause && "value" in cause)
+                pending.push(cause.value);
+            if (current instanceof AggregateError) {
+                const errors = Object.getOwnPropertyDescriptor(current, "errors");
+                if (errors && "value" in errors && Array.isArray(errors.value))
+                    pending.push(...errors.value.slice(0, 32));
+            }
+        }
+        catch {
+            // Unknown error wrappers cannot prove that command-owned handles settled.
+            return true;
+        }
+    }
+    return pending.length > 0;
+}
+function ignoreLateError() { }
+async function execute(operation, params, request) {
+    const selected = request ?? command(operation, params);
+    const { file, args, env, input, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, maxOutputBytes = MAX_OUTPUT_BYTES } = selected;
+    const startedAt = performance.now();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [input === undefined ? params.fd ?? "ignore" : "pipe", "pipe", "pipe"] });
+        const output = [];
+        const errors = [];
+        let bytes = 0;
+        let failure;
+        let failed = false;
+        let timedOut = false;
+        let stopping = false;
+        let settled = false;
+        let processExitConfirmed = false;
+        let exitCode = null;
+        let exitSignal = null;
+        let terminationSignalSent;
+        let terminationError;
+        let grace;
+        let missingPipes;
+        const deadlineError = () => new Error("Windows security command exceeded its inspection deadline");
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            fail(deadlineError());
+        }, timeoutMs);
+        const finish = (outputClosed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            clearTimeout(grace);
+            clearImmediate(missingPipes);
+            child.removeListener("exit", onExit);
+            child.removeListener("close", onClose);
+            child.removeListener("error", onChildError);
+            child.on("error", ignoreLateError);
+            const cleanupErrors = [];
+            if (input !== undefined && child.stdin) {
+                child.stdin.removeListener("error", fail);
+                child.stdin.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        child.stdin.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
+            for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
+                if (!stream)
+                    continue;
+                stream.removeListener("data", collect);
+                stream.removeListener("error", fail);
+                stream.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        stream.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
+            if (!outputClosed && !processExitConfirmed) {
+                try {
+                    child.unref();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+            }
+            if (failed || exitCode !== 0 || !outputClosed) {
+                reject(new WindowsSecurityCommandError(file, performance.now() - startedAt, {
+                    cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
+                    processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
+                    ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+                }, timedOut, timeoutMs));
+            }
+            else {
+                try {
+                    resolve(parseReply(Buffer.concat(output).toString("utf8"), operation));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }
+            output.length = 0;
+            errors.length = 0;
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            if (!failed) {
+                failed = true;
+                failure = error;
+            }
+            if (stopping)
+                return;
+            stopping = true;
+            clearTimeout(timeout);
+            // kill() can synchronously emit error, throw, or return false. None proves exit.
+            grace = setTimeout(() => finish(false), TERMINATION_GRACE_MS);
+            if (!processExitConfirmed) {
+                try {
+                    terminationSignalSent = child.kill("SIGKILL");
+                }
+                catch (error) {
+                    terminationError ??= error;
+                }
+            }
+        };
+        const collect = (chunks) => (chunk) => {
+            if (failed || settled)
+                return;
+            bytes += chunk.length;
+            if (bytes <= maxOutputBytes)
+                chunks.push(chunk);
+            else
+                fail(new Error("Windows security command exceeded its output budget"));
+        };
+        const collectOutput = collect(output);
+        const collectErrors = collect(errors);
+        const onChildError = (error) => {
+            if (settled)
+                return;
+            if (stopping)
+                terminationError ??= error;
+            else
+                fail(error);
+        };
+        const onExit = (code, signal) => {
+            processExitConfirmed = true;
+            exitCode = code;
+            exitSignal = signal;
+        };
+        const onClose = (code, signal) => {
+            onExit(code, signal);
+            if (!failed && performance.now() - startedAt >= timeoutMs) {
+                timedOut = true;
+                failed = true;
+                failure = deadlineError();
+            }
+            finish(true);
+        };
+        child.on("error", onChildError);
+        child.once("exit", onExit);
+        // Success still joins exit and both pipes. Failure releases only owned endpoints
+        // after grace; the child inherited its own HANDLE, independent of the caller fd.
+        child.once("close", onClose);
+        child.stdout?.on("error", fail);
+        child.stderr?.on("error", fail);
+        child.stdout?.on("data", collectOutput);
+        child.stderr?.on("data", collectErrors);
+        if (!child.stdout || !child.stderr || (input !== undefined && !child.stdin)) {
+            // Node reports spawn errors on nextTick, which can follow the current microtask.
+            missingPipes = setImmediate(() => { if (!failed && !settled)
+                fail(new Error("Windows security command output pipes are unavailable")); });
+        }
+        if (input !== undefined && child.stdin) {
+            child.stdin.on("error", fail);
+            try {
+                child.stdin.end(input, "utf8");
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    });
+}
+export async function readWindowsSecurityFactsBatch(paths, options) {
+    const invocation = command("paths", {});
+    const request = {
+        ...invocation,
+        input: JSON.stringify(paths),
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: WINDOWS_SECURITY_BATCH_MAX_BYTES,
+    };
+    if (options.native) {
+        request.file = process.execPath;
+        request.args = ["--", fileURLToPath(new URL("./owner-dacl-batch-worker.js", import.meta.url))];
+        request.env = {
+            ...Object.fromEntries(Object.entries(invocation.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH", "FS_SAFE_OWNER_DACL_BATCH_MODE"].includes(key.toUpperCase()))),
+            FS_SAFE_OWNER_DACL_BATCH_MODE: options.mode,
+        };
+    }
+    const response = await execute("paths", {}, request);
+    if (!Array.isArray(response) || response.length !== paths.length) {
+        unverified("Windows security command returned an incomplete path batch");
+    }
+    return response.map((row, index) => {
+        if (!record(row) || row.path !== paths[index]) {
+            unverified("Windows security command returned a mismatched path batch");
+        }
+        return parseWindowsOwnerAndDaclFacts(row.security);
+    });
+}
+export function readWindowsSecurityFactsCommand(targetPath) {
+    return parseWindowsSecurityCommandFacts(executeSync("path", { targetPath }));
+}
+export async function inspectWindowsDescriptorCommand(fd) {
+    const response = await execute("descriptor", { fd });
+    if (!record(response) || typeof response.identity !== "string") {
+        unverified("Windows security command returned incomplete handle facts");
+    }
+    return { identity: response.identity, security: parseWindowsSecurityCommandFacts(response.security) };
+}
+export async function createPrivateWindowsDirectoryCommand(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(await execute("create", { targetPath, expectedParentIdentity }));
+}
+export function createPrivateWindowsDirectoryCommandSync(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(executeSync("create", { targetPath, expectedParentIdentity }));
+}
+function fullIdentityReceipt(response, expected) {
+    if (!record(response) || !isFullIdentity(response.identity)) {
+        unverified("Windows security command returned an incomplete file identity");
+    }
+    if (expected !== undefined && response.identity !== expected) {
+        throw new FsSafeError("path-mismatch", "Windows security command observed a different file");
+    }
+    return { identity: response.identity };
+}
+export function inspectWindowsDirectoryCommandSync(targetPath, requirePrivate) {
+    return fullIdentityReceipt(executeSync("directory", { targetPath, requirePrivate }));
+}
+export async function inspectWindowsDirectoryCommand(targetPath, requirePrivate) {
+    return fullIdentityReceipt(await execute("directory", { targetPath, requirePrivate }));
+}
+export function protectPrivateWindowsFileCommandSync(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(executeSync("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export async function protectPrivateWindowsFileCommand(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(await execute("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export function verifyPrivateWindowsFileCommandSync(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(executeSync("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}
+export async function verifyPrivateWindowsFileCommand(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(await execute("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.d.ts

@@ -0,0 +1,9 @@
+import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export type DescriptorFacts = Pick<NativeWindowsSecurityFacts, "ownerSid" | "currentUserSid" | "daclPresent" | "isLocal" | "aceListComplete" | "unsupportedAceTypes" | "aces">;
+export declare function unverified(message: string, cause?: unknown): never;
+/** Validate policy-free observations crossing the isolated batch transport. */
+export declare function parseWindowsOwnerAndDaclFacts(value: unknown): DescriptorFacts;
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
+/** Native and command observations share the same fail-closed admission policy. */
+export declare function validateSecureWindowsSecurityFacts(value: unknown): NativeWindowsSecurityFacts;

package/node_modules/@openclaw/fs-safe/dist/windows-security-facts.js

@@ -0,0 +1,112 @@
+import { FsSafeError } from "./errors.js";
+const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
+const SYSTEM_SID = "s-1-5-18";
+const ADMINISTRATORS_SID = "s-1-5-32-544";
+const WORLD_SIDS = new Set([
+    "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
+    "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
+]);
+export function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function uint32(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff;
+}
+function validateAce(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.sid !== "string" || !SID_RE.test(value.sid) ||
+        !uint32(value.mask) || (value.aceType !== "allow" && value.aceType !== "deny") ||
+        !record(value.flags))
+        return false;
+    const { raw } = value.flags;
+    if (!uint32(raw) || (raw & ~(allowUnknownFlags ? 0xff : 0xdf)) !== 0)
+        return false;
+    const fields = [
+        ["objectInherit", 0x01], ["containerInherit", 0x02],
+        ["noPropagateInherit", 0x04], ["inheritOnly", 0x08], ["inherited", 0x10],
+        ["successfulAccess", 0x40], ["failedAccess", 0x80],
+    ];
+    const flags = value.flags;
+    return fields.every(([field, bit]) => typeof flags[field] === "boolean" && flags[field] === ((raw & bit) !== 0));
+}
+function validateDescriptor(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.ownerSid !== "string" || !SID_RE.test(value.ownerSid) ||
+        typeof value.currentUserSid !== "string" || !SID_RE.test(value.currentUserSid) ||
+        typeof value.daclPresent !== "boolean" || typeof value.isLocal !== "boolean" ||
+        typeof value.aceListComplete !== "boolean" || !Array.isArray(value.unsupportedAceTypes) ||
+        !value.unsupportedAceTypes.every(uint32) || !Array.isArray(value.aces) ||
+        !value.aces.every(ace => validateAce(ace, allowUnknownFlags))) {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if ((!value.daclPresent && value.aces.length !== 0) ||
+        (value.aceListComplete && value.unsupportedAceTypes.length !== 0)) {
+        unverified("Windows descriptor DACL facts were inconsistent");
+    }
+    return value;
+}
+/** Validate policy-free observations crossing the isolated batch transport. */
+export function parseWindowsOwnerAndDaclFacts(value) {
+    return validateDescriptor(value, true);
+}
+function summarize(facts) {
+    const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
+        : facts.ownerSid === SYSTEM_SID ? "system"
+            : facts.ownerSid === ADMINISTRATORS_SID ? "administrators" : "foreign";
+    let worldReadable = !facts.daclPresent;
+    let worldWritable = !facts.daclPresent;
+    let groupReadable = false;
+    let groupWritable = false;
+    const trusted = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
+    for (const ace of facts.aces) {
+        if (ace.aceType !== "allow" || ace.flags.inheritOnly || trusted.has(ace.sid))
+            continue;
+        // Generic and file-specific read/write, delete, and security-control rights.
+        const canRead = (ace.mask & 0x9000_0089) !== 0;
+        const canWrite = (ace.mask & 0x500d_0156) !== 0;
+        if (WORLD_SIDS.has(ace.sid)) {
+            worldReadable ||= canRead;
+            worldWritable ||= canWrite;
+        }
+        else {
+            groupReadable ||= canRead;
+            groupWritable ||= canWrite;
+        }
+    }
+    return { ownerClass, worldReadable, worldWritable, groupReadable, groupWritable };
+}
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export function parseWindowsSecurityCommandFacts(value) {
+    const facts = validateDescriptor(value, true);
+    if (!record(value) || typeof value.daclProtected !== "boolean") {
+        unverified("Windows security command returned malformed descriptor facts");
+    }
+    return {
+        ...facts,
+        ...summarize(facts),
+        fallbackRequired: !facts.isLocal || !facts.aceListComplete,
+    };
+}
+/** Native and command observations share the same fail-closed admission policy. */
+export function validateSecureWindowsSecurityFacts(value) {
+    const descriptor = validateDescriptor(value, false);
+    const facts = value;
+    const summary = summarize(descriptor);
+    const booleans = ["worldWritable", "groupWritable", "worldReadable", "groupReadable", "fallbackRequired"];
+    if (!booleans.every(field => typeof facts[field] === "boolean") ||
+        typeof facts.ownerClass !== "string") {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if (facts.ownerClass !== summary.ownerClass) {
+        unverified("Windows descriptor owner facts were inconsistent");
+    }
+    if (facts.fallbackRequired || !facts.isLocal || !facts.aceListComplete || facts.unsupportedAceTypes.length !== 0) {
+        unverified("Windows descriptor ACL facts were incomplete or unsupported");
+    }
+    if (facts.worldReadable !== summary.worldReadable || facts.worldWritable !== summary.worldWritable ||
+        facts.groupReadable !== summary.groupReadable || facts.groupWritable !== summary.groupWritable) {
+        unverified("Windows descriptor ACL summary was inconsistent");
+    }
+    return facts;
+}

package/node_modules/@openclaw/fs-safe/dist/write-file-handle.d.ts

@@ -1,7 +1,13 @@
 import type { FileHandle } from "node:fs/promises";
+export type WriteFileWindowOptions = {
+    signal?: AbortSignal;
+    /** Synchronous authority check immediately before every write, including short-write retries. */
+    assertBeforeMutation?: () => void;
+};
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export declare function writeFileWindowFully(handle: FileHandle, bytes: Uint8Array, position: number | null, options?: WriteFileWindowOptions): Promise<void>;
 export declare function writeAllToFile(target: FileHandle | number, data: string | Uint8Array, options?: {
     encoding?: BufferEncoding;
     position?: number;
     assertBeforeMutation?: () => void;
 }): Promise<void>;
-//# sourceMappingURL=write-file-handle.d.ts.map

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

@@ -1,6 +1,29 @@
 import fs from "node:fs";
+import { snapshotByteView } from "./byte-view.js";
 import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 const WRITE_CHUNK_BYTES = 512 * 1024;
+/** Write borrowed bytes completely; null advances the cursor, an explicit position preserves it. */
+export async function writeFileWindowFully(handle, bytes, position, options = {}) {
+    const payload = snapshotByteView(bytes);
+    if (position !== null && (!Number.isSafeInteger(position) || position < 0 ||
+        !Number.isSafeInteger(position + payload.byteLength))) {
+        throw new RangeError("write position and window end must be non-negative safe integers");
+    }
+    const signal = options.signal;
+    const assertion = options.assertBeforeMutation;
+    signal?.throwIfAborted();
+    await writeAllToFile(handle, payload, {
+        position: position === null ? undefined : position,
+        assertBeforeMutation: () => {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertion === undefined ? undefined : Reflect.apply(assertion, options, []), "assertBeforeMutation");
+            signal?.throwIfAborted();
+        },
+    });
+    // A pending write must settle before cancellation releases the caller's buffer and handle.
+    signal?.throwIfAborted();
+}
 export async function writeAllToFile(target, data, options = {}) {
     const buffer = typeof data === "string" ? Buffer.from(data, options.encoding ?? "utf8") : data;
     let offset = 0;

package/node_modules/@openclaw/fs-safe/dist/write-open-flags.d.ts

@@ -2,4 +2,3 @@ import fsSync from "node:fs";
 export declare function resolveNonblockingWriteFlag(constants?: Partial<Pick<typeof fsSync.constants, "O_NONBLOCK">>): number;
 export declare function isNonRegularWriteOpenError(error: unknown, filePath: string, flags: number): Promise<boolean>;
 export declare function isNonRegularWriteOpenErrorSync(error: unknown, filePath: string, flags: number): boolean;
-//# sourceMappingURL=write-open-flags.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/write-open-flags.js

@@ -13,14 +13,7 @@ function isNonblockingWriteEnxio(error, flags) {
 // A no-reader FIFO rejects a nonblocking write-only open before fstat is possible.
 // Reclassify only a confirmed non-regular path; inconclusive races keep the errno.
 export async function isNonRegularWriteOpenError(error, filePath, flags) {
-    if (!isNonblockingWriteEnxio(error, flags))
-        return false;
-    try {
-        return !fsSync.lstatSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
+    return isNonRegularWriteOpenErrorSync(error, filePath, flags);
 }
 export function isNonRegularWriteOpenErrorSync(error, filePath, flags) {
     if (!isNonblockingWriteEnxio(error, flags))

package/node_modules/@openclaw/fs-safe/dist/write-queue.d.ts

@@ -1,2 +1 @@
 export declare function serializePathWrite<T>(key: string, run: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=write-queue.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/write-queue.js

@@ -1,10 +1,7 @@
 const writeQueues = new Map();
 export async function serializePathWrite(key, run) {
     const previous = writeQueues.get(key) ?? Promise.resolve();
-    const task = (async () => {
-        await previous.catch(() => undefined);
-        return await run();
-    })();
+    const task = previous.then(() => run());
     const done = task.then(() => undefined, () => undefined);
     writeQueues.set(key, done);
     try {