artshelf 0.12.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
@@ -110,6 +119,34 @@
   state drifted since review, stamps the reconcile audit trail (`previousPath`,
   `reconcilePlanId`, `reconcileReceiptPath`, `reconciledAt`, `reconcileReason`) on
   every touched row, and writes an Artshelf-owned reconcile receipt.
+- Integrated reconcile findings into `review --agent`, `status --agent`, and
+  `doctor --agent` triage: missing-path warnings now route to reconcile dry-run
+  guidance before approval, reconciled plans escalate to ready-for-approval, and
+  the `ArtshelfReviewReport` schema adds the `reconcile` action type (NGX-438).
+- 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)
+
+
+### Features
+
+* **review:** integrate reconcile findings into agent review packets ([878785e](https://github.com/calvinnwq/artshelf/commit/878785e72c4e65bd8e09572525b05cc020d2f1e1))
+* **review:** integrate reconcile findings into agent triage; move put registry-warning to stderr (NGX-438, NGX-429) ([2573470](https://github.com/calvinnwq/artshelf/commit/25734701b439f617a33609ac98c3fae895199640))
+
+
+### Bug Fixes
+
+* **review:** include reconcile counts in all-ledger triage ([2eeb2fe](https://github.com/calvinnwq/artshelf/commit/2eeb2fea6eae58bfd652be959f2bb6e28d7cb90f))
+* **review:** keep reconcile approval schema and blocked triage consistent ([0c8925a](https://github.com/calvinnwq/artshelf/commit/0c8925a851023622796f2b8d847fcc89cab3c5f0))
 
 ## [0.12.0](https://github.com/calvinnwq/artshelf/compare/artshelf-v0.11.0...artshelf-v0.12.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

@@ -99,8 +99,9 @@ Defaults:
 `put` should refuse to record a path that does not exist unless a future flag
 explicitly supports planned artifacts. After appending the record, `put`
 registers the ledger in the ledger registry. Registry registration is
-best-effort: if it fails, the record remains appended and output includes a
-registry warning or `registryError`.
+best-effort: if it fails, the record remains appended and a registry warning is
+printed to stderr in human mode, or surfaced as a `registryError` field in
+`--json` output, so stdout stays machine-clean.
 
 ### `artshelf ledgers`
 
@@ -253,10 +254,13 @@ included with a `not-created` plan instead of writing a plan file.
 
 In `--all` mode, review emits an aggregate triage summary on top of the
 per-ledger detail. JSON includes a `summary` block with affected-ledger, due,
-manual-review, missing-path, executable, and skipped counts plus the preview
-plan ids; JSON also includes the next safe action. Human output adds a one-line
-triage count and states the same next safe action (repair broken ledgers, dry-run
-cleanup, inspect missing paths, or nothing to do). Review never writes a plan, so
+manual-review, missing-path, executable, skipped, and reconcile entry/blocked
+counts plus the preview plan ids; JSON also includes the next safe action. The
+per-ledger human detail appends a `reconcile` count when a ledger has reconcile
+drift. Human output adds a one-line triage count with the same reconcile counts
+and states the same next safe action (repair broken ledgers, dry-run cleanup,
+dry-run reconcile for missing-path or reconcile drift, or nothing to do). Review
+never writes a plan, so
 the next action always points at an explicit follow-up command.
 
 `review`, `status`, and `doctor` share three render modes. The default human
@@ -265,9 +269,13 @@ stays the full, backward-compatible public audit report; and `--agent` emits a c
 deterministic single-line JSON decision packet for agents, taking precedence over
 `--json` when both are passed. For `review`, the packet sorts records into
 ready-for-approval, needs-review-first, and blocked groups. Because review is
-read-only and never mints a cleanup plan, the only exact approval target it emits
-is `resolve missing`; cleanup-eligible records stay needs-review-first and point
-at `cleanup --dry-run`, which mints the reviewed plan id to approve.
+read-only and never mints a cleanup plan, the exact approval targets it emits are
+`resolve missing` and `reconcile`; the `reconcile` target appears only when a
+prior reviewed reconcile plan still matches the live drift. Cleanup-eligible
+records and reconcile drift without a reviewed plan stay needs-review-first and
+point at `cleanup --dry-run` or `reconcile --dry-run`, which mint the reviewed
+plan id to approve. Blocked or ambiguous reconcile findings surface in the
+blocked group with no approval target.
 
 ### `artshelf doctor`
 
@@ -432,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.
@@ -821,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
@@ -949,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/commands/put.js

@@ -31,6 +31,6 @@ export function handlePut(parsed, ledgerPath, json) {
         return printJson({ ok: true, record, ledgerPath, registryPath, ...(ledger ? { ledger } : {}), ...(registryError ? { registryError } : {}) });
     process.stdout.write(`recorded ${record.id}\npath: ${record.path}\nretains until: ${record.retainUntil ?? "manual review"}\nledger: ${ledgerPath}\n`);
     if (registryError)
-        process.stdout.write(`registry warning: ${registryError}\n`);
+        process.stderr.write(`registry warning: ${registryError}\n`);
     return 0;
 }

package/dist/src/commands/review.js

@@ -15,7 +15,7 @@ export function handleReview(parsed, ledgerPath, json) {
             printCompactJson(buildReviewAgentPacketAll(results, summary, { path: registryPath, exists: existsSync(registryPath) }));
             return ok ? 0 : 1;
         }
-        const nextAction = reviewNextAction(summary, "all");
+        const nextAction = reviewNextAction(summary, "all", undefined, registryPath);
         if (json) {
             printJson({ ok, registryPath, summary, nextAction, ledgers: results.map(reviewJsonResult) });
             return ok ? 0 : 1;

package/dist/src/commands/shared.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { dueEntries, previewCleanupPlan, readLedger, validateLedger } from "../ledger.js";
 import { listRegisteredLedgers } from "../registry.js";
+import { matchingReconcilePlan, previewReconcilePlan } from "../reconcile.js";
 import { printJson } from "../renderers/json.js";
 export function registeredLedgersOrThrow(registryPath) {
     const ledgers = listRegisteredLedgers(registryPath);
@@ -43,15 +44,19 @@ export function reviewLedger(ledger, registered = true) {
             ledgerExists,
             validate,
             due: [],
-            plan: emptyReviewPlan(ledger.path)
+            plan: emptyReviewPlan(ledger.path),
+            reconcile: null
         };
     }
+    const reconcilePlan = previewReconcilePlan(ledger.path);
+    const reviewedReconcilePlan = reconcilePlan.entries.length > 0 || reconcilePlan.blocked.length > 0 ? matchingReconcilePlan(ledger.path, reconcilePlan) : null;
     return {
         ledger,
         ledgerExists,
         validate,
         due: dueEntries(readLedger(ledger.path)),
-        plan: previewCleanupPlan(ledger.path)
+        plan: previewCleanupPlan(ledger.path),
+        reconcile: { plan: reconcilePlan, reviewedPlan: reviewedReconcilePlan }
     };
 }
 export function reviewJsonResult(result) {
@@ -147,6 +152,8 @@ export function summarizeReview(results) {
         missingPath: 0,
         executable: 0,
         skipped: 0,
+        reconcileEntries: 0,
+        reconcileBlocked: 0,
         previewPlanIds: []
     };
     for (const result of results) {
@@ -162,14 +169,18 @@ export function summarizeReview(results) {
         const due = result.due.filter((entry) => entry.dueStatus === "due").length;
         const manualReview = result.due.filter((entry) => entry.dueStatus === "manual-review").length;
         const missingPath = result.due.filter((entry) => entry.dueStatus === "missing-path").length;
+        const reconcileEntries = result.reconcile?.plan.entries.length ?? 0;
+        const reconcileBlocked = result.reconcile?.plan.blocked.length ?? 0;
         summary.due += due;
         summary.manualReview += manualReview;
         summary.missingPath += missingPath;
         summary.executable += result.plan.entries.length;
         summary.skipped += result.plan.skipped.length;
+        summary.reconcileEntries += reconcileEntries;
+        summary.reconcileBlocked += reconcileBlocked;
         if (result.plan.planId !== "not-created")
             summary.previewPlanIds.push(result.plan.planId);
-        if (!result.validate.ok || due + manualReview + missingPath > 0 || result.plan.entries.length > 0) {
+        if (!result.validate.ok || due + manualReview + missingPath + reconcileEntries + reconcileBlocked > 0 || result.plan.entries.length > 0) {
             summary.affected += 1;
         }
     }

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/dist/src/reconcile.js

@@ -64,6 +64,9 @@ export function createReconcilePlan(ledgerPath) {
     });
     return reviewed;
 }
+export function matchingReconcilePlan(ledgerPath, plan) {
+    return matchingExistingReconcilePlan(ledgerPath, plan);
+}
 // Apply a reviewed reconcile plan (NGX-437 `reconcile --execute`). This is the only
 // mutating reconcile entrypoint and it is deliberately conservative:
 //   * It refuses up front when the plan id is missing, the plan file is absent, or the

package/dist/src/renderers/doctor.js

@@ -3,12 +3,12 @@ const DOCTOR_ATTENTION_CATEGORIES = ["stale", "invalid", "warnings"];
 function doctorAttention(summary) {
     return DOCTOR_ATTENTION_CATEGORIES.filter((key) => summary[key] > 0);
 }
-function doctorNextAction(blockers, summary) {
+function doctorNextAction(blockers, summary, registryPath) {
     if (blockers.length > 0) {
         return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
     }
     if (summary.warnings > 0) {
-        return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf validate --all\` to inspect; nothing is auto-executed`;
+        return `healthy, but ${summary.warnings} warning(s) noted — run \`artshelf reconcile --dry-run --all --registry ${registryPath}\` to prepare reconcile-ready approvals, then run \`artshelf review --all --registry ${registryPath}\`; nothing is auto-executed`;
     }
     return "artshelf is healthy on this machine — cleanup safety enforced; no action needed";
 }
@@ -39,7 +39,7 @@ export function buildDoctorAgentPacket(report) {
         attention: doctorAttention(report.summary),
         blockers,
         cleanupSafety: report.cleanupSafety,
-        nextAction: doctorNextAction(blockers, report.summary),
+        nextAction: doctorNextAction(blockers, report.summary, report.registryPath),
         verification: `artshelf doctor --agent --registry ${report.registryPath}`
     };
 }