@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/temp-workspace-owner.js

@@ -0,0 +1,320 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createAsyncDirectoryGuard, createSyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { withAsyncDirectoryGuards, withSyncDirectoryGuards } from "./guarded-mutation.js";
+import { getNativeBinding } from "./native.js";
+import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function isNativeCleanupBinding(binding) {
+    return typeof binding?.renameNoReplace === "function" &&
+        typeof binding.removeOwnedTree === "function" &&
+        typeof binding.removeOwnedTreeSync === "function" &&
+        typeof binding.ownedTreeRemovalAvailable === "function";
+}
+function nativeRemovalError(result) {
+    if (!result.errorCode)
+        return undefined;
+    return Object.assign(new Error(result.errorMessage ?? "native owned-tree cleanup failed"), {
+        code: result.errorCode,
+    });
+}
+export class TempWorkspaceCleanupCapability {
+    binding;
+    parent;
+    #ownedTreeRemovalAvailable;
+    #closed = false;
+    constructor(root, safety) {
+        let binding;
+        try {
+            binding = getNativeBinding();
+        }
+        catch (error) {
+            if (safety === "require-bounded")
+                throw error;
+        }
+        this.binding = binding;
+        let parent;
+        try {
+            parent = openStagedDirectory(root);
+            assertStagedDirectoryCurrent(parent.receipt);
+        }
+        catch {
+            if (parent)
+                fsSync.closeSync(parent.fd);
+            parent = undefined;
+        }
+        this.parent = parent;
+        let available = false;
+        if (parent && isNativeCleanupBinding(binding)) {
+            try {
+                available = binding.ownedTreeRemovalAvailable(parent.fd) === true;
+            }
+            catch {
+                // Runtime denial must select fallback or reject before child creation.
+            }
+        }
+        this.#ownedTreeRemovalAvailable = available;
+        if (safety === "require-bounded" && !this.canRemoveOwnedTree) {
+            this.close();
+            throw new FsSafeError("helper-unavailable", "temp workspace owned-tree cleanup is unavailable");
+        }
+    }
+    get canRemoveOwnedTree() {
+        return !this.#closed && this.#ownedTreeRemovalAvailable;
+    }
+    assertCurrent() {
+        if (this.#closed || !this.parent) {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent is unavailable");
+        }
+        assertStagedDirectoryCurrent(this.parent.receipt);
+        const current = fsSync.fstatSync(this.parent.fd, { bigint: true });
+        if (!sameFileIdentityForCleanup(current, this.parent.receipt.identity)) {
+            throw new FsSafeError("path-mismatch", "temp workspace cleanup parent changed");
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        if (this.parent)
+            fsSync.closeSync(this.parent.fd);
+    }
+}
+export class TempWorkspaceCleanupOwner {
+    #dir;
+    #identity;
+    #capability;
+    #directory;
+    #closed = false;
+    #running = false;
+    #exitInterrupted = false;
+    #result;
+    #pending;
+    constructor(dir, identity, capability) {
+        this.#dir = dir;
+        this.#identity = { dev: identity.dev, ino: identity.ino };
+        this.#capability = capability;
+        let directory;
+        if (capability.canRemoveOwnedTree) {
+            directory = openStagedDirectory(dir);
+            const current = fsSync.fstatSync(directory.fd, { bigint: true });
+            if (!sameFileIdentityForCleanup(current, this.#identity)) {
+                fsSync.closeSync(directory.fd);
+                capability.close();
+                throw new FsSafeError("path-mismatch", "temp workspace changed while retaining cleanup authority");
+            }
+        }
+        this.#directory = directory;
+    }
+    #repeat() {
+        return this.#result === "removed" ? "missing" : this.#result;
+    }
+    #close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const errors = [];
+        if (this.#directory) {
+            try {
+                fsSync.closeSync(this.#directory.fd);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        try {
+            this.#capability.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "temp workspace cleanup descriptor close failed");
+    }
+    #finish(result) {
+        this.#result ??= this.#exitInterrupted ? "indeterminate" : result;
+        try {
+            this.#close();
+        }
+        catch (error) {
+            this.#result = "indeterminate";
+            throw error;
+        }
+        return this.#result;
+    }
+    #fallbackResult() {
+        try {
+            const current = fsSync.lstatSync(this.#dir, { bigint: true });
+            return current.isDirectory() && !current.isSymbolicLink() &&
+                sameFileIdentityForCleanup(current, this.#identity)
+                ? "indeterminate"
+                : "identity-mismatch";
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? "missing" : "indeterminate";
+        }
+    }
+    #prepare() {
+        const parent = this.#capability.parent;
+        if (!parent)
+            return this.#fallbackResult();
+        try {
+            this.#capability.assertCurrent();
+            let current;
+            try {
+                current = fsSync.lstatSync(this.#dir, { bigint: true });
+            }
+            catch (error) {
+                this.#capability.assertCurrent();
+                return error.code === "ENOENT" ? "missing" : "indeterminate";
+            }
+            this.#capability.assertCurrent();
+            if (!current.isDirectory() || current.isSymbolicLink() ||
+                !sameFileIdentityForCleanup(current, this.#identity)) {
+                return "identity-mismatch";
+            }
+            const name = `.fs-safe-workspace-cleanup-${randomUUID()}`;
+            const quarantinePath = path.join(parent.receipt.path, name);
+            const nativeRemoval = this.#capability.canRemoveOwnedTree && this.#directory !== undefined;
+            if (nativeRemoval) {
+                this.#capability.binding.renameNoReplace(parent.fd, path.basename(this.#dir), parent.fd, name);
+            }
+            else {
+                const guard = createSyncDirectoryGuard(parent.receipt.path);
+                withSyncDirectoryGuards([guard], () => {
+                    this.#capability.assertCurrent();
+                    fsSync.renameSync(this.#dir, quarantinePath);
+                });
+            }
+            this.#capability.assertCurrent();
+            const quarantined = fsSync.lstatSync(quarantinePath, { bigint: true });
+            this.#capability.assertCurrent();
+            if (!quarantined.isDirectory() || quarantined.isSymbolicLink() ||
+                !sameFileIdentityForCleanup(quarantined, this.#identity)) {
+                return "indeterminate";
+            }
+            return { name, path: quarantinePath, nativeRemoval };
+        }
+        catch {
+            // A failed rename can still have committed on a remote filesystem.
+            return "indeterminate";
+        }
+    }
+    #assertQuarantine(quarantine) {
+        const current = fsSync.lstatSync(quarantine.path, { bigint: true });
+        if (!current.isDirectory() || current.isSymbolicLink() ||
+            !sameFileIdentityForCleanup(current, this.#identity)) {
+            throw new FsSafeError("path-mismatch", "temp workspace quarantine changed");
+        }
+        this.#capability.assertCurrent();
+    }
+    #mapRemoval(result) {
+        const error = nativeRemovalError(result);
+        if (error) {
+            if (error.code === "path-mismatch")
+                return "indeterminate";
+            throw error;
+        }
+        return result.outcome === "removed" ? "removed" : "indeterminate";
+    }
+    async #remove(quarantine) {
+        if (quarantine.nativeRemoval) {
+            const beforeNativeRemoval = getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemoval;
+            if (beforeNativeRemoval)
+                await beforeNativeRemoval(quarantine.path);
+            return this.#mapRemoval(await this.#capability.binding.removeOwnedTree(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
+        }
+        let removalError;
+        try {
+            const guard = await createAsyncDirectoryGuard(this.#capability.parent.receipt.path);
+            await withAsyncDirectoryGuards([guard], async () => {
+                this.#assertQuarantine(quarantine);
+                try {
+                    await fs.rm(quarantine.path, { recursive: true, force: true });
+                }
+                catch (error) {
+                    removalError = error;
+                    throw error;
+                }
+            });
+            return "removed";
+        }
+        catch (error) {
+            if (error === removalError)
+                throw error;
+            return "indeterminate";
+        }
+    }
+    #removeSync(quarantine) {
+        if (quarantine.nativeRemoval) {
+            getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemovalSync?.(quarantine.path);
+            return this.#mapRemoval(this.#capability.binding.removeOwnedTreeSync(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
+        }
+        let removalError;
+        try {
+            const guard = createSyncDirectoryGuard(this.#capability.parent.receipt.path);
+            withSyncDirectoryGuards([guard], () => {
+                this.#assertQuarantine(quarantine);
+                try {
+                    fsSync.rmSync(quarantine.path, { recursive: true, force: true });
+                }
+                catch (error) {
+                    removalError = error;
+                    throw error;
+                }
+            });
+            return "removed";
+        }
+        catch (error) {
+            if (error === removalError)
+                throw error;
+            return "indeterminate";
+        }
+    }
+    async #run() {
+        let result = "indeterminate";
+        try {
+            const prepared = this.#prepare();
+            result = typeof prepared === "string" ? prepared : await this.#remove(prepared);
+            return this.#finish(result);
+        }
+        finally {
+            if (!this.#closed)
+                this.#finish(result);
+        }
+    }
+    cleanup() {
+        if (this.#result)
+            return Promise.resolve(this.#repeat());
+        if (this.#pending)
+            return this.#pending.then(() => this.#repeat());
+        this.#running = true;
+        this.#pending = this.#run();
+        return this.#pending;
+    }
+    cleanupSync() {
+        if (this.#result)
+            return this.#repeat();
+        if (this.#running) {
+            this.#exitInterrupted = true;
+            return "indeterminate";
+        }
+        this.#running = true;
+        let result = "indeterminate";
+        try {
+            const prepared = this.#prepare();
+            result = typeof prepared === "string" ? prepared : this.#removeSync(prepared);
+            return this.#finish(result);
+        }
+        finally {
+            if (!this.#closed)
+                this.#finish(result);
+        }
+    }
+}

package/dist/temp.d.ts

@@ -1,4 +1,4 @@
-export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, type TempWorkspaceCleanupResult, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, type TempWorkspaceCleanupResult, type TempWorkspaceCleanupSafety, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
 export type { TempPathIdentityReceipt } from "./temp-cleanup.js";
 export { resolveSecureTempRoot, type ResolveSecureTempRootOptions } from "./secure-temp-dir.js";
 //# sourceMappingURL=temp.d.ts.map

package/dist/temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp.d.ts","sourceRoot":"","sources":["../src/temp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"temp.d.ts","sourceRoot":"","sources":["../src/temp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/test-hooks.d.ts

@@ -4,6 +4,7 @@ export type FsSafeTestHooks = {
     afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
     beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
     afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+    afterOpenedPathIdentityCheck?: (filePath: string, handle: FileHandle) => Promise<void> | void;
     beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
     beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
     beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
@@ -11,6 +12,10 @@ export type FsSafeTestHooks = {
     afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
     beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
     beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
+    beforeRegularFileAppendOpen?: (filePath: string) => Promise<void> | void;
+    beforeRegularFileAppendOpenSync?: (filePath: string) => void;
+    beforeTempWorkspaceNativeRemoval?: (quarantinePath: string) => Promise<void> | void;
+    beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
     beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;

package/dist/test-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,6BAA6B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}
+{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,4BAA4B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9F,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,6BAA6B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACzE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,gCAAgC,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpF,oCAAoC,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/windows-owner.d.ts

@@ -1,3 +1,4 @@
+import { type PermissionCommandFailure } from "./permission-exec.js";
 export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
@@ -10,6 +11,8 @@ export type WindowsOwnerSummary = {
     remote?: boolean;
     trusted?: boolean;
     error?: string;
+    errorDetail?: PermissionCommandFailure;
+    errorCause?: unknown;
 };
 export declare function resolveWindowsPrincipalSids(params: {
     principals: string[];

package/dist/windows-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2C/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAkD/B"}

package/dist/windows-owner.js

@@ -1,3 +1,4 @@
+import { formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
 const TRUSTED_OWNER_SIDS = new Set(["s-1-5-18", "s-1-5-32-544"]);
@@ -83,8 +84,11 @@ export async function resolveWindowsCurrentUserSid(params) {
     }
 }
 export async function inspectWindowsOwner(params) {
+    let command = "";
+    let startedAt = performance.now();
     try {
-        const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        startedAt = performance.now();
         const { stdout } = await params.exec(command, [
             "-NoLogo",
             "-NoProfile",
@@ -113,6 +117,10 @@ export async function inspectWindowsOwner(params) {
         };
     }
     catch (err) {
-        return { error: String(err) };
+        return {
+            error: formatPermissionErrorDetail(String(err)),
+            errorDetail: getPermissionCommandFailure(err, command, performance.now() - startedAt),
+            errorCause: err,
+        };
     }
 }

package/docs/advanced.md

@@ -26,13 +26,22 @@ The exports group into a handful of themes. Each documented helper has its own p
 | Export | Page | Notes |
 |---|---|---|
 | `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-scope.md) | Absolute-path boundary helper with `Result`-shaped returns. |
-| `ensureDirectoryWithinRoot` | – | Create a directory while enforcing the root boundary. |
+| `ensureDirectoryWithinRoot` | [path-scope.md](path-scope.md#ensuredir-rel-options) | Create a directory while enforcing the root boundary; same result contract as `pathScope().ensureDir()`. |
 | `resolvePathWithinRoot`, `resolvePathsWithinRoot` | – | Resolve one or many relative paths against a trusted root. |
 | `resolveExistingPathsWithinRoot`, `resolveStrictExistingPathsWithinRoot` | – | Same, but require the targets to exist. |
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
 
+`ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
+returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
+It does not throw filesystem failures: operational failures carry a
+`helper-failed` diagnostic with the original `cause` and a bounded, escaped
+message naming the native code/syscall when available. Policy failures omit
+`diagnostic`. Missing parents already created before a failure remain in place.
+The diagnostic contract is specific to directory preparation, not the other
+root-path result helpers.
+
 ### Absolute path helpers
 
 | Export | Page | Notes |
@@ -63,6 +72,13 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `assertNoSymlinkParents`, `assertNoSymlinkParentsSync`, `AssertNoSymlinkParentsOptions` | – | Reject paths whose ancestor chain contains symlinks. |
 | `assertNoHardlinkedFinalPath`, `assertNoPathAliasEscape`, `PATH_ALIAS_POLICIES`, `PathAliasPolicy` | – | Hardlink/alias defense building blocks. |
 
+`openRootFile()` and `openRootFileSync()` compare exact bigint identities before
+open, on the retained descriptor, and on the current resolved path. Their `stat`
+receipts remain numeric. Custom `ioFs` adapters must honor `{ bigint: true }` for
+`lstatSync` and `fstatSync`; numeric identity responses fail validation. Unknown
+Windows identities receive one re-inspection without reopening, then fail
+validation if still unknown.
+
 The bounded descriptor helpers start at the descriptor's current offset and
 leave ownership with the caller. They are intended for the second half of a
 safe read: first open and validate the path using the boundary appropriate to
@@ -107,8 +123,9 @@ component is followed by another segment, both helpers throw
 
 | Export | Page | Notes |
 |---|---|---|
+| `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
-| `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Sibling-temp write building block used by `replaceFileAtomic`. |
+| `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Callback-produced file staging: verified sibling publication or private-workspace copy through a root. |
 
 ### Permissions