artshelf 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+- Hardened `cleanup --execute` with durable resumability: a `started` receipt is
+  written before the first filesystem move so an interrupted run is detectable,
+  terminal receipt evidence preserves an artifact's original
+  `executedAt`/`cleanedAt`, an artifact already moved into the plan's trash
+  directory without terminal receipt evidence is recorded as `trashed` at resume
+  time without moving it again, a missing original path with no trash target and no
+  receipt evidence stays a skipped missing path rather than a success, and a
+  completed receipt replays idempotently without duplicating the Artshelf-owned
+  receipt record (NGX-427).
 - Renamed the published package and CLI binary from `shelf` to `artshelf`,
   moved project URLs to `calvinnwq/artshelf`, and prepared public npm publishing.
 - Added a user-level ledger registry plus `--all` review commands so Artshelf can
@@ -117,6 +126,14 @@
 - Moved `artshelf put` registry-warning output from stdout to stderr in human
   mode; `--json` output is unchanged (NGX-429).
 
+## [0.13.1](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.13.0...artshelf-v0.13.1) (2026-06-15)
+
+
+### Bug Fixes
+
+* **cleanup:** make cleanup --execute resumable after interruption ([d0188f7](https://github.com/calvinnwq/artshelf/commit/d0188f73a62b1ff2d173e26c61c826a67bbc9542))
+* **cleanup:** make cleanup execution resumable ([7ec0ebe](https://github.com/calvinnwq/artshelf/commit/7ec0ebe113f589ccd00ed0fdd1a54034afc242ec))
+
 ## [0.13.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.12.0...artshelf-v0.13.0) (2026-06-15)
 
 

package/README.md

@@ -113,9 +113,10 @@ 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.
+- **Durable, resumable cleanup** — execution writes a started receipt before
+  moving files, can replay the same plan id after interruption, and ledger and
+  registry mutations take a cross-process lock 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

@@ -440,10 +440,19 @@ Rules:
   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
-  plan id.
+- Writes a `started` cleanup receipt to `<ledger-dir>/receipts/<plan-id>.json` before
+  the first filesystem move, then completes the receipt with `completedAt` and the
+  per-entry `trashed`, `review-required`, `refused`, or `skipped` results.
+- Appends or refreshes an Artshelf-owned ledger record for the completed receipt with
+  `owner=artshelf`, `kind=run-artifact`, `ttl=30d`, `cleanup=review`, and labels
+  including `artshelf`, `cleanup-receipt`, and the plan id.
+- Resumes an interrupted run on rerun of the same plan id: terminal receipt evidence
+  for an artifact keeps its original `executedAt`/`cleanedAt`, an artifact already
+  moved into the plan's trash directory without terminal receipt evidence is recorded
+  as `trashed` at resume time without moving it again, a missing original path with no
+  trash target and no receipt evidence stays a skipped missing path rather than a
+  success, and a completed receipt replays idempotently without duplicating the
+  Artshelf-owned receipt record.
 - Updates touched ledger records so handled artifacts stop appearing as active
   cleanup candidates.
 - Uses trash/review behavior by default.
@@ -829,11 +838,15 @@ Operational rules that back those boundaries:
 - Dry-run first.
 - Execute only by plan id.
 - Trash/review before delete.
-- Execute updates ledger state after writing the cleanup receipt. A trashed,
-  review-required, or refused record no longer participates in future `due` or
-  cleanup dry-run output by default.
-- Missing paths update the report; they are not treated as a successful cleanup
-  unless the user explicitly repairs the ledger later.
+- Execute writes a `started` cleanup receipt before the first filesystem move,
+  updates ledger state after recording per-entry outcomes, and completes the
+  receipt with `completedAt`. A trashed, review-required, or refused record no
+  longer participates in future `due` or cleanup dry-run output by default.
+- Rerunning the same plan id resumes or replays durable receipt/trash evidence:
+  terminal receipt evidence keeps its original cleanup timestamp, existing
+  plan-trash targets are not moved again, completed receipts are idempotent,
+  and missing paths without receipt or trash evidence stay skipped rather than
+  successful.
 - Cleanup never scans arbitrary filesystem paths for deletion in v1.
 - Cleanup only acts on ledger entries.
 - Trash purge is scoped to one ledger, requires a reviewed purge plan id, and
@@ -957,7 +970,9 @@ human review.
   creates.
 - 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.
+- Cleanup execute writes a started receipt before moving files, resumes or
+  replays the same plan id from receipt/trash evidence, and completes the
+  receipt idempotently.
 - 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
   receipt; purge refuses `--all` and never deletes without a reviewed plan id.

package/dist/src/ledger.js

@@ -553,41 +553,94 @@ export function executeCleanupPlan(ledgerPath, planId) {
     const plan = JSON.parse(readFileSync(planPath, "utf8"));
     assertCleanupPlanExecutable(plan, planId, ledgerPath);
     const trashRoot = join(dirname(ledgerPath), "trash", planId);
+    const receiptPath = receiptPathFor(ledgerPath, planId);
     return withLedgerLock(ledgerPath, () => {
+        const existingReceipt = existsSync(receiptPath) ? readCleanupReceiptIfValid(receiptPath) : null;
+        const planReceipt = existingReceipt?.planId === planId ? existingReceipt : null;
+        const priorResultById = new Map((planReceipt?.results ?? []).map((result) => [result.id, result]));
         const records = readLedger(ledgerPath);
+        if (planReceipt?.completedAt) {
+            if (!records.some((record) => record.status === "active" && isMatchingArtshelfArtifact(record, receiptPath, ["artshelf", "cleanup-receipt", planId]))) {
+                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: planReceipt.results };
+        }
         const recordsById = new Map(records.map((record) => [record.id, record]));
-        const results = [];
-        for (const entry of plan.entries) {
+        const executedAt = toIso(now());
+        const results = plan.entries.map((entry) => {
+            const prior = priorResultById.get(entry.id);
+            if (prior && isTerminalCleanupResult(prior)) {
+                return withCleanupResultExecutedAt(prior, cleanupResultExecutedAt(prior, planReceipt, executedAt));
+            }
+            return { id: entry.id, action: entry.action, status: "pending", path: entry.path };
+        });
+        writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+        for (const [index, entry] of plan.entries.entries()) {
             const record = recordsById.get(entry.id);
+            const prior = priorResultById.get(entry.id);
+            const priorExecutedAt = prior && isTerminalCleanupResult(prior)
+                ? cleanupResultExecutedAt(prior, planReceipt, executedAt)
+                : executedAt;
             if (!record) {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" });
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "record is missing from ledger" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
             if (record.status !== "active") {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` });
+                if (prior && priorCleanupResultMatchesLedger(record, prior, { planId, receiptPath, executedAt: priorExecutedAt })) {
+                    results[index] = withCleanupResultExecutedAt(prior, priorExecutedAt);
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: `record is ${record.status}` };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (!existsSync(entry.path)) {
-                results.push({ id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" });
+            if (prior && isTerminalCleanupResult(prior)) {
+                results[index] = withCleanupResultExecutedAt(prior, priorExecutedAt);
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (entry.action === "delete") {
-                results.push({ id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1" });
+            if (entry.action === "trash") {
+                const target = join(trashRoot, `${entry.id}-${basename(entry.path)}`);
+                if (existsSync(target)) {
+                    results[index] = { id: entry.id, action: entry.action, status: "trashed", path: entry.path, target, executedAt };
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                if (existsSync(entry.path)) {
+                    mkdirSync(trashRoot, { recursive: true });
+                    renameSync(entry.path, target);
+                    results[index] = { id: entry.id, action: entry.action, status: "trashed", path: entry.path, target, executedAt };
+                    writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                    continue;
+                }
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
+                continue;
+            }
+            if (!existsSync(entry.path)) {
+                results[index] = { id: entry.id, action: entry.action, status: "skipped", path: entry.path, reason: "path is missing" };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 continue;
             }
-            if (entry.action === "review") {
-                results.push({ id: entry.id, action: entry.action, status: "review-required", path: entry.path });
+            if (entry.action === "delete") {
+                results[index] = { id: entry.id, action: entry.action, status: "refused", path: entry.path, reason: "delete is disabled in v1", executedAt };
+                writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
                 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 });
+            results[index] = { id: entry.id, action: entry.action, status: "review-required", path: entry.path, executedAt };
+            writeCleanupReceipt(receiptPath, { planId, executedAt: cleanupReceiptExecutedAt(results, executedAt), status: "started", results });
         }
-        const receiptPath = receiptPathFor(ledgerPath, planId);
-        const executedAt = toIso(now());
-        writeJson(receiptPath, { planId, executedAt, results });
-        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt, results });
+        const receiptExecutedAt = cleanupReceiptExecutedAt(results, executedAt);
+        updateLedgerAfterCleanup(ledgerPath, records, { planId, receiptPath, executedAt: receiptExecutedAt, results });
+        writeCleanupReceipt(receiptPath, { planId, executedAt: receiptExecutedAt, completedAt: toIso(now()), results });
         registerArtshelfArtifact(ledgerPath, receiptPath, {
             reason: `Artshelf cleanup receipt for plan ${planId}`,
             ttl: "30d",
@@ -598,6 +651,69 @@ export function executeCleanupPlan(ledgerPath, planId) {
         return { planId, receiptPath, results };
     });
 }
+function priorCleanupResultMatchesLedger(record, result, receipt) {
+    if (record.cleanupPlanId !== receipt.planId)
+        return false;
+    if (record.receiptPath !== receipt.receiptPath)
+        return false;
+    if (record.cleanedAt !== receipt.executedAt)
+        return false;
+    if (result.status === "trashed") {
+        return record.status === "trashed" && !!result.target && record.targetPath === result.target;
+    }
+    if (result.status === "review-required") {
+        return record.status === "review-required";
+    }
+    if (result.status === "refused") {
+        return record.status === "cleanup-refused" && (!result.reason || record.cleanupReason === result.reason);
+    }
+    return false;
+}
+function isTerminalCleanupResult(result) {
+    return result.status === "trashed" || result.status === "review-required" || result.status === "refused";
+}
+function cleanupResultExecutedAt(result, receipt, fallback) {
+    if (typeof result.executedAt === "string")
+        return result.executedAt;
+    if (isTerminalCleanupResult(result) && typeof receipt?.executedAt === "string")
+        return receipt.executedAt;
+    return fallback;
+}
+function withCleanupResultExecutedAt(result, executedAt) {
+    return { ...result, executedAt };
+}
+function cleanupReceiptExecutedAt(results, fallback) {
+    const terminalExecutedAt = results
+        .filter(isTerminalCleanupResult)
+        .map((result) => result.executedAt)
+        .filter((value) => typeof value === "string");
+    const firstExecutedAt = terminalExecutedAt[0];
+    if (firstExecutedAt && terminalExecutedAt.every((value) => value === firstExecutedAt)) {
+        return firstExecutedAt;
+    }
+    return fallback;
+}
+function readCleanupReceiptIfValid(receiptPath) {
+    try {
+        return readCleanupReceipt(receiptPath);
+    }
+    catch {
+        return null;
+    }
+}
+function readCleanupReceipt(receiptPath) {
+    const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    return {
+        ...(typeof receipt.planId === "string" ? { planId: receipt.planId } : {}),
+        ...(typeof receipt.executedAt === "string" ? { executedAt: receipt.executedAt } : {}),
+        ...(typeof receipt.completedAt === "string" ? { completedAt: receipt.completedAt } : {}),
+        ...(typeof receipt.status === "string" ? { status: receipt.status } : {}),
+        results: Array.isArray(receipt.results) ? receipt.results : []
+    };
+}
+function writeCleanupReceipt(receiptPath, receipt) {
+    writeJson(receiptPath, receipt);
+}
 // Exported so the reconcile plan layer (src/reconcile.ts) registers its dry-run plan
 // artifacts through the same upsert-by-path-and-labels path that cleanup plans use,
 // keeping plan files tracked and reused under a stable plan id.
@@ -712,31 +828,34 @@ function updateLedgerAfterCleanup(ledgerPath, records, receipt) {
         if (!result)
             return record;
         if (result.status === "trashed") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "trashed",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt,
+                cleanedAt,
                 ...(result.target ? { targetPath: result.target } : {})
             };
         }
         if (result.status === "review-required") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "review-required",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt
+                cleanedAt
             };
         }
         if (result.status === "refused") {
+            const cleanedAt = result.executedAt ?? receipt.executedAt;
             return {
                 ...record,
                 status: "cleanup-refused",
                 cleanupPlanId: receipt.planId,
                 receiptPath: receipt.receiptPath,
-                cleanedAt: receipt.executedAt,
+                cleanedAt,
                 ...(result.reason ? { cleanupReason: result.reason } : {})
             };
         }
@@ -909,5 +1028,5 @@ function assertCleanupPlanExecutable(plan, planId, ledgerPath) {
 }
 function writeJson(path, value) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+    atomicWriteFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
 }

package/docs/agent-clean.html

@@ -38,8 +38,8 @@
           <h1>Execute only what was reviewed and approved.</h1>
           <p class="lede">
             Clean is meant to be boring. The human approves one plan, the agent runs
-            exactly that plan, writes a receipt, and checks that the next review
-            comes back quiet.
+            exactly that plan, leaves durable receipt evidence before moving files,
+            and checks that the next review comes back quiet.
           </p>
 
           <section>
@@ -90,10 +90,11 @@ artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
             <h2>Verify quiet</h2>
             <p>After cleanup execute or resolve, verify with <code>artshelf review --all --json</code>.</p>
             <p>
-              Execution writes a receipt and updates touched ledger records to
-              <code>trashed</code>, <code>review-required</code>, or
-              <code>cleanup-refused</code>. Generated plans and receipts are recorded as
-              <code>owner=artshelf</code> artifacts.
+              Execution writes a started receipt before the first move, completes it after
+              ledger updates, and updates touched ledger records to <code>trashed</code>,
+              <code>review-required</code>, or <code>cleanup-refused</code>. Rerunning the same
+              plan id resumes or idempotently replays durable receipt/trash evidence.
+              Generated plans and receipts are recorded as <code>owner=artshelf</code> artifacts.
             </p>
           </section>
         </article>

package/docs/reference.html

@@ -170,7 +170,9 @@ artshelf cleanup --execute --plan-id <id> [--ledger <path>] [--json]
               <code>--dry-run</code> creates and registers a cleanup plan without moving files;
               no-op dry-runs report <code>not-created</code>, and matching dry-runs reuse the
               existing plan id. <code>--execute</code> is approval-only for one reviewed plan id:
-              it writes a receipt, registers the receipt artifact, and updates touched records in the ledger.
+              it writes a started receipt before the first move, completes and registers the receipt
+              artifact, updates touched records in the ledger, and can resume or idempotently replay
+              the same plan id from durable receipt/trash evidence.
             </p>
             <div class="callout" data-kind="boundary">
               <span class="callout-label">Hard boundary</span>

package/package.json

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

package/skills/artshelf/SKILL.md

@@ -225,8 +225,9 @@ Cleanup execution requires approval naming the reviewed ledger and plan id:
 artshelf cleanup --execute --plan-id <id> --ledger <ledger-path> --json
 ```
 
-Cleanup with `cleanup=trash` quarantines files into Artshelf trash. Physical
-deletion belongs to the separate Purge stage.
+If cleanup is interrupted, rerun the same plan id; durable receipt/trash
+evidence resumes or replays without a fresh plan. `cleanup=trash` quarantines
+files into Artshelf trash. Physical deletion belongs to the separate Purge stage.
 
 Resolve only after confirmation; it updates the ledger and does not move or
 delete files: