@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/sidecar-lock.js

@@ -5,6 +5,7 @@ import { removeSidecarLockIfUnchanged, sidecarLockSnapshotMatches, } from "./sid
 import { acquireSidecarLock } from "./sidecar-lock-acquire.js";
 import { createHeldSidecarLockHandle, stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { ensureSidecarLockCleanupRegistered } from "./sidecar-lock-registration.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 const GLOBAL_CLEANUP_KEY = Symbol.for("fsSafe.sidecarLockCleanupRegistered");
 const GLOBAL_CLEANUP_HANDLER_KEY = Symbol.for("fsSafe.sidecarLockCleanupHandler");
@@ -118,51 +119,19 @@ function releaseAllLocksSync(state, options) {
     releaseAllReclaimGuardsSync(state);
 }
 function ensureGlobalExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[GLOBAL_CLEANUP_KEY])
-        return;
-    if (globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY]) {
-        throw new FsSafeError("helper-unavailable", "sidecar lock exit cleanup registration is already in progress");
-    }
-    const registration = {};
     const cleanup = () => {
         for (const state of getGlobalManagers().values()) {
             releaseAllLocksSync(state, { preserveRetained: true });
         }
     };
-    globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY] = registration;
-    try {
-        process.on("exit", cleanup);
-        globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
-        globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
-        globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
-    }
-    catch (error) {
-        if (process.listeners("exit").includes(cleanup)) {
-            try {
-                process.off("exit", cleanup);
-            }
-            catch {
-                // Reconcile the marker with the actual listener below.
-            }
-        }
-        if (process.listeners("exit").includes(cleanup)) {
-            globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] = cleanup;
-            globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] = true;
-            globalWithCleanup[GLOBAL_CLEANUP_KEY] = true;
-        }
-        else {
-            if (globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY] === cleanup) {
-                delete globalWithCleanup[GLOBAL_CLEANUP_HANDLER_KEY];
-            }
-        }
-        throw error;
-    }
-    finally {
-        if (globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY] === registration) {
-            delete globalWithCleanup[GLOBAL_CLEANUP_REGISTRATION_KEY];
-        }
-    }
+    ensureSidecarLockCleanupRegistered({
+        event: "exit",
+        registered: GLOBAL_CLEANUP_KEY,
+        registering: GLOBAL_CLEANUP_REGISTRATION_KEY,
+        handler: GLOBAL_CLEANUP_HANDLER_KEY,
+        retainAware: GLOBAL_RETAIN_AWARE_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock exit cleanup registration is already in progress"),
+    }, cleanup, true);
 }
 /** True when a retain-unaware package copy registered the process-exit handlers first. */
 export function exitCleanupCannotRetain() {
@@ -170,16 +139,8 @@ export function exitCleanupCannotRetain() {
     return globalWithCleanup[GLOBAL_CLEANUP_KEY] === true && globalWithCleanup[GLOBAL_RETAIN_AWARE_KEY] !== true;
 }
 function ensureGlobalBeforeExitCleanupRegistered() {
-    const globalWithCleanup = globalThis;
-    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY]) {
-        return globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
-    }
-    if (globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY]) {
-        throw new FsSafeError("helper-unavailable", "sidecar lock before-exit cleanup registration is already in progress");
-    }
     // Independent of the exit registration, which an older package copy may own.
     const lifecycle = { armed: false };
-    const registration = {};
     const cleanup = () => {
         if (!lifecycle.armed)
             return;
@@ -193,41 +154,13 @@ function ensureGlobalBeforeExitCleanupRegistered() {
             }
         }
     };
-    globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY] = registration;
-    try {
-        process.on("beforeExit", cleanup);
-        globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] = cleanup;
-        globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-        return lifecycle;
-    }
-    catch (error) {
-        if (process.listeners("beforeExit").includes(cleanup)) {
-            try {
-                process.off("beforeExit", cleanup);
-            }
-            catch {
-                // Reconcile the marker with the actual listener below.
-            }
-        }
-        if (process.listeners("beforeExit").includes(cleanup)) {
-            globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] = cleanup;
-            globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] = lifecycle;
-        }
-        else {
-            if (globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY] === cleanup) {
-                delete globalWithCleanup[GLOBAL_BEFORE_EXIT_HANDLER_KEY];
-            }
-            if (globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY] === lifecycle) {
-                delete globalWithCleanup[GLOBAL_BEFORE_EXIT_KEY];
-            }
-        }
-        throw error;
-    }
-    finally {
-        if (globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY] === registration) {
-            delete globalWithCleanup[GLOBAL_BEFORE_EXIT_REGISTRATION_KEY];
-        }
-    }
+    return ensureSidecarLockCleanupRegistered({
+        event: "beforeExit",
+        registered: GLOBAL_BEFORE_EXIT_KEY,
+        registering: GLOBAL_BEFORE_EXIT_REGISTRATION_KEY,
+        handler: GLOBAL_BEFORE_EXIT_HANDLER_KEY,
+        reentryError: () => new FsSafeError("helper-unavailable", "sidecar lock before-exit cleanup registration is already in progress"),
+    }, cleanup, lifecycle);
 }
 async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);

package/dist/staged-directory.d.ts

@@ -25,4 +25,3 @@ export declare function openStagedDirectory(directory: string | DirectoryReceipt
     fd: number;
     receipt: StagedDirectorySnapshot;
 };
-//# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-file-settlement.d.ts

@@ -14,4 +14,3 @@ export declare function settleStagedFile(params: {
     cleanup: () => Promise<StagedFileCleanupReceipt["status"]>;
     close: readonly (() => Promise<void> | void)[];
 }): Promise<void>;
-//# sourceMappingURL=staged-file-settlement.d.ts.map

package/dist/staged-file-types.d.ts

@@ -53,4 +53,3 @@ export interface StagedFile extends AsyncDisposable {
     }): Promise<PublishedFileReceipt>;
     cleanup(): Promise<StagedFileCleanupReceipt>;
 }
-//# sourceMappingURL=staged-file-types.d.ts.map

package/dist/stat-observation.d.ts

@@ -8,4 +8,3 @@ export type StatObservationReceipt = {
 export declare function inspectStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected?: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): StatObservationReceipt;
 /** Revalidate an exact identity without allocating a receipt that the caller will discard. */
 export declare function assertStatObservationSync(inspect: (bigint: boolean) => Stats | BigIntStats, expected: ExactStatIdentity, initial?: Stats | BigIntStats, platform?: NodeJS.Platform): Stats | BigIntStats;
-//# sourceMappingURL=stat-observation.d.ts.map

package/dist/store.d.ts

@@ -1,4 +1,3 @@
 export { fileStore, fileStoreSync, type FileStore, type FileStoreOptions, type FileStorePruneOptions, type FileStoreReadOptions, type FileStoreSync, type FileStoreWriteOptions, } from "./file-store.js";
 export { jsonStore, type JsonStore, type JsonFileStoreOptions, type JsonStoreLockOptions, type JsonStoreOptions, } from "./json-store.js";
 export { ackJsonDurableQueueEntry, ensureJsonDurableQueueDirs, jsonDurableQueueEntryExists, loadJsonDurableQueueEntry, loadPendingJsonDurableQueueEntries, moveJsonDurableQueueEntryToFailed, readJsonDurableQueueEntry, resolveJsonDurableQueueEntryPaths, unlinkBestEffort, writeJsonDurableQueueEntry, type JsonDurableQueueEntryPaths, type JsonDurableQueueLoadOptions, type JsonDurableQueueReadResult, } from "./json-durable-queue.js";
-//# sourceMappingURL=store.d.ts.map

package/dist/strict-file-identity.d.ts

@@ -3,4 +3,3 @@ type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
 export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => T | Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
 export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform, mismatch?: () => Error): T;
 export {};
-//# sourceMappingURL=strict-file-identity.d.ts.map

package/dist/string-coerce.d.ts

@@ -2,4 +2,3 @@ export declare function normalizeNullableString(value: unknown): string | null;
 export declare function normalizeOptionalString(value: unknown): string | undefined;
 export declare function normalizeOptionalLowercaseString(value: unknown): string | undefined;
 export declare function normalizeLowercaseStringOrEmpty(value: unknown): string;
-//# sourceMappingURL=string-coerce.d.ts.map

package/dist/suppressed-error.d.ts

@@ -3,4 +3,3 @@ export type SuppressedErrorLike = Error & {
     suppressed: unknown;
 };
 export declare function createSuppressedError(error: unknown, suppressed: unknown, message: string): SuppressedErrorLike;
-//# sourceMappingURL=suppressed-error.d.ts.map

package/dist/symlink-parents.d.ts

@@ -9,4 +9,3 @@ export type AssertNoSymlinkParentsOptions = {
 };
 export declare function assertNoSymlinkParents(params: AssertNoSymlinkParentsOptions): Promise<void>;
 export declare function assertNoSymlinkParentsSync(params: AssertNoSymlinkParentsOptions): void;
-//# sourceMappingURL=symlink-parents.d.ts.map

package/dist/temp-cleanup.d.ts

@@ -11,4 +11,3 @@ export declare function registerTempPathForExit(tempPath: string, options?: {
 }): TempPathRegistration;
 export declare function __cleanupRegisteredTempPathsForTest(): void;
 export declare function __cleanupRegisteredTempPathForTest(tempPath: string): void;
-//# sourceMappingURL=temp-cleanup.d.ts.map

package/dist/temp-target.d.ts

@@ -29,4 +29,3 @@ export declare function createOwnedTempFile(params: TempFileOptions): Promise<{
 export declare function tempFile(params: TempFileOptions): Promise<TempFile>;
 export declare function withTempFile<T>(params: TempFileOptions, fn: (tmpPath: string) => Promise<T>): Promise<T>;
 export {};
-//# sourceMappingURL=temp-target.d.ts.map

package/dist/temp-target.js

@@ -59,10 +59,7 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    const sanitized = sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
-        allowDotPrefix: true,
-    });
-    return suffixWindowsReservedDeviceName(sanitized);
+    return suffixWindowsReservedDeviceName(sanitizeSafePathSegment(path.basename(fileName)) ?? "download.bin");
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);
@@ -87,16 +84,7 @@ function isNodeErrorWithCode(err, code) {
 }
 async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
-        let current;
-        try {
-            current = fsSync.lstatSync(dir, { bigint: true });
-        }
-        catch (error) {
-            if (isNodeErrorWithCode(error, "ENOENT")) {
-                return;
-            }
-            throw error;
-        }
+        const current = fsSync.lstatSync(dir, { bigint: true });
         if (!current || !sameFileIdentityForCleanup(current, identity)) {
             return;
         }
@@ -131,7 +119,7 @@ export async function createOwnedTempFile(params) {
     const prefix = `${sanitizePrefix(params.prefix)}-`;
     if (cleanupSafety === "require-bounded") {
         const initialFileName = sanitizeTempFileName(params.fileName ?? "download.bin");
-        const [{ TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner }, { admitExistingTempWorkspaceRoot }, { TempWorkspaceRetainedChild }, { validateInitialTempWorkspaceChild, admitRetainedTempWorkspaceChild }, { inspectDirectoryIdentitySync },] = await Promise.all([
+        const [{ TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, throwTempWorkspaceCreationFailure }, { admitExistingTempWorkspaceRoot }, { TempWorkspaceRetainedChild }, { validateInitialTempWorkspaceChild }, { inspectDirectoryIdentitySync },] = await Promise.all([
             import("./temp-workspace-owner.js"),
             import("./temp-workspace-admission.js"),
             import("./temp-workspace-descriptor.js"),
@@ -159,9 +147,9 @@ export async function createOwnedTempFile(params) {
             identity = Object.freeze({ dev: initial.dev, ino: initial.ino });
             const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700);
             retainedChild = TempWorkspaceRetainedChild.retain(dir, identity);
-            const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, 0o700);
-            if (modeInitialization)
-                await modeInitialization;
+            if (needsModeInitialization) {
+                await retainedChild.initializeMode(0o700, admission.ownerUid, admission.assertCurrent);
+            }
             const retainDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
             capability.assertAncestryCurrent();
             retainedChild.finalizeAdmission(admission.ownerUid, 0o700);
@@ -172,34 +160,7 @@ export async function createOwnedTempFile(params) {
             });
         }
         catch (error) {
-            try {
-                if (cleanupOwner)
-                    cleanupOwner.cleanupSync();
-                else {
-                    const closeErrors = [];
-                    try {
-                        retainedChild?.close();
-                    }
-                    catch (closeError) {
-                        closeErrors.push(closeError);
-                    }
-                    try {
-                        capability.close();
-                    }
-                    catch (closeError) {
-                        closeErrors.push(closeError);
-                    }
-                    if (closeErrors.length === 1)
-                        throw closeErrors[0];
-                    if (closeErrors.length > 1) {
-                        throw new AggregateError(closeErrors, "temp file admission descriptor close failed");
-                    }
-                }
-            }
-            catch (cleanupError) {
-                throw new AggregateError([error, cleanupError], "temp file creation and cleanup both failed");
-            }
-            throw error;
+            return throwTempWorkspaceCreationFailure(error, retainedChild, capability, cleanupOwner, "temp file");
         }
         const owner = cleanupOwner;
         const file = (fileName) => {

package/dist/temp-workspace-admission.d.ts

@@ -1,12 +1,6 @@
-type ExactIdentity = Readonly<{
-    dev: bigint;
-    ino: bigint;
-}>;
 export type TempWorkspaceRootAdmission = {
     dir: string;
-    identity: ExactIdentity;
     ownerUid: number | undefined;
-    realPath: string;
     retainCleanupParent(descriptorFd: number): void;
     prepareCleanupProbe(descriptorFd: number): void;
     prepareChildCreation(descriptorFd?: number): void;
@@ -18,5 +12,3 @@ export type TempWorkspaceRootAdmission = {
 export declare function admitExistingTempWorkspaceRoot(rootDir: string): TempWorkspaceRootAdmission;
 export declare function admitTempWorkspaceRoot(rootDir: string): Promise<TempWorkspaceRootAdmission>;
 export declare function admitTempWorkspaceRootSync(rootDir: string): TempWorkspaceRootAdmission;
-export {};
-//# sourceMappingURL=temp-workspace-admission.d.ts.map

package/dist/temp-workspace-admission.js

@@ -2,14 +2,12 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
-import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, } from "./temp-workspace-child-admission.js";
+import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, assertTrustedTempWorkspaceDirectory, inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 import { FsSafeError } from "./errors.js";
 import { recordFileObservationFailure } from "./file-observation.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
-import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
 const WINDOWS = process.platform === "win32";
 function effectiveOwner() {
     // Windows mode/uid fields do not describe ACL authority. The supplied root's
@@ -247,9 +245,7 @@ function rootAdmission(chain, ownerUid) {
     const current = chain[chain.length - 1];
     return {
         dir: current.dir,
-        identity: current.identity,
         ownerUid,
-        realPath: current.realPath,
         retainCleanupParent: (descriptorFd) => {
             assertSnapshot(current, ownerUid);
             associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
@@ -280,9 +276,7 @@ function canonicalRootAdmission(discovery, ownerUid) {
     };
     return {
         dir: discovery.dir,
-        identity: discovery.identity,
         ownerUid,
-        realPath: discovery.realPath,
         // Merely opening the cleanup-parent descriptor grants no authority. The
         // exact association is completed only at a bounded probe or the mutation
         // boundary below.

package/dist/temp-workspace-child-admission.d.ts

@@ -1,13 +1,23 @@
-import type { BigIntStats, Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
-import type { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
-import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+export type TempWorkspaceIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type TempWorkspaceNumericIdentity = Readonly<{
+    dev: number;
+    ino: number;
+}>;
+export type TempWorkspaceIdentityStat = BigIntStats | Stats;
+export declare const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY: boolean;
+export declare function projectTempWorkspaceNumericIdentity(identity: TempWorkspaceIdentity): TempWorkspaceNumericIdentity | undefined;
+export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function validateTempWorkspaceDirMode(mode: number): void;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "mode"> | Pick<Stats, "uid" | "mode">, uid: number | undefined, child?: boolean): void;
 export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
 export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
 export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;
 export declare function admitTempWorkspaceChild(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
 export declare function admitTempWorkspaceChildSync(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): void;
-export declare function admitRetainedTempWorkspaceChild(retained: TempWorkspaceRetainedChild, needsModeInitialization: boolean, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
-export declare function admitRetainedTempWorkspaceChildSync(retained: TempWorkspaceRetainedChild, needsModeInitialization: boolean, parent: TempWorkspaceRootAdmission, mode: number): void;
 export declare function validateAdmittedTempWorkspaceChild(current: TempWorkspaceIdentityStat, ownerUid: number | undefined, mode: number): TempWorkspaceIdentityStat;
-//# sourceMappingURL=temp-workspace-child-admission.d.ts.map

package/dist/temp-workspace-child-admission.js

@@ -1,8 +1,76 @@
-import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import fsSync, {} from "node:fs";
+import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync } from "./directory-guard.js";
 import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
-import { TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
-import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
+export function projectTempWorkspaceNumericIdentity(identity) {
+    const dev = Number(identity.dev);
+    const ino = Number(identity.ino);
+    if (!Number.isSafeInteger(dev) || dev < 0 || BigInt(dev) !== identity.dev ||
+        !Number.isSafeInteger(ino) || ino < 0 || BigInt(ino) !== identity.ino) {
+        return undefined;
+    }
+    return Object.freeze({ dev, ino });
+}
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function inspectNumericIdentity(current, expected) {
+    if (!Number.isSafeInteger(current.dev) || current.dev < 0 || current.dev !== expected.dev ||
+        !Number.isSafeInteger(current.ino) || current.ino < 0 || current.ino !== expected.ino) {
+        identityMismatch();
+    }
+    return current;
+}
+export function inspectTempWorkspaceDescriptorIdentitySync(fd, expected, numeric) {
+    // A malformed or mismatched numeric observation is definite and never
+    // retried. Unsafe receipts and other platforms retain exact replay.
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(fsSync.fstatSync(fd), numeric);
+    }
+    return inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+}
+export function inspectTempWorkspaceDirectoryIdentitySync(dir, expected, numeric) {
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(observeDirectoryIdentitySync(dir), numeric);
+    }
+    return inspectFileIdentitySync(() => observeDirectoryIdentitySync(dir, { bigint: true }), expected);
+}
+export function validateTempWorkspaceDirMode(mode) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+        throw new FsSafeError("insecure-permissions", "temp workspace dirMode must be permission bits");
+    }
+    if (process.platform !== "win32" && (mode & 0o022) !== 0) {
+        throw new FsSafeError("insecure-permissions", "temp workspace must not be group/world writable");
+    }
+}
+export function assertTrustedTempWorkspaceDirectory(stat, uid, child = false) {
+    if (uid === undefined)
+        return;
+    const ownedByUser = typeof stat.uid === "bigint" ? stat.uid === BigInt(uid) : stat.uid === uid;
+    const ownedByRoot = typeof stat.uid === "bigint" ? stat.uid === 0n : stat.uid === 0;
+    if (!ownedByUser && (child || !ownedByRoot)) {
+        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner");
+    }
+    // A root/current-user-owned sticky directory protects children owned by us,
+    // including the usual shared system temp directory. Never chmod that parent.
+    const writable = typeof stat.mode === "bigint"
+        ? (stat.mode & 18n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o022) !== 0;
+    const sticky = typeof stat.mode === "bigint"
+        ? (stat.mode & 512n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o1000) !== 0;
+    if (typeof stat.mode !== "bigint" && (!Number.isSafeInteger(stat.mode) || stat.mode < 0)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory permissions are invalid");
+    }
+    if (writable && (child || !sticky)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory is group/world writable without sticky protection");
+    }
+}
 const WINDOWS = process.platform === "win32";
 export function assertTempWorkspaceChildState(stat, ownerUid) {
     const exactIdentity = typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
@@ -74,18 +142,6 @@ export function admitTempWorkspaceChildSync(dir, expected, parent, mode) {
         owner.close();
     }
 }
-export function admitRetainedTempWorkspaceChild(retained, needsModeInitialization, parent, mode) {
-    if (!needsModeInitialization)
-        return undefined;
-    return retained.initializeMode(mode, parent.ownerUid, parent.assertCurrent);
-}
-export function admitRetainedTempWorkspaceChildSync(retained, needsModeInitialization, parent, mode) {
-    if (!needsModeInitialization) {
-        retained.discardInitialReceipt();
-        return;
-    }
-    retained.initializeModeSync(mode, parent.ownerUid, parent.assertCurrent);
-}
 export function validateAdmittedTempWorkspaceChild(current, ownerUid, mode) {
     assertTempWorkspaceChildState(current, ownerUid);
     if (!childHasRequestedMode(current, mode)) {

package/dist/temp-workspace-descriptor.d.ts

@@ -1,18 +1,13 @@
 import fsSync from "node:fs";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
-import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+import { type TempWorkspaceIdentityStat } from "./temp-workspace-child-admission.js";
 type DirectoryDescriptorAccess = "read" | "search";
 export type RetainedDirectory = {
     fd: number;
     access: DirectoryDescriptorAccess;
     receipt: Readonly<{
         path: string;
-        realPath: string;
-        identity: Readonly<{
-            dev: bigint;
-            ino: bigint;
-        }>;
     }>;
 };
 export type RetainedChildDirectory = {
@@ -45,4 +40,3 @@ export declare class TempWorkspaceRetainedChild {
     close(): void;
 }
 export {};
-//# sourceMappingURL=temp-workspace-descriptor.d.ts.map

package/dist/temp-workspace-descriptor.js

@@ -5,8 +5,7 @@ import { assertOwnedDirectory } from "./directory-mode-owner.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
+import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 function assertRetainedChildDirectory(stat) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new FsSafeError("not-file", "temp workspace child must be a real directory");
@@ -80,8 +79,6 @@ export function openTempWorkspaceCleanupParent(root, admission) {
             access: opened.access,
             receipt: Object.freeze({
                 path: pathname,
-                realPath: admission.realPath,
-                identity: admission.identity,
             }),
         };
     }

package/dist/temp-workspace-owner.d.ts

@@ -15,10 +15,10 @@ export declare class TempWorkspaceCleanupCapability {
     assertAncestryCurrent(): void;
     close(): void;
 }
+export declare function throwTempWorkspaceCreationFailure(error: unknown, retainedChild: TempWorkspaceRetainedChild | undefined, capability: TempWorkspaceCleanupCapability, owner?: TempWorkspaceCleanupOwner, label?: string): never;
 export declare class TempWorkspaceCleanupOwner {
     #private;
     constructor(retained: TempWorkspaceRetainedChild, capability: TempWorkspaceCleanupCapability, retainDescriptor: boolean);
     cleanup(): Promise<TempWorkspaceCleanupResult>;
     cleanupSync(): TempWorkspaceCleanupResult;
 }
-//# sourceMappingURL=temp-workspace-owner.d.ts.map

package/dist/temp-workspace-owner.js

@@ -158,6 +158,36 @@ export class TempWorkspaceCleanupCapability {
             fsSync.closeSync(this.parent.fd);
     }
 }
+export function throwTempWorkspaceCreationFailure(error, retainedChild, capability, owner, label = "temp workspace") {
+    try {
+        if (owner)
+            owner.cleanupSync();
+        else {
+            const closeErrors = [];
+            try {
+                retainedChild?.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            try {
+                capability.close();
+            }
+            catch (closeError) {
+                closeErrors.push(closeError);
+            }
+            if (closeErrors.length === 1)
+                throw closeErrors[0];
+            if (closeErrors.length > 1) {
+                throw new AggregateError(closeErrors, `${label} admission descriptor close failed`);
+            }
+        }
+    }
+    catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], `${label} creation and cleanup both failed`);
+    }
+    throw error;
+}
 export class TempWorkspaceCleanupOwner {
     #dir;
     #identity;
@@ -294,22 +324,19 @@ export class TempWorkspaceCleanupOwner {
                 await beforeNativeRemoval(quarantine.path);
             return this.#mapRemoval(await this.#capability.binding.removeOwnedTree(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalFailure;
         try {
             this.#assertQuarantine(quarantine);
-            try {
-                await fs.rm(quarantine.path, { recursive: true, force: true });
-            }
-            catch (error) {
-                removalFailure = { error };
-                throw error;
-            }
+        }
+        catch {
+            return "indeterminate";
+        }
+        // Removal failures propagate unchanged; only authority uncertainty becomes a receipt.
+        await fs.rm(quarantine.path, { recursive: true, force: true });
+        try {
             this.#capability.assertCurrent();
             return "removed";
         }
-        catch (error) {
-            if (removalFailure !== undefined)
-                throw removalFailure.error;
+        catch {
             return "indeterminate";
         }
     }
@@ -318,22 +345,18 @@ export class TempWorkspaceCleanupOwner {
             getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemovalSync?.(quarantine.path);
             return this.#mapRemoval(this.#capability.binding.removeOwnedTreeSync(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalFailure;
         try {
             this.#assertQuarantine(quarantine);
-            try {
-                fsSync.rmSync(quarantine.path, { recursive: true, force: true });
-            }
-            catch (error) {
-                removalFailure = { error };
-                throw error;
-            }
+        }
+        catch {
+            return "indeterminate";
+        }
+        fsSync.rmSync(quarantine.path, { recursive: true, force: true });
+        try {
             this.#capability.assertCurrent();
             return "removed";
         }
-        catch (error) {
-            if (removalFailure !== undefined)
-                throw removalFailure.error;
+        catch {
             return "indeterminate";
         }
     }

package/dist/temp-workspace-types.d.ts

@@ -37,4 +37,3 @@ export type TempWorkspaceSync = {
     cleanup(): TempWorkspaceCleanupResult;
     [Symbol.dispose](): void;
 };
-//# sourceMappingURL=temp-workspace-types.d.ts.map

package/dist/temp.d.ts

@@ -1,4 +1,3 @@
 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, type SecureTempRootDescriptorAdapter, } from "./secure-temp-dir.js";
-//# sourceMappingURL=temp.d.ts.map