@agent-workspace/utils 0.7.0 → 0.8.2

package/dist/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQ3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,CAEhG;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAEpF"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG5E;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAQ3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,CAEhG;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAChE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAEpF"}

package/dist/frontmatter.js

@@ -1,5 +1,6 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import matter from "gray-matter";
+import { atomicWriteFile } from "./safe-io.js";
 /**
  * Parse an AWP workspace file (Markdown with YAML frontmatter).
  *
@@ -32,7 +33,7 @@ export function serializeWorkspaceFile(file) {
  */
 export async function writeWorkspaceFile(file) {
     const content = serializeWorkspaceFile(file);
-    await writeFile(file.filePath, content, "utf-8");
+    await atomicWriteFile(file.filePath, content);
 }
 /**
  * Extract the type from frontmatter data.

package/dist/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,MAAM,MAAM,aAAa,CAAC;AAGjC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO;QACL,WAAW,EAAE,IAAS;QACtB,IAAI,EAAE,OAAO;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAA4B,IAAsB;IACtF,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAsB;IAEtB,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,OAAO,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO;QACL,WAAW,EAAE,IAAS;QACtB,IAAI,EAAE,OAAO;QACb,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAA4B,IAAsB;IACtF,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAsB;IAEtB,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,OAAO,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export { computeConfidence, computeDecayedScore, updateDimension, computeWeighte
 export { parseWorkspaceFile, serializeWorkspaceFile, writeWorkspaceFile, getFrontmatterType, } from "./frontmatter.js";
 export { findWorkspaceRoot, loadManifest, fileExists, getAgentDid, safeReadFile, getWorkspaceRoot, } from "./workspace.js";
 export { type TaskNode, type DependencyGraph, type GraphAnalysis, buildGraph, topologicalSort, detectCycles, findCriticalPath, getBlockedTasks, analyzeGraph, getTaskSlug, getProjectSlug, } from "./graph.js";
+export { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile, type AtomicWriteOptions, type FileLockOptions, } from "./safe-io.js";
 export { type RecruitmentCandidate, type RecruitmentResult, findCandidatesForRole, autoRecruitSwarm, isSwarmFullyStaffed, getSwarmStaffingSummary, } from "./swarm.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -14,6 +14,8 @@ export { parseWorkspaceFile, serializeWorkspaceFile, writeWorkspaceFile, getFron
 export { findWorkspaceRoot, loadManifest, fileExists, getAgentDid, safeReadFile, getWorkspaceRoot, } from "./workspace.js";
 // Graph utilities (dependency analysis)
 export { buildGraph, topologicalSort, detectCycles, findCriticalPath, getBlockedTasks, analyzeGraph, getTaskSlug, getProjectSlug, } from "./graph.js";
+// Safe I/O utilities
+export { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile, } from "./safe-io.js";
 // Swarm utilities (recruitment)
 export { findCandidatesForRole, autoRecruitSwarm, isSwarmFullyStaffed, getSwarmStaffingSummary, } from "./swarm.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,wCAAwC;AACxC,OAAO,EAIL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,gCAAgC;AAChC,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,wCAAwC;AACxC,OAAO,EAIL,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,YAAY,GAGb,MAAM,cAAc,CAAC;AAEtB,gCAAgC;AAChC,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/safe-io.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Safe file I/O utilities inspired by clawdbot.
+ *
+ * Provides atomic writes (temp file + rename), file locking with stale
+ * detection, backup rotation, and safe JSON helpers.
+ */
+export interface AtomicWriteOptions {
+    /** Enable backup rotation on overwrite (default: true) */
+    backup?: boolean;
+    /** Maximum number of backup copies to keep (default: 5) */
+    maxBackups?: number;
+}
+export interface FileLockOptions {
+    /** Lock acquisition timeout in milliseconds (default: 10_000) */
+    timeout?: number;
+    /** Age in milliseconds after which a lock is considered stale (default: 1_800_000 = 30min) */
+    staleThreshold?: number;
+}
+/**
+ * Write a file atomically using temp file + rename.
+ *
+ * - Writes content to a uniquely-named temp file
+ * - Backs up the existing file with rotation (if it exists)
+ * - Atomically renames the temp file to the target
+ * - Falls back to copyFile on cross-device or Windows errors
+ * - Cleans up the temp file on failure
+ */
+export declare function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Execute a function while holding an exclusive file lock.
+ *
+ * - Uses `fs.open(lockPath, "wx")` for exclusive creation
+ * - Supports nested lock counting (same process, same file)
+ * - Detects stale locks via timestamp age and PID liveness
+ * - Retries with exponential backoff up to timeout
+ * - Always releases lock in finally block
+ */
+export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Write a JSON file atomically with directory creation.
+ */
+export declare function safeWriteJson(filePath: string, data: unknown, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Load and parse a JSON file, returning undefined if missing or corrupt.
+ */
+export declare function loadJsonFile<T = unknown>(filePath: string): Promise<T | undefined>;
+//# sourceMappingURL=safe-io.d.ts.map

package/dist/safe-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.d.ts","sourceRoot":"","sources":["../src/safe-io.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAwED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAqCf;AAMD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,CAAC,CAAC,CA2FZ;AAMD;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAGf;AAMD;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAWxF"}

package/dist/safe-io.js

@@ -0,0 +1,227 @@
+/**
+ * Safe file I/O utilities inspired by clawdbot.
+ *
+ * Provides atomic writes (temp file + rename), file locking with stale
+ * detection, backup rotation, and safe JSON helpers.
+ */
+import { mkdir, writeFile, readFile, rename, copyFile, unlink, open, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, basename, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+const HELD_LOCKS = new Map();
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Check if a process is still alive via signal 0.
+ */
+function isProcessAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and parse lock file payload.
+ */
+async function readLockPayload(lockPath) {
+    try {
+        const raw = await readFile(lockPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" || typeof parsed.createdAt !== "string")
+            return null;
+        return { pid: parsed.pid, createdAt: parsed.createdAt };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rotate backup files: .bak → .bak.1, .bak.1 → .bak.2, etc.
+ * Deletes the oldest backup if at max capacity.
+ */
+async function rotateBackups(filePath, maxBackups) {
+    if (maxBackups <= 1)
+        return;
+    const backupBase = `${filePath}.bak`;
+    const maxIndex = maxBackups - 1;
+    // Delete oldest
+    await unlink(`${backupBase}.${maxIndex}`).catch(() => { });
+    // Shift all down
+    for (let i = maxIndex - 1; i >= 1; i--) {
+        await rename(`${backupBase}.${i}`, `${backupBase}.${i + 1}`).catch(() => { });
+    }
+    // Move current .bak to .bak.1
+    await rename(backupBase, `${backupBase}.1`).catch(() => { });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// atomicWriteFile
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write a file atomically using temp file + rename.
+ *
+ * - Writes content to a uniquely-named temp file
+ * - Backs up the existing file with rotation (if it exists)
+ * - Atomically renames the temp file to the target
+ * - Falls back to copyFile on cross-device or Windows errors
+ * - Cleans up the temp file on failure
+ */
+export async function atomicWriteFile(filePath, content, options) {
+    const doBackup = options?.backup !== false;
+    const maxBackups = options?.maxBackups ?? 5;
+    const dir = dirname(filePath);
+    const base = basename(filePath);
+    const tmp = join(dir, `${base}.${process.pid}.${randomUUID()}.tmp`);
+    // Ensure directory exists
+    await mkdir(dir, { recursive: true });
+    // Write to temp file
+    await writeFile(tmp, content, { encoding: "utf-8" });
+    try {
+        // Backup existing file
+        if (doBackup && existsSync(filePath)) {
+            await rotateBackups(filePath, maxBackups);
+            await copyFile(filePath, `${filePath}.bak`).catch(() => { });
+        }
+        // Atomic rename
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        const code = err.code;
+        // Cross-device rename or Windows permission error: fall back to copy
+        if (code === "EXDEV" || code === "EPERM" || code === "EEXIST") {
+            await copyFile(tmp, filePath);
+            await unlink(tmp).catch(() => { });
+            return;
+        }
+        // Clean up temp file on unexpected error
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// withFileLock
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a function while holding an exclusive file lock.
+ *
+ * - Uses `fs.open(lockPath, "wx")` for exclusive creation
+ * - Supports nested lock counting (same process, same file)
+ * - Detects stale locks via timestamp age and PID liveness
+ * - Retries with exponential backoff up to timeout
+ * - Always releases lock in finally block
+ */
+export async function withFileLock(filePath, fn, options) {
+    const timeout = options?.timeout ?? 10_000;
+    const staleThreshold = options?.staleThreshold ?? 30 * 60 * 1000;
+    const normalizedPath = resolve(filePath);
+    const lockPath = `${normalizedPath}.lock`;
+    // Check for nested lock (same process already holds this lock)
+    const held = HELD_LOCKS.get(normalizedPath);
+    if (held) {
+        held.count++;
+        try {
+            return await fn();
+        }
+        finally {
+            held.count--;
+            if (held.count <= 0) {
+                HELD_LOCKS.delete(normalizedPath);
+                await rm(held.lockPath, { force: true }).catch(() => { });
+            }
+        }
+    }
+    // Acquire new lock
+    const startedAt = Date.now();
+    let attempt = 0;
+    while (Date.now() - startedAt < timeout) {
+        attempt++;
+        try {
+            // Ensure directory exists
+            await mkdir(dirname(lockPath), { recursive: true });
+            // Exclusive creation — fails with EEXIST if lock already held
+            const handle = await open(lockPath, "wx");
+            const payload = JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2);
+            await handle.writeFile(payload, "utf-8");
+            await handle.close();
+            // Register in-process lock
+            HELD_LOCKS.set(normalizedPath, { count: 1, lockPath });
+            try {
+                return await fn();
+            }
+            finally {
+                const current = HELD_LOCKS.get(normalizedPath);
+                if (current) {
+                    current.count--;
+                    if (current.count <= 0) {
+                        HELD_LOCKS.delete(normalizedPath);
+                        await rm(current.lockPath, { force: true }).catch(() => { });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            // Lock file exists — check if stale
+            const lockPayload = await readLockPayload(lockPath);
+            if (lockPayload) {
+                const createdAt = Date.parse(lockPayload.createdAt);
+                const isStale = !Number.isFinite(createdAt) || Date.now() - createdAt > staleThreshold;
+                const isAlive = isProcessAlive(lockPayload.pid);
+                if (isStale || !isAlive) {
+                    // Remove stale lock and retry immediately
+                    await rm(lockPath, { force: true }).catch(() => { });
+                    continue;
+                }
+            }
+            else {
+                // Can't read lock file — remove and retry
+                await rm(lockPath, { force: true }).catch(() => { });
+                continue;
+            }
+            // Lock is held by a live process — wait with backoff
+            const delay = Math.min(1000, 50 * attempt);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    // Timeout
+    const lockPayload = await readLockPayload(lockPath);
+    const owner = lockPayload?.pid ? `pid=${lockPayload.pid}` : "unknown";
+    throw new Error(`File lock timeout (${timeout}ms): ${owner} holds ${lockPath}`);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// safeWriteJson
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Write a JSON file atomically with directory creation.
+ */
+export async function safeWriteJson(filePath, data, options) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await atomicWriteFile(filePath, JSON.stringify(data, null, 2) + "\n", options);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// loadJsonFile
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Load and parse a JSON file, returning undefined if missing or corrupt.
+ */
+export async function loadJsonFile(filePath) {
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || err instanceof SyntaxError) {
+            return undefined;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=safe-io.js.map

package/dist/safe-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.js","sourceRoot":"","sources":["../src/safe-io.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAS,IAAI,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA6BzC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqB,CAAC;AAEhD,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;GAEG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,eAAe,CAC5B,QAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxF,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,UAAkB;IAC/D,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO;IAE5B,MAAM,UAAU,GAAG,GAAG,QAAQ,MAAM,CAAC;IACrC,MAAM,QAAQ,GAAG,UAAU,GAAG,CAAC,CAAC;IAEhC,gBAAgB;IAChB,MAAM,MAAM,CAAC,GAAG,UAAU,IAAI,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE1D,iBAAiB;IACjB,KAAK,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,MAAM,CAAC,GAAG,UAAU,IAAI,CAAC,EAAE,EAAE,GAAG,UAAU,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,8BAA8B;IAC9B,MAAM,MAAM,CAAC,UAAU,EAAE,GAAG,UAAU,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAe,EACf,OAA4B;IAE5B,MAAM,QAAQ,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IAEpE,0BAA0B;IAC1B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtC,qBAAqB;IACrB,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAErD,IAAI,CAAC;QACH,uBAAuB;QACvB,IAAI,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,MAAM,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAC1C,MAAM,QAAQ,CAAC,QAAQ,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9D,CAAC;QAED,gBAAgB;QAChB,MAAM,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QAEjD,qEAAqE;QACrE,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC9B,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QAED,yCAAyC;QACzC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,EAAoB,EACpB,OAAyB;IAEzB,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC;IAC3C,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAEjE,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,GAAG,cAAc,OAAO,CAAC;IAE1C,+DAA+D;IAC/D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5C,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpB,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;gBAClC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC;QAEV,IAAI,CAAC;YACH,0BAA0B;YAC1B,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAEpD,8DAA8D;YAC9D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAC5B,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EACzD,IAAI,EACJ,CAAC,CACF,CAAC;YACF,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAErB,2BAA2B;YAC3B,UAAU,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAEvD,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;oBAAS,CAAC;gBACT,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;gBAC/C,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,CAAC,KAAK,EAAE,CAAC;oBAChB,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;wBACvB,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;wBAClC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBAC9D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAEjC,oCAAoC;YACpC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;gBACpD,MAAM,OAAO,GACX,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,cAAc,CAAC;gBACzE,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAEhD,IAAI,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;oBACxB,0CAA0C;oBAC1C,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACpD,SAAS;gBACX,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,0CAA0C;gBAC1C,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBACpD,SAAS;YACX,CAAC;YAED,qDAAqD;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;YAC3C,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,UAAU;IACV,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,QAAQ,KAAK,UAAU,QAAQ,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,IAAa,EACb,OAA4B;IAE5B,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACjF,CAAC;AAED,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAc,QAAgB;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/safe-io.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=safe-io.test.d.ts.map

package/dist/safe-io.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.test.d.ts","sourceRoot":"","sources":["../src/safe-io.test.ts"],"names":[],"mappings":""}

package/dist/safe-io.test.js

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, readFile, writeFile, readdir, rm, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { atomicWriteFile, withFileLock, safeWriteJson, loadJsonFile } from "./safe-io.js";
+let testDir;
+beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "awp-safe-io-test-"));
+});
+afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// atomicWriteFile
+// ─────────────────────────────────────────────────────────────────────────────
+describe("atomicWriteFile", () => {
+    it("writes file content correctly", async () => {
+        const filePath = join(testDir, "test.md");
+        await atomicWriteFile(filePath, "hello world");
+        const content = await readFile(filePath, "utf-8");
+        expect(content).toBe("hello world");
+    });
+    it("creates parent directories", async () => {
+        const filePath = join(testDir, "a", "b", "c", "test.md");
+        await atomicWriteFile(filePath, "nested");
+        const content = await readFile(filePath, "utf-8");
+        expect(content).toBe("nested");
+    });
+    it("creates .bak on overwrite", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "original", "utf-8");
+        await atomicWriteFile(filePath, "updated");
+        expect(await readFile(filePath, "utf-8")).toBe("updated");
+        expect(await readFile(`${filePath}.bak`, "utf-8")).toBe("original");
+    });
+    it("rotates backups on repeated overwrites", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "v1", "utf-8");
+        await atomicWriteFile(filePath, "v2");
+        await atomicWriteFile(filePath, "v3");
+        await atomicWriteFile(filePath, "v4");
+        expect(await readFile(filePath, "utf-8")).toBe("v4");
+        expect(await readFile(`${filePath}.bak`, "utf-8")).toBe("v3");
+        expect(await readFile(`${filePath}.bak.1`, "utf-8")).toBe("v2");
+        expect(await readFile(`${filePath}.bak.2`, "utf-8")).toBe("v1");
+    });
+    it("does not create backup when backup=false", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "original", "utf-8");
+        await atomicWriteFile(filePath, "updated", { backup: false });
+        expect(await readFile(filePath, "utf-8")).toBe("updated");
+        expect(existsSync(`${filePath}.bak`)).toBe(false);
+    });
+    it("does not leave temp files on success", async () => {
+        const filePath = join(testDir, "test.md");
+        await atomicWriteFile(filePath, "content");
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".tmp"))).toHaveLength(0);
+    });
+    it("respects maxBackups option", async () => {
+        const filePath = join(testDir, "test.md");
+        await writeFile(filePath, "v1", "utf-8");
+        for (let i = 2; i <= 6; i++) {
+            await atomicWriteFile(filePath, `v${i}`, { maxBackups: 2 });
+        }
+        // Should only keep 2 backups: .bak and .bak.1
+        expect(existsSync(`${filePath}.bak`)).toBe(true);
+        expect(existsSync(`${filePath}.bak.1`)).toBe(true);
+        // .bak.2 should not exist (maxBackups=2 means slots: .bak, .bak.1)
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// withFileLock
+// ─────────────────────────────────────────────────────────────────────────────
+describe("withFileLock", () => {
+    it("acquires lock and runs callback", async () => {
+        const filePath = join(testDir, "data.md");
+        const result = await withFileLock(filePath, async () => {
+            return 42;
+        });
+        expect(result).toBe(42);
+    });
+    it("cleans up lock file after callback", async () => {
+        const filePath = join(testDir, "data.md");
+        await withFileLock(filePath, async () => { });
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".lock"))).toHaveLength(0);
+    });
+    it("cleans up lock file after callback throws", async () => {
+        const filePath = join(testDir, "data.md");
+        await expect(withFileLock(filePath, async () => {
+            throw new Error("test error");
+        })).rejects.toThrow("test error");
+        const files = await readdir(testDir);
+        expect(files.filter((f) => f.includes(".lock"))).toHaveLength(0);
+    });
+    it("serializes concurrent access", async () => {
+        const filePath = join(testDir, "counter.txt");
+        await writeFile(filePath, "0", "utf-8");
+        // Run 5 concurrent increments
+        const results = await Promise.all(Array.from({ length: 5 }, () => withFileLock(filePath, async () => {
+            const val = parseInt(await readFile(filePath, "utf-8"), 10);
+            await writeFile(filePath, String(val + 1), "utf-8");
+            return val + 1;
+        })));
+        // All increments should have serialized correctly
+        const finalValue = await readFile(filePath, "utf-8");
+        expect(parseInt(finalValue, 10)).toBe(5);
+        // Results should contain all values 1-5
+        expect(results.sort()).toEqual([1, 2, 3, 4, 5]);
+    });
+    it("supports nested lock counting", async () => {
+        const filePath = join(testDir, "data.md");
+        const result = await withFileLock(filePath, async () => {
+            // Nested lock on same file should not deadlock
+            return withFileLock(filePath, async () => {
+                return "nested ok";
+            });
+        });
+        expect(result).toBe("nested ok");
+    });
+    it("times out if lock cannot be acquired", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock file from a "live" process (our own PID)
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }), "utf-8");
+        // Should timeout since lock is held by a "live" process
+        await expect(withFileLock(filePath, async () => { }, { timeout: 200 })).rejects.toThrow(/timeout/i);
+        // Clean up the lock file manually
+        await rm(lockPath, { force: true });
+    });
+    it("detects stale locks from dead process", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock from a definitely-dead PID
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({ pid: 999999999, createdAt: new Date().toISOString() }), "utf-8");
+        // Should succeed because the PID is dead
+        const result = await withFileLock(filePath, async () => "recovered");
+        expect(result).toBe("recovered");
+    });
+    it("detects stale locks by age", async () => {
+        const filePath = join(testDir, "data.md");
+        const lockPath = `${filePath}.lock`;
+        // Create a lock from our own PID but with an old timestamp
+        await mkdir(testDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify({
+            pid: process.pid,
+            createdAt: new Date(Date.now() - 2_000_000).toISOString(),
+        }), "utf-8");
+        // Should succeed because the lock is stale (older than 30min default)
+        const result = await withFileLock(filePath, async () => "recovered");
+        expect(result).toBe("recovered");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// safeWriteJson
+// ─────────────────────────────────────────────────────────────────────────────
+describe("safeWriteJson", () => {
+    it("writes valid JSON with formatting", async () => {
+        const filePath = join(testDir, "data.json");
+        await safeWriteJson(filePath, { key: "value", num: 42 });
+        const raw = await readFile(filePath, "utf-8");
+        expect(raw).toBe('{\n  "key": "value",\n  "num": 42\n}\n');
+    });
+    it("creates directories recursively", async () => {
+        const filePath = join(testDir, "a", "b", "data.json");
+        await safeWriteJson(filePath, { ok: true });
+        const data = JSON.parse(await readFile(filePath, "utf-8"));
+        expect(data).toEqual({ ok: true });
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// loadJsonFile
+// ─────────────────────────────────────────────────────────────────────────────
+describe("loadJsonFile", () => {
+    it("loads valid JSON", async () => {
+        const filePath = join(testDir, "data.json");
+        await writeFile(filePath, '{"key": "value"}', "utf-8");
+        const data = await loadJsonFile(filePath);
+        expect(data).toEqual({ key: "value" });
+    });
+    it("returns undefined for missing file", async () => {
+        const data = await loadJsonFile(join(testDir, "nonexistent.json"));
+        expect(data).toBeUndefined();
+    });
+    it("returns undefined for corrupt JSON", async () => {
+        const filePath = join(testDir, "corrupt.json");
+        await writeFile(filePath, "not valid json {{{", "utf-8");
+        const data = await loadJsonFile(filePath);
+        expect(data).toBeUndefined();
+    });
+});
+//# sourceMappingURL=safe-io.test.js.map

package/dist/safe-io.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-io.test.js","sourceRoot":"","sources":["../src/safe-io.test.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -28,6 +28,7 @@ export declare function validatePath(root: string, targetPath: string): string;
  *
  * @param dateStr - The date string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export declare function isValidDate(dateStr: string): boolean;
 /**
@@ -35,6 +36,7 @@ export declare function isValidDate(dateStr: string): boolean;
  *
  * @param timestamp - The timestamp string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export declare function isValidTimestamp(timestamp: string): boolean;
 //# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3D"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWjD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3D"}

package/dist/validation.js

@@ -52,6 +52,7 @@ export function validatePath(root, targetPath) {
  *
  * @param dateStr - The date string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export function isValidDate(dateStr) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
@@ -65,6 +66,7 @@ export function isValidDate(dateStr) {
  *
  * @param timestamp - The timestamp string to validate
  * @returns true if valid, false otherwise
+ * @internal Utility function for future validation use
  */
 export function isValidTimestamp(timestamp) {
     const date = new Date(timestamp);

package/dist/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE1D,8FAA8F;AAC9F,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,0BAA0B;AAC1B,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,2EAA2E,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,eAAe,aAAa,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAEvC,8BAA8B;IAC9B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE1D,8FAA8F;AAC9F,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,0BAA0B;AAC1B,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,2EAA2E,CAClG,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sBAAsB,eAAe,aAAa,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAEvC,8BAA8B;IAC9B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-workspace/utils",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "Shared utilities for AWP packages — validation, reputation calculations, and frontmatter parsing",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agent-workspace/core": "0.7.0",
+    "@agent-workspace/core": "0.8.2",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {