@openclaw/fs-safe 0.1.2 → 0.2.1

package/dist/sidecar-lock.d.ts

@@ -5,12 +5,14 @@ export type SidecarLockRetryOptions = {
     maxTimeout?: number;
     randomize?: boolean;
 };
+export type SidecarLockStaleRecovery = "fail-closed";
 export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     targetPath: string;
     lockPath?: string;
     staleMs: number;
     timeoutMs?: number;
     retry?: SidecarLockRetryOptions;
+    staleRecovery?: SidecarLockStaleRecovery;
     allowReentrant?: boolean;
     payload: () => TPayload | Promise<TPayload>;
     shouldReclaim?: (params: {

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAuIF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAW3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eA6FL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"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"}

package/dist/sidecar-lock.js

@@ -1,6 +1,7 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 function getGlobalManagers() {
     const globalWithState = globalThis;
@@ -18,17 +19,63 @@ function resolveManagerState(key) {
     }
     return state;
 }
-async function readJsonPayload(lockPath) {
+async function readLockSnapshot(lockPath) {
     try {
-        const parsed = JSON.parse(await fs.readFile(lockPath, "utf8"));
-        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : null;
+        const stat = await fs.lstat(lockPath);
+        const raw = await fs.readFile(lockPath, "utf8");
+        try {
+            const parsed = JSON.parse(raw);
+            const payload = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : null;
+            return { raw, payload, stat };
+        }
+        catch {
+            return { raw, payload: null, stat };
+        }
     }
     catch {
         return null;
     }
 }
+function snapshotMatches(current, observed) {
+    if (observed.stat && current.stat && !sameFileIdentity(observed.stat, current.stat)) {
+        return false;
+    }
+    if (observed.raw !== undefined) {
+        return current.raw === observed.raw;
+    }
+    return observed.stat !== undefined && current.stat !== undefined;
+}
+async function removeLockIfUnchanged(lockPath, observed) {
+    const current = await readLockSnapshot(lockPath);
+    if (!current || !observed) {
+        return false;
+    }
+    if (!snapshotMatches(current, observed)) {
+        // The lock changed after we decided it was stale. Leave the fresh holder's
+        // file alone; deleting by path here would break mutual exclusion.
+        return false;
+    }
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+    return true;
+}
+async function lockSnapshotStillPresent(lockPath, observed) {
+    const current = await readLockSnapshot(lockPath);
+    return !!current && !!observed && snapshotMatches(current, observed);
+}
+function snapshotMatchesSync(lockPath, observed) {
+    try {
+        const stat = fsSync.lstatSync(lockPath);
+        if (observed.stat && !sameFileIdentity(observed.stat, stat)) {
+            return false;
+        }
+        return observed.raw === undefined || fsSync.readFileSync(lockPath, "utf8") === observed.raw;
+    }
+    catch {
+        return false;
+    }
+}
 async function resolveNormalizedTargetPath(targetPath) {
     const resolved = path.resolve(targetPath);
     const dir = path.dirname(resolved);
@@ -66,7 +113,9 @@ function releaseAllLocksSync(state) {
     for (const [normalizedTargetPath, held] of state.held) {
         void held.handle.close().catch(() => undefined);
         try {
-            fsSync.rmSync(held.lockPath, { force: true });
+            if (snapshotMatchesSync(held.lockPath, held.snapshot)) {
+                fsSync.rmSync(held.lockPath, { force: true });
+            }
         }
         catch {
             // Best-effort process-exit cleanup.
@@ -95,7 +144,7 @@ async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
     state.held.delete(normalizedTargetPath);
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
-        await fs.rm(held.lockPath, { force: true }).catch(() => undefined);
+        await removeLockIfUnchanged(held.lockPath, held.snapshot);
     })();
     try {
         await held.releasePromise;
@@ -137,15 +186,19 @@ export function createSidecarLockManager(key) {
             let handle = null;
             try {
                 handle = await fs.open(lockPath, "wx");
+                const payload = await options.payload();
+                const raw = `${JSON.stringify(payload, null, 2)}\n`;
+                await handle.writeFile(raw, "utf8");
+                const snapshot = { raw, payload, stat: await handle.stat() };
                 const createdHeld = {
                     count: 1,
                     handle,
                     lockPath,
+                    snapshot,
                     acquiredAt: Date.now(),
                     metadata: options.metadata ?? {},
                 };
                 state.held.set(normalizedTargetPath, createdHeld);
-                await handle.writeFile(`${JSON.stringify(await options.payload(), null, 2)}\n`, "utf8");
                 const release = () => releaseHeldLock(state, normalizedTargetPath, createdHeld).then(() => undefined);
                 return {
                     lockPath,
@@ -156,29 +209,56 @@ export function createSidecarLockManager(key) {
             }
             catch (err) {
                 if (handle) {
+                    const failedSnapshot = { payload: null };
+                    try {
+                        failedSnapshot.stat = await handle.stat();
+                    }
+                    catch {
+                        // Best-effort cleanup of a failed exclusive create.
+                    }
                     const current = state.held.get(normalizedTargetPath);
                     if (current?.handle === handle) {
                         state.held.delete(normalizedTargetPath);
                     }
-                    await handle.close().catch(() => undefined);
+                    // If payload serialization/write fails, the file may be empty or
+                    // partial JSON, so remove while our exclusive handle is still open.
                     await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                    await handle.close().catch(() => undefined);
+                    // Windows can refuse removing an open file; retry after close but
+                    // only if the path still points at the file identity we created.
+                    await removeLockIfUnchanged(lockPath, failedSnapshot);
                 }
                 if (err.code !== "EEXIST") {
                     throw err;
                 }
                 const nowMs = Date.now();
-                const payload = await readJsonPayload(lockPath);
+                const snapshot = await readLockSnapshot(lockPath);
+                if (!snapshot) {
+                    continue;
+                }
                 const shouldReclaim = options.shouldReclaim ?? defaultShouldReclaim;
                 if (await shouldReclaim({
                     lockPath,
                     normalizedTargetPath,
-                    payload,
+                    payload: snapshot?.payload ?? null,
                     staleMs: options.staleMs,
                     nowMs,
                     heldByThisProcess: state.held.has(normalizedTargetPath),
                 })) {
-                    await fs.rm(lockPath, { force: true }).catch(() => undefined);
-                    continue;
+                    if (!(await lockSnapshotStillPresent(lockPath, snapshot))) {
+                        continue;
+                    }
+                    // Node exposes only path-based unlink/rename here. A stale-lock
+                    // reclaimer cannot bind the delete to the file it inspected, so a
+                    // concurrent release+fresh-acquire could otherwise lose its lock.
+                    // Fail closed and let callers choose a higher-level recovery path.
+                    if ((options.staleRecovery ?? "fail-closed") === "fail-closed") {
+                        throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                            code: "file_lock_stale",
+                            lockPath,
+                            normalizedTargetPath,
+                        });
+                    }
                 }
                 const elapsed = Date.now() - startedAt;
                 if ((options.timeoutMs !== undefined &&

package/dist/store.d.ts

@@ -1,3 +1,4 @@
 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/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,yBAAyB,EACzB,kCAAkC,EAClC,iCAAiC,EACjC,yBAAyB,EACzB,iCAAiC,EACjC,gBAAgB,EAChB,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC"}

package/dist/store.js

@@ -1,2 +1,3 @@
 export { fileStore, fileStoreSync, } from "./file-store.js";
 export { jsonStore, } from "./json-store.js";
+export { ackJsonDurableQueueEntry, ensureJsonDurableQueueDirs, jsonDurableQueueEntryExists, loadJsonDurableQueueEntry, loadPendingJsonDurableQueueEntries, moveJsonDurableQueueEntryToFailed, readJsonDurableQueueEntry, resolveJsonDurableQueueEntryPaths, unlinkBestEffort, writeJsonDurableQueueEntry, } from "./json-durable-queue.js";

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAiBF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAWT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAiBF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { mkdtemp, rm } from "node:fs/promises";
 import path from "node:path";
+import { assertSafePathSegment, sanitizeSafePathSegment } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 function sanitizePrefix(prefix) {
@@ -17,9 +18,9 @@ function sanitizeExtension(extension) {
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {
-    const base = path.basename(fileName).replace(/[^a-zA-Z0-9._-]+/g, "-");
-    const normalized = base.replace(/^-+|-+$/g, "");
-    return normalized || "download.bin";
+    return sanitizeSafePathSegment(path.basename(fileName), "download.bin", {
+        allowDotPrefix: true,
+    });
 }
 export function buildRandomTempFilePath(params) {
     const rootDir = resolveTempRoot(params.rootDir);
@@ -29,7 +30,9 @@ export function buildRandomTempFilePath(params) {
     const now = typeof nowCandidate === "number" && Number.isFinite(nowCandidate)
         ? Math.trunc(nowCandidate)
         : Date.now();
-    const uuid = params.uuid?.trim() || crypto.randomUUID();
+    const uuid = params.uuid
+        ? assertSafePathSegment(params.uuid.trim(), { label: "temp uuid" })
+        : crypto.randomUUID();
     return path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
 }
 function isNodeErrorWithCode(err, code) {

package/dist/test-hooks.d.ts

@@ -3,6 +3,12 @@ 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;
+    beforeArchiveOutputMutation?: (operation: "mkdir" | "chmod", targetPath: string) => Promise<void> | void;
+    beforeFileStorePruneDescend?: (dirPath: string) => Promise<void> | void;
+    beforeFileStoreSyncPrivateWrite?: (filePath: string) => void;
+    beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
+    beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+    beforeTrashMove?: (targetPath: string, destPath: string) => void;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): 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;AAEnD,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;CAC5E,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;AAEnD,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,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/text-atomic.d.ts

@@ -2,6 +2,13 @@ export type WriteTextAtomicOptions = {
     mode?: number;
     dirMode?: number;
     trailingNewline?: boolean;
+    /**
+     * When false, skip the temp-file and parent-directory fsync calls while
+     * preserving the temp-file replace/rename behavior.
+     *
+     * Defaults to true.
+     */
+    durable?: boolean;
 };
 export declare function writeTextAtomic(filePath: string, content: string, options?: WriteTextAtomicOptions): Promise<void>;
 //# sourceMappingURL=text-atomic.d.ts.map

package/dist/text-atomic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-atomic.d.ts","sourceRoot":"","sources":["../src/text-atomic.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAWf"}
+{"version":3,"file":"text-atomic.d.ts","sourceRoot":"","sources":["../src/text-atomic.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/text-atomic.js

@@ -1,13 +1,14 @@
 import { replaceFileAtomic } from "./replace-file.js";
 export async function writeTextAtomic(filePath, content, options) {
     const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
+    const durable = options?.durable ?? true;
     await replaceFileAtomic({
         filePath,
         content: payload,
         mode: options?.mode ?? 0o600,
         dirMode: options?.dirMode ?? (0o777 & ~process.umask()),
         copyFallbackOnPermissionError: true,
-        syncTempFile: true,
-        syncParentDir: true,
+        syncTempFile: durable,
+        syncParentDir: durable,
     });
 }

package/dist/trash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AA4HF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAwKF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/trash.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { sameFileIdentity } from "./file-identity.js";
+import { guardedRenameSync, guardedRmSync } from "./guarded-mutation.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
 const TRASH_DESTINATION_RETRY_LIMIT = 4;
 function getFsErrorCode(error) {
@@ -18,28 +21,56 @@ function isSameOrChildPath(candidate, parent) {
     return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
 }
 function resolveAllowedTrashRoots(allowedRoots) {
-    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].map((root) => {
+    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].flatMap((root) => {
+        const lexicalRoot = path.resolve(root);
         try {
-            return path.resolve(fs.realpathSync.native(root));
+            // Keep both spellings: broken symlink targets cannot be realpathed and
+            // may only compare equal to the caller's lexical allowed root.
+            return [path.resolve(fs.realpathSync.native(root)), lexicalRoot];
         }
         catch {
-            return path.resolve(root);
+            return [lexicalRoot];
         }
     });
     return [...new Set(roots)];
 }
-function assertAllowedTrashTarget(targetPath, allowedRoots) {
-    let resolvedTargetPath = path.resolve(targetPath);
+function resolveTrashTargetPath(targetPath) {
     try {
-        resolvedTargetPath = path.resolve(fs.realpathSync.native(targetPath));
+        return { path: path.resolve(fs.realpathSync.native(targetPath)), resolved: true };
     }
     catch {
-        // The subsequent move will surface missing or inaccessible targets.
+        // Broken symlinks are valid trash targets. Fall back to the lexical path,
+        // then rely on lstat identity so the move renames the symlink itself.
+        return { path: path.resolve(targetPath), resolved: false };
     }
+}
+function assertAllowedTrashTarget(targetPath, allowedRoots) {
+    const stat = fs.lstatSync(path.resolve(targetPath));
+    const resolvedTarget = resolveTrashTargetPath(targetPath);
+    const resolvedTargetPath = resolvedTarget.path;
     const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
     if (!isAllowed) {
         throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
     }
+    return {
+        path: path.resolve(targetPath),
+        realPath: resolvedTargetPath,
+        realPathResolved: resolvedTarget.resolved,
+        stat,
+    };
+}
+function assertTrashTargetGuard(guard) {
+    const stat = fs.lstatSync(guard.path);
+    if (!sameFileIdentity(stat, guard.stat)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    const current = resolveTrashTargetPath(guard.path);
+    if (guard.realPathResolved && (!current.resolved || current.path !== guard.realPath)) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
+    if (!guard.realPathResolved && current.resolved) {
+        throw new Error(`Refusing to trash path after it changed: ${guard.path}`);
+    }
 }
 function resolveTrashDir() {
     const homeDir = os.homedir();
@@ -86,9 +117,11 @@ function reserveTrashDestination(trashDir, base, timestamp) {
     }
     return resolveContainedPath(container, base);
 }
-function movePathToDestination(targetPath, dest) {
+function movePathToDestination(target, dest) {
+    getFsSafeTestHooks()?.beforeTrashMove?.(target.path, dest);
+    assertTrashTargetGuard(target);
     try {
-        fs.renameSync(targetPath, dest);
+        guardedRenameSync({ from: target.path, to: dest });
         return true;
     }
     catch (error) {
@@ -100,8 +133,10 @@ function movePathToDestination(targetPath, dest) {
         }
     }
     try {
-        fs.cpSync(targetPath, dest, { recursive: true, force: false, errorOnExist: true });
-        fs.rmSync(targetPath, { recursive: true, force: false });
+        assertTrashTargetGuard(target);
+        fs.cpSync(target.path, dest, { recursive: true, force: false, errorOnExist: true });
+        assertTrashTargetGuard(target);
+        guardedRmSync({ target: target.path, recursive: true, force: false, verifyAfter: false });
         return true;
     }
     catch (error) {
@@ -114,12 +149,12 @@ function movePathToDestination(targetPath, dest) {
 export async function movePathToTrash(targetPath, options = {}) {
     // Avoid resolving external trash helpers through the service PATH during cleanup.
     const base = trashBaseName(targetPath);
-    assertAllowedTrashTarget(targetPath, options.allowedRoots);
+    const target = assertAllowedTrashTarget(targetPath, options.allowedRoots);
     const trashDir = resolveTrashDir();
     const timestamp = Date.now();
     for (let attempt = 0; attempt < TRASH_DESTINATION_RETRY_LIMIT; attempt += 1) {
         const dest = reserveTrashDestination(trashDir, base, timestamp);
-        if (movePathToDestination(targetPath, dest)) {
+        if (movePathToDestination(target, dest)) {
             return dest;
         }
     }

package/docs/advanced.md

@@ -38,9 +38,19 @@ The exports group into a handful of themes. Each documented helper has its own p
 | Export | Page | Notes |
 |---|---|---|
 | `assertAbsolutePathInput` | – | Validate a caller-supplied absolute path string. |
+| `ensureAbsoluteDirectory`, `EnsureAbsoluteDirectoryOptions`, `EnsureAbsoluteDirectoryResult` | – | Create a trusted absolute directory path one segment at a time, rejecting symlink or non-directory segments. |
 | `canonicalPathFromExistingAncestor`, `findExistingAncestor` | – | Canonicalize without requiring the leaf to exist. |
 | `resolveAbsolutePathForRead`, `resolveAbsolutePathForWrite`, `ResolvedAbsolutePath`, `ResolvedWritableAbsolutePath`, `AbsolutePathSymlinkPolicy` | – | Validate an absolute path against a symlink policy before opening. |
 
+`ensureAbsoluteDirectory()` is for paths you already intend to trust as absolute
+locations, such as a configured output root. It does not enforce a root boundary;
+use `pathScope().ensureDir()` or `ensureDirectoryWithinRoot()` when the caller
+supplies a path that must stay under a root.
+
+The helper returns `{ ok: false, code, error }` for path-policy failures such as
+relative paths, symlinks, non-directories, or directory swaps during creation.
+Operational filesystem failures such as permissions or I/O errors are rethrown.
+
 ### Files and identity
 
 | Export | Page | Notes |

package/docs/atomic.md

@@ -68,7 +68,12 @@ If `beforeRename` throws, the rename is skipped and the temp file is removed —
 
 ### `EPERM` and copy fallback
 
-On systems where `rename` fails with `EPERM`/`EEXIST`, pass `copyFallbackOnPermissionError: true` to fall back to copy + unlink. The fallback refuses symlink destinations before copying so it does not write through a replaced destination link.
+On systems where `rename` fails with `EPERM`/`EEXIST`, pass
+`copyFallbackOnPermissionError: true` to fall back to a non-atomic copy
+replacement. The fallback removes the old destination, opens the replacement
+with exclusive/no-follow flags where the platform supports them, and refuses
+known symlink destinations so it does not write through a replaced destination
+link.
 
 ### Sync variant
 
@@ -109,21 +114,44 @@ await writeTextAtomic("/srv/workspace/rendered.md", rendered, {
 });
 ```
 
+Options:
+
+```ts
+type WriteTextAtomicOptions = {
+  mode?: number;             // file mode (default 0o600)
+  dirMode?: number;          // mode for parent dirs created on demand
+  trailingNewline?: boolean; // append "\n" if missing
+  durable?: boolean;         // default true; false skips temp/parent fsync
+};
+```
+
+`durable: false` keeps the sibling-temp replace/rename behavior but skips the
+temp-file and parent-directory `fsync` calls. Use it only for reconstructible
+metadata where lower latency matters more than crash-durability.
+
 ## `movePathWithCopyFallback`
 
-Rename a path. If the rename fails with `EXDEV` (cross-device) or `EPERM`, fall back to copy + remove. Preserves atomicity at the destination by writing the copy through `replaceFileAtomic` (for files) or staged-rename (for directories).
+Rename a path. If the rename fails with `EXDEV` (cross-device), fall back to
+copying into a staged sibling path, renaming that staged path into place, and
+then removing only the source entries that were copied. The fallback avoids
+buffering regular files into memory and does not tighten the destination parent
+directory mode.
 
 ```ts
 import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
 
 await movePathWithCopyFallback({
-  source: "/srv/cache/blob.bin",
-  destination: "/srv/persistent/blob.bin",
-  overwrite: true,
+  from: "/srv/cache/blob.bin",
+  sourceHardlinks: "reject",
+  to: "/srv/persistent/blob.bin",
 });
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+If another writer changes source entries during the fallback, the staged copy
+throws `ESTALE` before commit when possible. If the destination has already
+been committed, cleanup still preserves the changed source entries and throws
+`ESTALE`.
 
 ## Difference from `root()`
 

package/docs/config.md

@@ -1,22 +1,25 @@
 ---
 title: Config
-description: "Process-global configuration for the optional Python helper used by fs-safe on POSIX."
+description: "Process-global defaults for optional fs-safe helpers."
 ---
 
 # `@openclaw/fs-safe/config`
 
-Process-global configuration knobs for the optional persistent Python helper that backs POSIX fd-relative operations in `root()`. The whole helper policy is described in the [Python helper policy](python-helper.md); this page is the API reference.
+Process-global configuration knobs for optional fs-safe helpers. The Python helper policy is described in the [Python helper policy](python-helper.md); this page is the API reference.
 
 ```ts
 import {
   configureFsSafePython,
+  configureFsSafeLocks,
   getFsSafePythonConfig,
+  getFsSafeLockConfig,
+  type FsSafeLockConfig,
   type FsSafePythonConfig,
   type FsSafePythonMode,
 } from "@openclaw/fs-safe/config";
 ```
 
-`configureFsSafePython` is also re-exported from the main entry point, so `import { configureFsSafePython } from "@openclaw/fs-safe"` works too. Prefer the subpath when you only need helper configuration and want the smallest import surface.
+These functions are also re-exported from the main entry point. Prefer the subpath when you only need helper configuration and want the smallest import surface.
 
 ## `configureFsSafePython(config)`
 
@@ -47,6 +50,31 @@ function getFsSafePythonConfig(): FsSafePythonConfig;
 
 Return the effective configuration: programmatic overrides win, then env vars, then the package default (`auto`).
 
+## `configureFsSafeLocks(config)`
+
+```ts
+function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
+
+type FsSafeLockConfig = {
+  staleRecovery: "fail-closed";
+  staleMs?: number;
+  timeoutMs?: number;
+  retry?: FileLockRetryOptions;
+};
+```
+
+Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
+
+`staleRecovery` currently supports `"fail-closed"` only. Stale third-party sidecars are not deleted by path because Node cannot atomically bind that deletion to the file that was inspected.
+
+## `getFsSafeLockConfig()`
+
+```ts
+function getFsSafeLockConfig(): FsSafeLockConfig;
+```
+
+Return the current sidecar lock defaults.
+
 ## Environment variables
 
 The same policy can be set without code:
@@ -61,5 +89,6 @@ OpenClaw compatibility aliases are accepted: `OPENCLAW_FS_SAFE_PYTHON_MODE`, `OP
 ## Related pages
 
 - [Python helper policy](python-helper.md) — when to pick `auto`, `off`, or `require`, and what each mode protects.
+- [File lock](sidecar-lock.md) — the per-resource lock API that consumes lock defaults.
 - [Root API](root.md) — the API whose POSIX hardening the helper backs.
 - [Errors](errors.md) — `helper-unavailable` and `helper-failed`.

package/docs/index.md

@@ -49,9 +49,10 @@ await fs.remove("notes/archive/today.txt");
 | Surface | Use it for |
 |---|---|
 | [`root()`](root.md) | One boundary for read/write/move/remove inside a trusted directory. |
-| [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper configuration (`configureFsSafePython`, `getFsSafePythonConfig`). |
+| [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper and lock-option defaults. |
 | [Python helper policy](python-helper.md) | Choose `auto`, `off`, or `require` for POSIX fd-relative hardening. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
+| [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
 | [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
 | [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |
 | [`jsonStore`](json-store.md) | Single JSON state file with explicit fallback, atomic writes, and optional locking. |
@@ -63,7 +64,7 @@ await fs.remove("notes/archive/today.txt");
 | [`extractArchive`](archive.md) | ZIP/TAR extraction with size, count, link, and traversal limits. |
 | [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
 | [Permissions](permissions.md) | POSIX mode and Windows ACL inspection/remediation helpers. |
-| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and stale-lock recovery. |
+| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
 | [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
 | [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
 | [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |

package/docs/json-store.md

@@ -53,6 +53,7 @@ type JsonStoreLockOptions = {
   staleMs?: number;     // default 30_000
   timeoutMs?: number;   // default 30_000
   retry?: FileLockRetryOptions;
+  staleRecovery?: "fail-closed";
   managerKey?: string;  // default `fs-safe.json-store:<filePath>`
 };
 
@@ -130,6 +131,7 @@ const counter = jsonStore<{ count: number }>({
   lock: {
     staleMs: 60_000,
     timeoutMs: 10_000,
+    staleRecovery: "fail-closed",
     retry: { retries: 30, minTimeout: 100, maxTimeout: 5_000, randomize: true },
   },
 });
@@ -137,6 +139,8 @@ const counter = jsonStore<{ count: number }>({
 
 When `lock` is falsy, `read` / `write` / `update` are unlocked. The `update` shape is still useful — it gives you a single function for the read-modify-write pattern — but it offers no concurrency guarantees if other processes also write to the file.
 
+Process-wide lock defaults from `configureFsSafeLocks()` apply only after locking is explicitly enabled. They do not make JSON stores lock by default.
+
 The default `managerKey` namespaces the in-process `FileLockManager` per absolute file path, so two `jsonStore` calls on the same file share lock state automatically.
 
 ## Common patterns