artshelf 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -79,6 +79,31 @@
   cache, `ARTSHELF_NO_UPDATE_CHECK_TTL_MS` overrides the no-update/failed TTL
   (falling back to `ARTSHELF_UPDATE_CHECK_TTL_MS` for compatibility), and a
   non-numeric TTL value falls back to the default instead of disabling expiry.
+- Made concurrent ledger and registry writes safe: ledger mutations now take the
+  same cross-process advisory lock as the registry (extracted into a shared
+  `withPathLock` helper in `src/locks.ts`), and ledger appends and rewrites commit
+  through a unique temp file and an atomic rename, so overlapping `put`,
+  `resolve`, and cleanup runs no longer drop records or leave a partially written
+  ledger.
+- Hardened `cleanup --execute` to reject unsafe plan ids and bind the loaded plan
+  to the request before any filesystem mutation: the plan's `planId` must match
+  the requested id, its `ledgerPath` must match the executing ledger, and its
+  entries must be well-formed, so mismatched or malformed plans are refused before
+  moving files or writing a receipt — the plan-id-bound posture trash purge
+  already enforces.
+
+## [0.11.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.2...artshelf-v0.11.0) (2026-06-14)
+
+
+### Features
+
+* **ledger:** add cross-process advisory file lock and unique temp paths for atomic writes (NGX-428) ([0f553e4](https://github.com/calvinnwq/artshelf/commit/0f553e485737cf96390d451f4ae92f52e1abbf2a))
+
+
+### Bug Fixes
+
+* **cleanup:** reject unsafe plan-ids and mismatched plans before filesystem mutation (NGX-426) ([79debb7](https://github.com/calvinnwq/artshelf/commit/79debb7c3610984a969adea7f93b27ca08150647))
+* **ledger:** make ledger writes atomic and concurrency-safe and reject unsafe cleanup plans ([ac98c4e](https://github.com/calvinnwq/artshelf/commit/ac98c4eaf917b695e166f2ca7c40b6759d6e5f53))
 
 ## [0.10.2](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.10.1...artshelf-v0.10.2) (2026-06-13)
 

package/README.md

@@ -113,6 +113,9 @@ destructive deletion.
 - **No fresh-plan-then-execute shortcut** — review the plan, then run that plan.
 - **Trash before delete** — `cleanup=delete` stays refused; physical deletion
   needs its own reviewed trash purge. No silent deletion, ever.
+- **Durable, concurrency-safe writes** — ledger and registry mutations take a
+  cross-process lock and commit atomically, so overlapping commands never lose
+  records or leave a half-written ledger.
 - **`--json` on every command**, so agents can act on structured output.
 - **`--agent` on `review`/`status`/`doctor`**, a compact, token-efficient
   decision packet for agents, while the default render stays human-scannable.

package/SPEC.md

@@ -423,8 +423,15 @@ artshelf cleanup --execute --plan-id <id> [--ledger <path>] --json
 
 Rules:
 
-- Requires `--plan-id`.
+- Requires `--plan-id`, and refuses an unsafe plan id (anything outside
+  `[A-Za-z0-9_-]`, such as a value containing path separators or `..`) before
+  touching the filesystem.
 - Refuses to generate a fresh live cleanup set during execute.
+- Binds the loaded plan to the request before any mutation: the plan file's
+  `planId` must match the requested id, its `ledgerPath` must match the executing
+  ledger, and its entries must be well-formed. A mismatched or malformed plan is
+  refused without moving files or writing a receipt, mirroring the live-record
+  re-checks `trash purge --execute` performs.
 - Writes a cleanup receipt and appends or refreshes an Artshelf-owned ledger record
   for that receipt with `owner=artshelf`, `kind=run-artifact`, `ttl=30d`,
   `cleanup=review`, and labels including `artshelf`, `cleanup-receipt`, and the
@@ -532,6 +539,16 @@ Default behavior:
 - Otherwise write user-global.
 - Allow `--ledger <path>` for explicit tests and unusual workflows.
 
+Write durability:
+
+- Every mutation of a ledger or the registry runs under a cross-process advisory
+  lock keyed on the target file, so overlapping `artshelf` processes serialize
+  their writes instead of racing. The lock is re-entrant within a process and
+  reclaims a stale lock left by a crashed holder.
+- Ledger writes — both single-record appends and full rewrites — land through a
+  unique temp file and an atomic rename, so an interrupted write cannot truncate
+  the ledger or lose already-recorded entries.
+
 V1 also supports a user-level registry of known ledgers:
 
 - registry: `~/.artshelf/ledgers.json`
@@ -784,6 +801,8 @@ human review.
 - CLI can find existing records by path/owner/label/status and get records by id.
 - CLI can mark records manually resolved with a required reason.
 - CLI validates ledger shape.
+- Concurrent ledger and registry writes are serialized with a cross-process lock
+  and committed atomically, so overlapping commands do not lose records.
 - CLI reports machine and registry health through `artshelf doctor`, exiting
   non-zero when the registry or a registered ledger is broken.
 - CLI reports a read-only daily dashboard through `artshelf status`, with
@@ -795,7 +814,8 @@ human review.
   entries; no-op dry-runs do not write plan files.
 - Cleanup dry-run and execute register the plan/receipt artifacts that Artshelf
   creates.
-- Cleanup execute refuses to run without a plan id.
+- Cleanup execute refuses to run without a plan id, and refuses an unsafe,
+  mismatched, or malformed plan before moving files or writing a receipt.
 - Cleanup execute writes a receipt.
 - CLI can list trashed records (single ledger or `--all`) and purge them through
   an approval-first, ledger-scoped dry-run/execute boundary that writes a purge
@@ -807,7 +827,8 @@ human review.
   JSON decision packet for agents that takes precedence over `--json`.
 - Tests cover record/list/find/get/status-filter/due/validate/resolve/registry,
   `artshelf doctor`, the `artshelf status` dashboard, `--all` review, stale-registry,
-  dry-run, global-dry-run, execute-plan, and trash list/purge behavior.
+  dry-run, global-dry-run, execute-plan, cleanup plan-id validation, concurrent
+  ledger writes, and trash list/purge behavior.
 
 ## Deferred
 

package/dist/src/ledger.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { withPathLock } from "./locks.js";
 import { addTtl, assertIsoDate, ageOf, now, ttlToMs, toIso } from "./time.js";
 const KINDS = new Set([
     "scratch",
@@ -136,25 +137,27 @@ export function resolveRecord(ledgerPath, input) {
     if (!input.reason || input.reason.trim().length === 0)
         throw new Error("Missing required --reason");
     const status = assertResolveStatus(input.status);
-    const records = readLedger(ledgerPath);
-    const index = records.findIndex((record) => record.id === input.id);
-    if (index === -1)
-        throw new Error(`Artshelf record not found: ${input.id}`);
-    const current = records[index];
-    if (!current)
-        throw new Error(`Artshelf record not found: ${input.id}`);
-    if (current.status === "resolved") {
-        throw new Error(`Artshelf record is already resolved: ${input.id}`);
-    }
-    const updated = {
-        ...current,
-        status,
-        resolvedAt: toIso(now()),
-        resolutionReason: input.reason.trim()
-    };
-    records[index] = updated;
-    writeLedger(ledgerPath, records);
-    return updated;
+    return withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const index = records.findIndex((record) => record.id === input.id);
+        if (index === -1)
+            throw new Error(`Artshelf record not found: ${input.id}`);
+        const current = records[index];
+        if (!current)
+            throw new Error(`Artshelf record not found: ${input.id}`);
+        if (current.status === "resolved") {
+            throw new Error(`Artshelf record is already resolved: ${input.id}`);
+        }
+        const updated = {
+            ...current,
+            status,
+            resolvedAt: toIso(now()),
+            resolutionReason: input.reason.trim()
+        };
+        records[index] = updated;
+        writeLedger(ledgerPath, records);
+        return updated;
+    });
 }
 export function dueEntries(records, at = now()) {
     return records.filter((record) => record.status === "active").map((record) => {
@@ -305,115 +308,117 @@ export function executeTrashPurgePlan(ledgerPath, purgePlanId) {
     if (!existsSync(planPath))
         throw new Error(`Trash purge plan not found: ${purgePlanId}`);
     const receiptPath = trashPurgeReceiptPath(ledgerPath, purgePlanId);
-    const existingReceipt = existsSync(receiptPath) ? readTrashPurgeReceipt(receiptPath) : null;
-    if (existingReceipt?.completedAt)
-        throw new Error(`Trash purge receipt already exists: ${purgePlanId}`);
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
-    const records = readLedger(ledgerPath);
-    const recordsById = new Map(records.map((record) => [record.id, record]));
-    const trashRoot = resolve(dirname(ledgerPath), "trash");
-    const executedAt = existingReceipt?.executedAt ?? toIso(now());
-    let results = existingReceipt?.results ?? [];
-    const candidates = [];
-    for (const entry of plan.entries) {
-        const existingResult = results.find((result) => result.id === entry.id);
-        if (existingResult && ["failed", "purged", "skipped"].includes(existingResult.status))
-            continue;
-        const record = recordsById.get(entry.id);
-        if (!record) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "record is missing from ledger" });
-            continue;
-        }
-        if (record.status !== "trashed") {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `record is ${record.status}` });
-            continue;
-        }
-        if (record.targetPath !== entry.targetPath ||
-            record.cleanedAt !== entry.cleanedAt ||
-            record.receiptPath !== entry.receiptPath ||
-            record.cleanupPlanId !== entry.cleanupPlanId) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "plan entry no longer matches ledger record" });
-            continue;
-        }
-        const targetPath = resolve(entry.targetPath);
-        const expectedPlanTrashRoot = resolve(trashRoot, record.cleanupPlanId);
-        if (!isPathWithin(trashRoot, targetPath)) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is outside Artshelf trash" });
-            continue;
-        }
-        if (!isStrictPathWithin(expectedPlanTrashRoot, targetPath)) {
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is not a trashed artifact path" });
-            continue;
-        }
-        if (!pathExistsForPurge(entry.targetPath)) {
-            if (existingResult?.status === "deleting") {
-                results = upsertTrashPurgeResult(results, { id: entry.id, status: "purged", targetPath });
+    return withLedgerLock(ledgerPath, () => {
+        const existingReceipt = existsSync(receiptPath) ? readTrashPurgeReceipt(receiptPath) : null;
+        if (existingReceipt?.completedAt)
+            throw new Error(`Trash purge receipt already exists: ${purgePlanId}`);
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const trashRoot = resolve(dirname(ledgerPath), "trash");
+        const executedAt = existingReceipt?.executedAt ?? toIso(now());
+        let results = existingReceipt?.results ?? [];
+        const candidates = [];
+        for (const entry of plan.entries) {
+            const existingResult = results.find((result) => result.id === entry.id);
+            if (existingResult && ["failed", "purged", "skipped"].includes(existingResult.status))
+                continue;
+            const record = recordsById.get(entry.id);
+            if (!record) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "record is missing from ledger" });
                 continue;
             }
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is missing" });
-            continue;
-        }
-        try {
-            if (resolvesOutsideLedgerTrash(dirname(ledgerPath), trashRoot, expectedPlanTrashRoot, targetPath)) {
-                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target resolves outside Artshelf trash" });
+            if (record.status !== "trashed") {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `record is ${record.status}` });
                 continue;
             }
+            if (record.targetPath !== entry.targetPath ||
+                record.cleanedAt !== entry.cleanedAt ||
+                record.receiptPath !== entry.receiptPath ||
+                record.cleanupPlanId !== entry.cleanupPlanId) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "plan entry no longer matches ledger record" });
+                continue;
+            }
+            const targetPath = resolve(entry.targetPath);
+            const expectedPlanTrashRoot = resolve(trashRoot, record.cleanupPlanId);
+            if (!isPathWithin(trashRoot, targetPath)) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is outside Artshelf trash" });
+                continue;
+            }
+            if (!isStrictPathWithin(expectedPlanTrashRoot, targetPath)) {
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is not a trashed artifact path" });
+                continue;
+            }
+            if (!pathExistsForPurge(entry.targetPath)) {
+                if (existingResult?.status === "deleting") {
+                    results = upsertTrashPurgeResult(results, { id: entry.id, status: "purged", targetPath });
+                    continue;
+                }
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is missing" });
+                continue;
+            }
+            try {
+                if (resolvesOutsideLedgerTrash(dirname(ledgerPath), trashRoot, expectedPlanTrashRoot, targetPath)) {
+                    results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target resolves outside Artshelf trash" });
+                    continue;
+                }
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `target cannot be validated: ${reason}` });
+                continue;
+            }
+            candidates.push({ id: entry.id, targetPath });
         }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `target cannot be validated: ${reason}` });
-            continue;
-        }
-        candidates.push({ id: entry.id, targetPath });
-    }
-    writeTrashPurgeReceipt(receiptPath, {
-        purgePlanId,
-        executedAt,
-        status: "started",
-        results: [
-            ...results,
-            ...candidates.map((candidate) => ({ id: candidate.id, status: "pending", targetPath: candidate.targetPath }))
-        ]
-    });
-    for (const candidate of candidates) {
-        results = upsertTrashPurgeResult(results, { id: candidate.id, status: "deleting", targetPath: candidate.targetPath });
         writeTrashPurgeReceipt(receiptPath, {
             purgePlanId,
             executedAt,
             status: "started",
             results: [
                 ...results,
-                ...pendingTrashPurgeResults(candidates, results)
+                ...candidates.map((candidate) => ({ id: candidate.id, status: "pending", targetPath: candidate.targetPath }))
             ]
         });
-        try {
-            rmSync(candidate.targetPath, { recursive: true, force: true });
-            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "purged", targetPath: candidate.targetPath });
-        }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "failed", targetPath: candidate.targetPath, reason });
+        for (const candidate of candidates) {
+            results = upsertTrashPurgeResult(results, { id: candidate.id, status: "deleting", targetPath: candidate.targetPath });
+            writeTrashPurgeReceipt(receiptPath, {
+                purgePlanId,
+                executedAt,
+                status: "started",
+                results: [
+                    ...results,
+                    ...pendingTrashPurgeResults(candidates, results)
+                ]
+            });
+            try {
+                rmSync(candidate.targetPath, { recursive: true, force: true });
+                results = upsertTrashPurgeResult(results, { id: candidate.id, status: "purged", targetPath: candidate.targetPath });
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                results = upsertTrashPurgeResult(results, { id: candidate.id, status: "failed", targetPath: candidate.targetPath, reason });
+            }
+            writeTrashPurgeReceipt(receiptPath, {
+                purgePlanId,
+                executedAt,
+                status: "started",
+                results: [
+                    ...results,
+                    ...pendingTrashPurgeResults(candidates, results)
+                ]
+            });
         }
-        writeTrashPurgeReceipt(receiptPath, {
-            purgePlanId,
-            executedAt,
-            status: "started",
-            results: [
-                ...results,
-                ...pendingTrashPurgeResults(candidates, results)
-            ]
+        updateLedgerAfterTrashPurge(ledgerPath, records, { purgePlanId, receiptPath, executedAt, results });
+        writeTrashPurgeReceipt(receiptPath, { purgePlanId, executedAt, completedAt: toIso(now()), results });
+        registerArtshelfArtifact(ledgerPath, receiptPath, {
+            reason: `Artshelf trash purge receipt for plan ${purgePlanId}`,
+            ttl: "30d",
+            kind: "run-artifact",
+            cleanup: "review",
+            labels: ["artshelf", "trash-purge-receipt", purgePlanId]
         });
-    }
-    updateLedgerAfterTrashPurge(ledgerPath, records, { purgePlanId, receiptPath, executedAt, results });
-    writeTrashPurgeReceipt(receiptPath, { purgePlanId, executedAt, completedAt: toIso(now()), results });
-    registerArtshelfArtifact(ledgerPath, receiptPath, {
-        reason: `Artshelf trash purge receipt for plan ${purgePlanId}`,
-        ttl: "30d",
-        kind: "run-artifact",
-        cleanup: "review",
-        labels: ["artshelf", "trash-purge-receipt", purgePlanId]
+        return { purgePlanId, receiptPath, results };
     });
-    return { purgePlanId, receiptPath, results };
 }
 function readTrashPurgeReceipt(receiptPath) {
     const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
@@ -537,49 +542,52 @@ export function executeCleanupPlan(ledgerPath, planId) {
     if (!existsSync(planPath))
         throw new Error(`Cleanup plan not found: ${planId}`);
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertCleanupPlanExecutable(plan, planId, ledgerPath);
     const trashRoot = join(dirname(ledgerPath), "trash", planId);
-    const records = readLedger(ledgerPath);
-    const recordsById = new Map(records.map((record) => [record.id, record]));
-    const results = [];
-    for (const entry of plan.entries) {
-        const record = recordsById.get(entry.id);
-        if (!record) {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
-            continue;
-        }
-        if (record.status !== "active") {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
-            continue;
-        }
-        if (!existsSync(entry.path)) {
-            results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
-            continue;
-        }
-        if (entry.action === "delete") {
-            results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
-            continue;
-        }
-        if (entry.action === "review") {
-            results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
-            continue;
-        }
-        mkdirSync(trashRoot, { recursive: true });
-        const target = join(trashRoot, `${entry.id}-${basename(entry.path)}`);
-        renameSync(entry.path, target);
-        results.push({ id: entry.id, action: entry.action, status: "trashed", path: entry.path, target });
-    }
-    const receiptPath = receiptPathFor(ledgerPath, planId);
-    const executedAt = toIso(now());
-    writeJson(receiptPath, { planId, executedAt, results });
-    updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
-    registerArtshelfArtifact(ledgerPath, receiptPath, {
-        reason: `Artshelf cleanup receipt for plan ${planId}`,
-        ttl: "30d",
-        kind: "run-artifact",
-        cleanup: "review",
-        labels: ["artshelf", "cleanup-receipt", planId]
+    return withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const results = [];
+        for (const entry of plan.entries) {
+            const record = recordsById.get(entry.id);
+            if (!record) {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
+                continue;
+            }
+            if (record.status !== "active") {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
+                continue;
+            }
+            if (!existsSync(entry.path)) {
+                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
+                continue;
+            }
+            if (entry.action === "delete") {
+                results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
+                continue;
+            }
+            if (entry.action === "review") {
+                results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
+                continue;
+            }
+            mkdirSync(trashRoot, { recursive: true });
+            const target = join(trashRoot, `${entry.id}-${basename(entry.path)}`);
+            renameSync(entry.path, target);
+            results.push({ id: entry.id, action: entry.action, status: "trashed", path: entry.path, target });
+        }
+        const receiptPath = receiptPathFor(ledgerPath, planId);
+        const executedAt = toIso(now());
+        writeJson(receiptPath, { planId, executedAt, results });
+        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
+        registerArtshelfArtifact(ledgerPath, receiptPath, {
+            reason: `Artshelf cleanup receipt for plan ${planId}`,
+            ttl: "30d",
+            kind: "run-artifact",
+            cleanup: "review",
+            labels: ["artshelf", "cleanup-receipt", planId]
+        });
+        return { planId, receiptPath, results };
     });
-    return { planId, receiptPath, results };
 }
 function registerArtshelfArtifact(ledgerPath, path, input) {
     const prepared = prepareRecord({
@@ -591,29 +599,31 @@ function registerArtshelfArtifact(ledgerPath, path, input) {
         owner: "artshelf",
         labels: input.labels
     });
-    const records = readLedger(ledgerPath);
-    const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
-        record.status === "active" &&
-        record.path === path));
-    if (index === -1) {
-        appendPreparedRecord(ledgerPath, prepared);
-        return;
-    }
-    const current = records[index];
-    if (!current)
-        return;
-    records[index] = {
-        ...current,
-        reason: prepared.reason,
-        createdAt: prepared.createdAt,
-        ...(prepared.retainUntil ? { retainUntil: prepared.retainUntil } : {}),
-        retention: prepared.retention,
-        kind: prepared.kind,
-        cleanup: prepared.cleanup,
-        owner: prepared.owner,
-        labels: prepared.labels
-    };
-    writeLedger(ledgerPath, records);
+    withLedgerLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const index = records.findIndex((record) => (isMatchingArtshelfArtifact(record, path, input.labels) &&
+            record.status === "active" &&
+            record.path === path));
+        if (index === -1) {
+            appendPreparedRecord(ledgerPath, prepared);
+            return;
+        }
+        const current = records[index];
+        if (!current)
+            return;
+        records[index] = {
+            ...current,
+            reason: prepared.reason,
+            createdAt: prepared.createdAt,
+            ...(prepared.retainUntil ? { retainUntil: prepared.retainUntil } : {}),
+            retention: prepared.retention,
+            kind: prepared.kind,
+            cleanup: prepared.cleanup,
+            owner: prepared.owner,
+            labels: prepared.labels
+        };
+        writeLedger(ledgerPath, records);
+    });
 }
 function isMatchingArtshelfArtifact(record, path, labels) {
     if (record.path !== path)
@@ -659,16 +669,26 @@ function cleanupPlanEntriesFingerprint(plan) {
         dueStatus: entry.dueStatus
     })));
 }
+function withLedgerLock(ledgerPath, fn) {
+    return withPathLock(ledgerPath, fn, "Artshelf ledger");
+}
+function atomicWriteFileSync(targetPath, content) {
+    const tmpPath = `${targetPath}.${Date.now().toString(36)}-${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmpPath, content);
+    renameSync(tmpPath, targetPath);
+}
 function appendRecord(ledgerPath, record) {
-    mkdirSync(dirname(ledgerPath), { recursive: true });
-    const previous = existsSync(ledgerPath) ? readFileSync(ledgerPath, "utf8") : "";
-    writeFileSync(ledgerPath, `${previous}${previous && !previous.endsWith("\n") ? "\n" : ""}${JSON.stringify(record)}\n`);
+    withLedgerLock(ledgerPath, () => {
+        mkdirSync(dirname(ledgerPath), { recursive: true });
+        const previous = existsSync(ledgerPath) ? readFileSync(ledgerPath, "utf8") : "";
+        atomicWriteFileSync(ledgerPath, `${previous}${previous && !previous.endsWith("\n") ? "\n" : ""}${JSON.stringify(record)}\n`);
+    });
 }
 function writeLedger(ledgerPath, records) {
-    mkdirSync(dirname(ledgerPath), { recursive: true });
-    const tmpPath = `${ledgerPath}.tmp`;
-    writeFileSync(tmpPath, records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : ""));
-    renameSync(tmpPath, ledgerPath);
+    withLedgerLock(ledgerPath, () => {
+        mkdirSync(dirname(ledgerPath), { recursive: true });
+        atomicWriteFileSync(ledgerPath, records.map((record) => JSON.stringify(record)).join("\n") + (records.length > 0 ? "\n" : ""));
+    });
 }
 function updateLedgerAfterCleanup(ledgerPath, records, receipt) {
     const resultById = new Map(receipt.results.map((result) => [result.id, result]));
@@ -802,6 +822,7 @@ function makePurgePlanId(date) {
     return `purge_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
 }
 function cleanupPlanPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "cleanup plan id");
     return join(dirname(ledgerPath), "plans", `${planId}.json`);
 }
 function trashPurgePlanPath(ledgerPath, purgePlanId) {
@@ -809,6 +830,7 @@ function trashPurgePlanPath(ledgerPath, purgePlanId) {
     return join(dirname(ledgerPath), "purge-plans", `${purgePlanId}.json`);
 }
 function receiptPathFor(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "cleanup plan id");
     return join(dirname(ledgerPath), "receipts", `${planId}.json`);
 }
 function trashPurgeReceiptPath(ledgerPath, purgePlanId) {
@@ -850,6 +872,26 @@ function assertSafeGeneratedId(value, label) {
         throw new Error(`Invalid ${label}: ${value}`);
     }
 }
+// Bind a loaded cleanup plan to the request before any filesystem mutation: the
+// plan must declare the requested id, belong to the executing ledger, and carry
+// executable-looking entries. This keeps `cleanup --execute` plan-id bound, the
+// same posture trash purge already enforces against ledger record metadata.
+function assertCleanupPlanExecutable(plan, planId, ledgerPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Cleanup plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.ledgerPath !== ledgerPath) {
+        throw new Error(`Cleanup plan ledger mismatch: plan was created for ${plan.ledgerPath}, executing ${ledgerPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Cleanup plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.id !== "string" || typeof entry.path !== "string" || !CLEANUP_ACTIONS.has(entry.action)) {
+            throw new Error(`Cleanup plan entries are malformed: ${planId}`);
+        }
+    }
+}
 function writeJson(path, value) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);

package/dist/src/locks.js

@@ -0,0 +1,73 @@
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const heldLocks = new Map();
+/**
+ * Run `fn` while holding a cross-process advisory lock for `targetPath`.
+ *
+ * The lock is a sibling `${targetPath}.lock` directory; `mkdir` is atomic across
+ * processes, so only one holder proceeds at a time. A stale lock is reclaimed
+ * after `staleAfterMs`, and acquisition gives up after the deadline so a crashed
+ * holder cannot block forever.
+ *
+ * Locks are re-entrant within a single process: nested calls for the same path
+ * reuse the existing lock instead of deadlocking on the directory they created.
+ */
+export function withPathLock(targetPath, fn, label = "Artshelf") {
+    const key = resolve(targetPath);
+    const depth = heldLocks.get(key) ?? 0;
+    if (depth > 0) {
+        heldLocks.set(key, depth + 1);
+        try {
+            return fn();
+        }
+        finally {
+            const next = (heldLocks.get(key) ?? 1) - 1;
+            if (next > 0)
+                heldLocks.set(key, next);
+            else
+                heldLocks.delete(key);
+        }
+    }
+    mkdirSync(dirname(key), { recursive: true });
+    const lockPath = `${key}.lock`;
+    const deadline = Date.now() + 5000;
+    const staleAfterMs = 30_000;
+    while (true) {
+        try {
+            mkdirSync(lockPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (isStaleLock(lockPath, staleAfterMs)) {
+                rmSync(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`Timed out waiting for ${label} lock: ${key}`);
+            sleep(25);
+        }
+    }
+    heldLocks.set(key, 1);
+    try {
+        return fn();
+    }
+    finally {
+        heldLocks.delete(key);
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isStaleLock(lockPath, staleAfterMs) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs > staleAfterMs;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}

package/dist/src/registry.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { withPathLock } from "./locks.js";
 import { now, toIso } from "./time.js";
 export function defaultRegistryPath() {
     return process.env.ARTSHELF_REGISTRY ?? process.env.SHELF_REGISTRY ?? join(homedir(), ".artshelf", "ledgers.json");
@@ -57,46 +58,7 @@ function writeRegistry(registryPath, registry) {
     renameSync(tmpPath, registryPath);
 }
 function withRegistryLock(registryPath, fn) {
-    mkdirSync(dirname(registryPath), { recursive: true });
-    const lockPath = `${registryPath}.lock`;
-    const deadline = Date.now() + 5000;
-    const staleAfterMs = 30_000;
-    while (true) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            if (isStaleLock(lockPath, staleAfterMs)) {
-                rmSync(lockPath, { recursive: true, force: true });
-                continue;
-            }
-            if (Date.now() > deadline)
-                throw new Error(`Timed out waiting for Artshelf ledger registry lock: ${registryPath}`);
-            sleep(25);
-        }
-    }
-    try {
-        return fn();
-    }
-    finally {
-        rmSync(lockPath, { recursive: true, force: true });
-    }
-}
-function sleep(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function isStaleLock(lockPath, staleAfterMs) {
-    try {
-        return Date.now() - statSync(lockPath).mtimeMs > staleAfterMs;
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
+    return withPathLock(registryPath, fn, "Artshelf ledger registry");
 }
 function normalizeEntry(entry) {
     if (!entry.name || !entry.path || !entry.scope || !entry.createdAt || !entry.updatedAt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artshelf",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Tiny CLI for accountable temporary artifact retention.",
   "type": "module",
   "author": "Calvin",