@openclaw/fs-safe 0.4.1 → 0.4.3

package/docs/sidecar-lock.md

@@ -51,7 +51,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   staleMs?: number;                      // default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
+  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // legacy value also fails closed
   allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
   payload: () => TPayload | Promise<TPayload>;
   shouldReclaim?: (params: {
@@ -62,7 +62,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     nowMs: number;
     heldByThisProcess: boolean;
   }) => boolean | Promise<boolean>;
-  shouldRemoveStaleLock?: (snapshot: {
+  shouldRemoveStaleLock?: (snapshot: {          // deprecated; retained but not invoked
     lockPath: string;
     normalizedTargetPath: string;
     raw: string;
@@ -170,40 +170,24 @@ const handle = await acquireFileLock(targetPath, {
 });
 ```
 
-`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or tries caller-approved removal.
+`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale and acquisition throws an error with code `file_lock_stale`.
 
-## Stale recovery: `remove-if-unchanged`
+## Stale recovery is fail-closed
 
-The default `staleRecovery: "fail-closed"` never removes third-party sidecars. Use `staleRecovery: "remove-if-unchanged"` only when your app has a reliable owner-liveness policy and can prove a stale owner cannot still be writing.
+fs-safe never removes a stale third-party sidecar during acquisition. Checking a pathname's content and identity before unlinking it is not atomic: another process can replace the lock between the final check and the unlink. Every stale result therefore fails closed with error code `file_lock_stale`.
 
-```ts
-const handle = await acquireFileLock(targetPath, {
-  staleMs: 60_000,
-  staleRecovery: "remove-if-unchanged",
-  payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
-  shouldReclaim: ({ payload }) => {
-    const pid = Number(payload?.pid);
-    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
-  },
-  shouldRemoveStaleLock: ({ payload }) => {
-    const pid = Number(payload?.pid);
-    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
-  },
-});
-```
-
-`shouldRemoveStaleLock` receives the exact lock snapshot that `fs-safe` inspected. `fs-safe` re-reads the sidecar and removes it only if the raw content and file identity are unchanged. If the callback is missing, returns false, or the file changed, acquisition fails closed or keeps retrying according to the normal retry policy.
+The `"remove-if-unchanged"` value and `shouldRemoveStaleLock` callback remain accepted as deprecated compatibility inputs. They are ignored and the callback is not invoked. To recover, stop or otherwise exclude every process that can acquire the lock, remove the confirmed stale sidecar under that external authority, and retry acquisition.
 
 ## What sidecar locks defend against
 
 - **Two processes writing the same file at once.** `acquire` serializes the critical section.
-- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed by default. Opt-in removal rechecks the observed snapshot before unlinking.
+- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks always fail closed and are never unlinked during acquisition.
 - **Race between simultaneous acquire attempts.** `O_CREAT | O_EXCL` ensures one wins.
 
 ## What they do **not** defend against
 
 - **Misbehaving holders that ignore the lock.** Locks are advisory — only callers that go through `acquire` are bound.
-- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when removal is safe, then opt into `remove-if-unchanged`.
+- **Automatic stale lock deletion.** If a process crashes, recover only under external authority that excludes every competing lock acquirer.
 - **Multi-host coordination over network filesystems.** Behavior depends on the underlying filesystem's `O_EXCL` semantics; treat as best-effort.
 
 ## Common patterns

package/docs/writing.md

@@ -250,7 +250,7 @@ await fs.write("state.json", body); // succeeds on rclone FUSE
 
 **Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain the Python helper's fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
 
-Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Remove a stale sidecar only after proving that its holder can no longer write, using the application-owned recovery guidance in [File lock](sidecar-lock.md#stale-recovery-remove-if-unchanged).
+Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-is-fail-closed).
 
 ## See also
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -97,25 +97,12 @@
       "default": "./dist/test-hooks.js"
     }
   },
-  "optionalDependencies": {
-    "jszip": "^3.10.1",
-    "tar": "7.5.19"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.0",
-    "@vitest/coverage-v8": "4.1.9",
-    "typescript": "^5.9.3",
-    "vite": "7.3.5",
-    "vitest": "^4.1.9"
-  },
-  "engines": {
-    "node": ">=22"
-  },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
+    "prepack": "node scripts/prepack-build.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
@@ -127,5 +114,20 @@
     "crabbox:run": "crabbox run",
     "crabbox:stop": "crabbox stop",
     "crabbox:warmup": "crabbox warmup"
-  }
-}
+  },
+  "optionalDependencies": {
+    "jszip": "^3.10.1",
+    "tar": "7.5.20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "^7.0.2",
+    "vite": "8.1.5",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.34.5"
+}