artshelf 0.11.0 → 0.13.0

package/dist/src/provenance.js

@@ -0,0 +1,142 @@
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+// Capture reconcile-safe provenance for an absolute artifact path. The matched root
+// plus the relative path against it is what survives a `shelf` -> `artshelf` or
+// `.shelf` -> `.artshelf` rename: a future reconcile can rebuild the current path
+// from the current root without Artshelf watching the filesystem. This reads the
+// filesystem to classify the node and fingerprint files; it never mutates anything.
+export function computeProvenance(targetPath, context) {
+    const absolute = resolve(targetPath);
+    const ledgerRoot = resolveLedgerRoot(context.ledgerPath);
+    const repoRoot = findRepoRoot(ledgerRoot);
+    const node = classifyNode(absolute);
+    // Ledger-owned paths are the most specific root, so they win over the repo root:
+    // trash/, plans/, and receipts/ all live under the ledger directory.
+    if (isWithin(ledgerRoot, absolute)) {
+        return reconstructable("ledger", ledgerRoot, absolute, node);
+    }
+    if (repoRoot && isWithin(repoRoot, absolute)) {
+        return reconstructable("repo", repoRoot, absolute, node);
+    }
+    return {
+        root: "external",
+        rootPath: null,
+        relativePath: null,
+        basename: basename(absolute),
+        pathKind: node.kind,
+        ...(node.fingerprint ? { fingerprint: node.fingerprint } : {})
+    };
+}
+const ROOT_KINDS = new Set(["repo", "ledger", "external"]);
+const NODE_KINDS = new Set(["file", "directory", "other"]);
+// Validate a provenance value carried on a record. Returns a list of problems
+// (empty means well-formed). This is the line between a legacy row (no provenance
+// field at all, which callers skip) and a malformed one: once provenance is present
+// it must conform to the PathProvenance contract, including the rule that only
+// `external` roots drop the reconstruct data (rootPath/relativePath).
+export function validateProvenance(provenance) {
+    if (typeof provenance !== "object" || provenance === null) {
+        return ["provenance must be an object"];
+    }
+    const value = provenance;
+    const problems = [];
+    if (typeof value.root !== "string" || !ROOT_KINDS.has(value.root)) {
+        problems.push(`provenance.root is invalid: ${String(value.root)}`);
+    }
+    if (typeof value.basename !== "string" || value.basename.length === 0) {
+        problems.push("provenance.basename must be a non-empty string");
+    }
+    if (typeof value.pathKind !== "string" || !NODE_KINDS.has(value.pathKind)) {
+        problems.push(`provenance.pathKind is invalid: ${String(value.pathKind)}`);
+    }
+    if (value.rootPath !== null && typeof value.rootPath !== "string") {
+        problems.push("provenance.rootPath must be a string or null");
+    }
+    if (value.relativePath !== null && typeof value.relativePath !== "string") {
+        problems.push("provenance.relativePath must be a string or null");
+    }
+    // Reconstruct-data consistency: external paths cannot be rebuilt, so they carry
+    // null rootPath/relativePath; repo/ledger paths must carry both to be remappable.
+    if (value.root === "external") {
+        if (value.rootPath !== null || value.relativePath !== null) {
+            problems.push("provenance with external root must have null rootPath and relativePath");
+        }
+    }
+    else if (value.root === "repo" || value.root === "ledger") {
+        if (typeof value.rootPath !== "string" || typeof value.relativePath !== "string") {
+            problems.push(`provenance with ${value.root} root requires rootPath and relativePath`);
+        }
+    }
+    if (value.fingerprint !== undefined) {
+        const fingerprint = value.fingerprint;
+        if (typeof fingerprint !== "object" || fingerprint === null || typeof fingerprint.byteSize !== "number") {
+            problems.push("provenance.fingerprint must have a numeric byteSize");
+        }
+    }
+    return problems;
+}
+// The current ledger root: the directory that owns trash/, plans/, and receipts/.
+// Provenance with a `ledger` root stores paths relative to this, so a reconcile can
+// re-root them under the current ledger directory after a `.shelf` -> `.artshelf` move.
+export function resolveLedgerRoot(ledgerPath) {
+    return resolve(dirname(ledgerPath));
+}
+// The current repo root for a ledger, using the same resolution as capture time:
+// the enclosing git checkout, or the parent of a dotted ledger directory. Returns
+// null when no repo root can be determined (e.g. a user-global ledger).
+export function resolveRepoRoot(ledgerPath) {
+    return findRepoRoot(resolveLedgerRoot(ledgerPath));
+}
+function reconstructable(root, rootPath, absolute, node) {
+    return {
+        root,
+        rootPath,
+        relativePath: toPosix(relative(rootPath, absolute)),
+        basename: basename(absolute),
+        pathKind: node.kind,
+        ...(node.fingerprint ? { fingerprint: node.fingerprint } : {})
+    };
+}
+function findRepoRoot(ledgerRoot) {
+    const gitRoot = findGitRoot(ledgerRoot);
+    if (gitRoot)
+        return gitRoot;
+    // No git checkout: a dotted ledger directory (.artshelf / .shelf) sits directly
+    // inside its repo/folder, so the parent is the best repo-root candidate.
+    if (basename(ledgerRoot).startsWith(".")) {
+        const parent = dirname(ledgerRoot);
+        return parent === ledgerRoot ? null : parent;
+    }
+    return null;
+}
+function findGitRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function classifyNode(absolute) {
+    try {
+        const stats = statSync(absolute);
+        if (stats.isFile())
+            return { kind: "file", fingerprint: { byteSize: stats.size } };
+        if (stats.isDirectory())
+            return { kind: "directory" };
+        return { kind: "other" };
+    }
+    catch {
+        return { kind: "other" };
+    }
+}
+function isWithin(parent, child) {
+    const fromParent = relative(parent, child);
+    return fromParent === "" || (!fromParent.startsWith("..") && !isAbsolute(fromParent));
+}
+function toPosix(path) {
+    return sep === "/" ? path : path.split(sep).join("/");
+}

package/dist/src/reconcile.js

@@ -0,0 +1,335 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { assertSafeGeneratedId, readLedger, registerArtshelfArtifact, writeLedger } from "./ledger.js";
+import { withPathLock } from "./locks.js";
+import { computeProvenance, resolveLedgerRoot, resolveRepoRoot } from "./provenance.js";
+import { now, toIso } from "./time.js";
+const RECONCILE_CATEGORIES = new Set([
+    "remap",
+    "resolve-missing",
+    "resolve-stale-trash",
+    "registry-remap",
+    "blocked"
+]);
+// Classify path drift in a ledger into reconcile findings (NGX-437). This is the
+// read-only engine the dry-run/execute workflow builds on: it never mutates the
+// ledger or the filesystem, it only reads records and probes whether recorded paths
+// still exist (and whether a renamed root can reconstruct them via provenance).
+// Findings are returned in ledger order so downstream JSON output is deterministic.
+export function classifyReconcileFindings(ledgerPath) {
+    const records = readLedger(ledgerPath);
+    const roots = {
+        ledgerRoot: resolveLedgerRoot(ledgerPath),
+        repoRoot: resolveRepoRoot(ledgerPath)
+    };
+    const findings = [];
+    for (const record of records) {
+        const finding = classifyRecord(record, roots);
+        if (finding)
+            findings.push(finding);
+    }
+    return findings;
+}
+// Build the reconcile plan without persisting anything (NGX-437 dry-run preview).
+// This is fully read-only: it classifies drift and returns the plan a `--dry-run`
+// would create, but never writes a plan file or touches the ledger. An empty plan
+// (no actionable entries) collapses to the not-created shape so callers can render
+// "nothing to reconcile" the same way cleanup does.
+export function previewReconcilePlan(ledgerPath) {
+    const plan = buildReconcilePlan(ledgerPath);
+    return plan.entries.length === 0 ? noCreatedReconcilePlan(plan) : plan;
+}
+// Create (or reuse) a reviewed reconcile plan (NGX-437 dry-run). This is the only
+// part of dry-run that writes: it persists the plan JSON and registers it as an
+// artshelf-owned artifact so the plan file is tracked and a later `--execute` can
+// bind to an exact reviewed plan id. When an earlier plan already covers the same
+// findings it is reused verbatim (stable plan id), and when nothing is actionable
+// no plan artifact is created at all, keeping dry-run side-effect-free in that case.
+export function createReconcilePlan(ledgerPath) {
+    const plan = buildReconcilePlan(ledgerPath);
+    if (plan.entries.length === 0)
+        return noCreatedReconcilePlan(plan);
+    const existing = matchingExistingReconcilePlan(ledgerPath, plan);
+    const reviewed = existing ? { ...plan, planId: existing.planId, planPath: existing.planPath } : plan;
+    if (!reviewed.planPath)
+        throw new Error("reconcile plan path was not created");
+    writeReconcilePlanFile(reviewed.planPath, reviewed);
+    registerArtshelfArtifact(ledgerPath, reviewed.planPath, {
+        reason: `Artshelf reconcile dry-run plan ${reviewed.planId}`,
+        ttl: "14d",
+        kind: "run-artifact",
+        cleanup: "trash",
+        labels: ["artshelf", "reconcile-plan", reviewed.planId]
+    });
+    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
+//     plan file's declared id/ledger does not match the scoped request (no fresh plan,
+//     no `--all`; the command layer enforces those, this binds to one exact plan id).
+//   * Before applying any entry it re-classifies the live ledger and only acts when the
+//     current finding still matches the reviewed entry, so a plan executed against a
+//     drifted ledger refuses the stale entries instead of mutating the wrong rows.
+// Reconcile is ledger/registry housekeeping only: it rewrites paths and resolves rows
+// and writes a receipt; it never creates or deletes filesystem artifacts.
+export function executeReconcilePlan(ledgerPath, planId) {
+    if (!planId)
+        throw new Error("reconcile --execute requires --plan-id");
+    const planPath = reconcilePlanPath(ledgerPath, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Reconcile plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertReconcilePlanExecutable(plan, planId, ledgerPath);
+    const receiptPath = reconcileReceiptPath(ledgerPath, planId);
+    return withPathLock(ledgerPath, () => {
+        const records = readLedger(ledgerPath);
+        const recordsById = new Map(records.map((record) => [record.id, record]));
+        const liveById = new Map(classifyReconcileFindings(ledgerPath).map((finding) => [finding.id, finding]));
+        const executedAt = toIso(now());
+        const audit = { reconcilePlanId: planId, reconcileReceiptPath: receiptPath, reconciledAt: executedAt };
+        const results = [];
+        for (const entry of plan.entries) {
+            const record = recordsById.get(entry.id);
+            const live = liveById.get(entry.id);
+            if (!record || !live || !sameReconcileTarget(live, entry)) {
+                results.push(skippedResult(entry));
+                continue;
+            }
+            const applied = applyReconcileEntry(record, entry, audit, ledgerPath);
+            recordsById.set(entry.id, applied);
+            results.push(appliedResult(entry, applied));
+        }
+        writeReconcileReceipt(receiptPath, { planId, ledgerPath, executedAt, results });
+        writeLedger(ledgerPath, records.map((record) => recordsById.get(record.id) ?? record));
+        registerArtshelfArtifact(ledgerPath, receiptPath, {
+            reason: `Artshelf reconcile receipt for plan ${planId}`,
+            ttl: "30d",
+            kind: "run-artifact",
+            cleanup: "review",
+            labels: ["artshelf", "reconcile-receipt", planId]
+        });
+        return { planId, receiptPath, executedAt, results };
+    }, "Artshelf ledger");
+}
+// Produce the mutated record for one applicable entry. A remap rewrites the path and
+// recomputes provenance against the new location (so the row is reconcile-healthy
+// afterwards) while keeping the row's status; every resolve category archives the row
+// ledger-only as `resolved`. previousPath always preserves the pre-action path.
+function applyReconcileEntry(record, entry, audit, ledgerPath) {
+    if (entry.category === "remap" && entry.proposedPath) {
+        return {
+            ...record,
+            path: entry.proposedPath,
+            provenance: computeProvenance(entry.proposedPath, { ledgerPath }),
+            previousPath: entry.currentPath,
+            ...audit,
+            reconcileReason: entry.reason
+        };
+    }
+    return {
+        ...record,
+        status: "resolved",
+        resolvedAt: audit.reconciledAt,
+        resolutionReason: entry.reason,
+        previousPath: entry.currentPath,
+        ...audit,
+        reconcileReason: entry.reason
+    };
+}
+function appliedResult(entry, applied) {
+    return {
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        status: applied.status === "resolved" ? "resolved" : "remapped",
+        previousPath: entry.currentPath,
+        newPath: entry.category === "remap" ? entry.proposedPath : null,
+        reason: entry.reason
+    };
+}
+function skippedResult(entry) {
+    return {
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        status: "skipped",
+        previousPath: entry.currentPath,
+        newPath: null,
+        reason: "live ledger state no longer matches the reviewed plan"
+    };
+}
+// Two findings describe the same drift only when every structural field agrees; this
+// is the execute-time safety check that refuses entries whose live state has moved on.
+function sameReconcileTarget(live, entry) {
+    return (live.category === entry.category &&
+        live.field === entry.field &&
+        live.status === entry.status &&
+        live.currentPath === entry.currentPath &&
+        live.proposedPath === entry.proposedPath);
+}
+// Bind a loaded reconcile plan to the request before any ledger mutation, mirroring
+// cleanup's assertCleanupPlanExecutable: the plan must declare the requested id, belong
+// to the executing ledger, and carry well-formed entries.
+function assertReconcilePlanExecutable(plan, planId, ledgerPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Reconcile plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.ledgerPath !== ledgerPath) {
+        throw new Error(`Reconcile plan ledger mismatch: plan was created for ${plan.ledgerPath}, executing ${ledgerPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Reconcile plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.id !== "string" || typeof entry.currentPath !== "string" || !RECONCILE_CATEGORIES.has(entry.category)) {
+            throw new Error(`Reconcile plan entries are malformed: ${planId}`);
+        }
+    }
+}
+function reconcileReceiptPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "reconcile plan id");
+    return join(dirname(ledgerPath), "reconcile-receipts", `${planId}.json`);
+}
+function writeReconcileReceipt(receiptPath, value) {
+    mkdirSync(dirname(receiptPath), { recursive: true });
+    writeFileSync(receiptPath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function classifyRecord(record, roots) {
+    // A trashed row's original path is expected to be empty (it was moved to trash),
+    // so the only path that matters is the trash target.
+    if (record.status === "trashed")
+        return classifyTrashTarget(record);
+    // Live rows are the ones whose recorded artifact path should still exist. This
+    // mirrors validateLedger's "recorded path is missing" warning surface.
+    if (record.status === "active" || record.status === "review-required") {
+        return classifyActivePath(record, roots);
+    }
+    // resolved / cleanup-refused rows are terminal for reconcile purposes.
+    return null;
+}
+function classifyActivePath(record, roots) {
+    if (!record.path || existsSync(record.path))
+        return null;
+    const provenance = record.provenance;
+    const candidate = reconstructPath(provenance, roots);
+    if (provenance && candidate && existsSync(candidate)) {
+        if (isSafeMatch(provenance, candidate)) {
+            return finding(record, "remap", "path", record.path, candidate, `recorded path is missing; reconstructed at ${candidate}`);
+        }
+        return finding(record, "blocked", "path", record.path, null, `a candidate exists at ${candidate} but its name or fingerprint does not match the recorded artifact`);
+    }
+    return finding(record, "resolve-missing", "path", record.path, null, "recorded path is missing and no safe remap target was found");
+}
+function classifyTrashTarget(record) {
+    // Missing cleanup metadata on a trashed row is validateLedger's concern, not ours.
+    if (!record.targetPath || existsSync(record.targetPath))
+        return null;
+    return finding(record, "resolve-stale-trash", "targetPath", record.targetPath, null, "trashed target is missing; resolve the ledger row without touching the filesystem");
+}
+// Re-root a provenance-relative path under the current ledger/repo root. Only
+// reconstructable roots (repo/ledger) with a stored relative path can be rebuilt;
+// external paths and legacy rows without provenance return null.
+function reconstructPath(provenance, roots) {
+    if (!provenance || provenance.relativePath === null)
+        return null;
+    if (provenance.root === "repo") {
+        return roots.repoRoot ? join(roots.repoRoot, fromPosix(provenance.relativePath)) : null;
+    }
+    if (provenance.root === "ledger") {
+        return join(roots.ledgerRoot, fromPosix(provenance.relativePath));
+    }
+    return null;
+}
+// A reconstructed candidate is only trusted when its basename matches and, for
+// files with a captured fingerprint, its byte size matches too. Directories and
+// fingerprint-less rows fall back to name plus existence as the evidence.
+function isSafeMatch(provenance, candidate) {
+    if (basename(candidate) !== provenance.basename)
+        return false;
+    if (provenance.pathKind === "file" && provenance.fingerprint) {
+        try {
+            return statSync(candidate).size === provenance.fingerprint.byteSize;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+function finding(record, category, field, currentPath, proposedPath, reason) {
+    return { id: record.id, category, field, status: record.status, currentPath, proposedPath, reason };
+}
+function fromPosix(path) {
+    return sep === "/" ? path : path.split("/").join(sep);
+}
+// Split classified findings into a plan: actionable entries (everything a scoped
+// `--execute` may apply) versus blocked findings (surfaced for review only). The
+// plan id/path are computed up front so a dry-run can persist deterministically.
+function buildReconcilePlan(ledgerPath) {
+    const generatedAt = now();
+    const findings = classifyReconcileFindings(ledgerPath);
+    const entries = findings.filter((finding) => finding.category !== "blocked");
+    const blocked = findings.filter((finding) => finding.category === "blocked");
+    const planId = makeReconcilePlanId(generatedAt);
+    return {
+        planId,
+        generatedAt: toIso(generatedAt),
+        ledgerPath,
+        entries,
+        blocked,
+        planPath: reconcilePlanPath(ledgerPath, planId)
+    };
+}
+function noCreatedReconcilePlan(plan) {
+    return { ...plan, planId: "not-created", planPath: null };
+}
+// Reuse an earlier plan whose actionable entries match this one's, so repeated
+// dry-runs converge on a single stable plan id (mirrors cleanup plan reuse). Only
+// the structural entry fields are fingerprinted; volatile fields (generatedAt) and
+// the review-only blocked list do not affect reuse.
+function matchingExistingReconcilePlan(ledgerPath, plan) {
+    const plansDir = join(dirname(ledgerPath), "reconcile-plans");
+    if (!existsSync(plansDir))
+        return null;
+    const filenames = readdirSync(plansDir).filter((name) => name.endsWith(".json")).sort().reverse();
+    for (const filename of filenames) {
+        const planPath = join(plansDir, filename);
+        try {
+            const candidate = JSON.parse(readFileSync(planPath, "utf8"));
+            if (candidate.ledgerPath !== ledgerPath)
+                continue;
+            if (reconcilePlanFingerprint(candidate) !== reconcilePlanFingerprint(plan))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function reconcilePlanFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({
+        id: entry.id,
+        category: entry.category,
+        field: entry.field,
+        currentPath: entry.currentPath,
+        proposedPath: entry.proposedPath
+    })));
+}
+function writeReconcilePlanFile(planPath, plan) {
+    mkdirSync(dirname(planPath), { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function makeReconcilePlanId(date) {
+    return `reconcile_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function reconcilePlanPath(ledgerPath, planId) {
+    assertSafeGeneratedId(planId, "reconcile plan id");
+    return join(dirname(ledgerPath), "reconcile-plans", `${planId}.json`);
+}

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}`
     };
 }

package/dist/src/renderers/review.js

@@ -7,7 +7,7 @@ const REVIEW_SAFETY = {
     noResolveRan: true,
     noDeleteRan: true
 };
-export function reviewNextAction(summary, scope, ledgerPath) {
+export function reviewNextAction(summary, scope, ledgerPath, registryPath) {
     const broken = summary.invalid + summary.stale;
     const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
@@ -18,25 +18,30 @@ export function reviewNextAction(summary, scope, ledgerPath) {
         const dryRun = scope === "all" ? "artshelf cleanup --dry-run --all" : `artshelf cleanup --dry-run${ledgerPath ? ` --ledger ${ledgerPath}` : ""}`;
         return `run \`${dryRun}\` to generate plans, then \`artshelf cleanup --execute --plan-id <id> --ledger <path>\` for each reviewed plan`;
     }
-    if (summary.missingPath > 0) {
-        return "inspect missing-path entries and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+    if (summary.missingPath > 0 || summary.reconcileEntries > 0 || summary.reconcileBlocked > 0) {
+        const reconcile = scope === "all" ? `artshelf reconcile --dry-run --all${registryPath ? ` --registry ${registryPath}` : ""}` : `artshelf reconcile --dry-run --ledger ${ledgerPath}`;
+        return `run \`${reconcile} --json\` and then \`${review}\` to surface reconcile-ready approvals; nothing is auto-executable`;
     }
     return "nothing to do — no broken ledgers and no due, manual-review, missing-path, or executable cleanup entries";
 }
 export function printReviewAll(results, summary, nextAction, registryPath) {
-    const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath > 0;
+    const needsAttention = summary.invalid + summary.stale + summary.executable + summary.due + summary.manualReview + summary.missingPath + summary.reconcileEntries + summary.reconcileBlocked > 0;
     process.stdout.write(`${attentionGlyph(needsAttention)} artshelf review --all: ${needsAttention ? "needs attention" : "all clear"}\n`);
     process.stdout.write(`registry: ${registryPath} — ${summary.ledgers} ledgers (${summary.ok} ok, ${summary.invalid} invalid, ${summary.stale} stale)\n`);
     printReview(results);
-    process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped}\n`);
+    process.stdout.write(`triage: due ${summary.due} · manual-review ${summary.manualReview} · missing ${summary.missingPath} · executable ${summary.executable} · skipped ${summary.skipped} · reconcile ${summary.reconcileEntries} · blocked ${summary.reconcileBlocked}\n`);
     process.stdout.write(`next: ${nextAction}\n`);
 }
 export function printReview(results) {
     for (const result of results) {
         const visibleDue = result.due.filter((entry) => entry.dueStatus !== "kept");
-        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0;
+        const reconcileEntries = result.reconcile?.plan.entries.length ?? 0;
+        const reconcileBlocked = result.reconcile?.plan.blocked.length ?? 0;
+        const reconcileDrift = reconcileEntries + reconcileBlocked;
+        const needsAttention = !result.validate.ok || visibleDue.length > 0 || result.plan.entries.length > 0 || reconcileDrift > 0;
+        const reconcileDetail = reconcileDrift > 0 ? `; reconcile: ${reconcileEntries} entries, ${reconcileBlocked} blocked` : "";
         process.stdout.write(`${attentionGlyph(needsAttention)} [${result.ledger.name}] ${result.validate.ok ? "ok" : "invalid"}: ${result.validate.entries} entries, ${result.validate.errors.length} errors, ${result.validate.warnings.length} warnings\n`);
-        process.stdout.write(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped\n`);
+        process.stdout.write(`due/manual/missing: ${visibleDue.length}; plan ${result.plan.planId}: ${result.plan.entries.length} entries, ${result.plan.skipped.length} skipped${reconcileDetail}\n`);
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
@@ -60,7 +65,15 @@ function buildReviewDecisions(results, scope) {
             });
             continue;
         }
-        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path");
+        const handledReconcileIds = new Set([
+            ...(result.reconcile?.plan.entries.map((entry) => entry.id) ?? []),
+            ...(result.reconcile?.plan.blocked.map((entry) => entry.id) ?? [])
+        ]);
+        const reconcileActions = buildReconcileDecisions(result, scope);
+        readyForApproval.push(...reconcileActions.readyForApproval);
+        needsReviewFirst.push(...reconcileActions.needsReviewFirst);
+        blocked.push(...reconcileActions.blocked);
+        const missingPath = due.filter((entry) => entry.dueStatus === "missing-path" && !handledReconcileIds.has(entry.id));
         const trashSafe = due.filter((entry) => entry.dueStatus === "due" && entry.cleanup === "trash");
         const inspectItems = due.filter((entry) => entry.dueStatus === "manual-review" ||
             (entry.dueStatus === "due" && (entry.cleanup === "review" || entry.cleanup === "delete")));
@@ -103,6 +116,57 @@ function buildReviewDecisions(results, scope) {
     }
     return { readyForApproval, needsReviewFirst, blocked };
 }
+function buildReconcileDecisions(result, _scope) {
+    if (!result.reconcile)
+        return { readyForApproval: [], needsReviewFirst: [], blocked: [] };
+    const readyForApproval = [];
+    const needsReviewFirst = [];
+    const blocked = [];
+    const hasReviewedPlan = Boolean(result.reconcile.reviewedPlan && result.reconcile.reviewedPlan.planId !== "not-created");
+    const reviewedPlanId = result.reconcile.reviewedPlan?.planId ?? null;
+    const byCategory = {
+        remap: [],
+        "resolve-missing": [],
+        "resolve-stale-trash": [],
+        "registry-remap": [],
+        blocked: []
+    };
+    for (const finding of result.reconcile.plan.entries.concat(result.reconcile.plan.blocked)) {
+        byCategory[finding.category].push(finding);
+    }
+    const reconcileActionCategories = ["remap", "resolve-missing", "resolve-stale-trash", "registry-remap"];
+    for (const category of reconcileActionCategories) {
+        const entries = byCategory[category];
+        if (entries.length === 0)
+            continue;
+        const ids = entries.map((entry) => entry.id).sort();
+        const label = `Review ${entries.length} reconcile ${category} finding(s) in ${result.ledger.name}`;
+        const reason = `recorded paths are ${category === "remap" ? "safe to remap" : "stale and require manual review before execution"}`;
+        const decision = {
+            label,
+            itemIds: ids,
+            actionType: "reconcile",
+            approvalTarget: hasReviewedPlan ? `approve artshelf reconcile ledger ${result.ledger.path} plan ${reviewedPlanId}` : null,
+            reason,
+            nextStep: hasReviewedPlan
+                ? `run \`artshelf reconcile --execute --plan-id ${reviewedPlanId} --ledger ${result.ledger.path}\``
+                : `run \`artshelf reconcile --dry-run --ledger ${result.ledger.path} --json\`, then approve with \`approve artshelf reconcile ledger ${result.ledger.path} plan <plan-id>\``
+        };
+        (hasReviewedPlan ? readyForApproval : needsReviewFirst).push(decision);
+    }
+    if (byCategory.blocked.length > 0) {
+        const entries = byCategory.blocked;
+        blocked.push({
+            label: `Review ${entries.length} blocked reconcile finding(s) in ${result.ledger.name}`,
+            itemIds: entries.map((entry) => entry.id).sort(),
+            actionType: "reconcile",
+            approvalTarget: null,
+            reason: "path drift is ambiguous or unsafe and needs manual investigation",
+            nextStep: `run \`artshelf reconcile --dry-run --ledger ${result.ledger.path} --json\`, then handle each item manually`
+        });
+    }
+    return { readyForApproval, needsReviewFirst, blocked };
+}
 function reviewCounts(summary) {
     return {
         due: summary.due,
@@ -131,7 +195,7 @@ export function buildReviewAgentPacketAll(results, summary, registry) {
         needsReviewFirst: groups.needsReviewFirst,
         blocked: groups.blocked,
         safety: REVIEW_SAFETY,
-        nextAction: reviewNextAction(summary, "all"),
+        nextAction: reviewNextAction(summary, "all", undefined, registry.path),
         verification: `artshelf review --all --agent --registry ${registry.path}`
     };
 }

package/dist/src/renderers/status.js

@@ -14,7 +14,7 @@ export function statusCommand(scope, command, ledgerPath) {
         return `artshelf ${command} --all`;
     return ledgerPath ? `artshelf ${command} --ledger ${ledgerPath}` : `artshelf ${command}`;
 }
-function statusNextAction(blockers, counts, scope, ledgerPath) {
+function statusNextAction(blockers, counts, scope, ledgerPath, registryPath) {
     if (blockers.length > 0) {
         const verify = statusCommand(scope, "status", ledgerPath);
         return `repair ${blockers.length} broken ledger(s) above, then re-run \`${verify}\``;
@@ -27,7 +27,8 @@ function statusNextAction(blockers, counts, scope, ledgerPath) {
         return `run \`${review}\` to inspect manual-review records; nothing is auto-executed`;
     }
     if (counts.missingPath > 0) {
-        return "inspect missing-path records and `artshelf resolve` the ones no longer needed; nothing is auto-executable";
+        const reconcile = scope === "all" ? `artshelf reconcile --dry-run --all${registryPath ? ` --registry ${registryPath}` : ""}` : `artshelf reconcile --dry-run --ledger ${ledgerPath}`;
+        return `run \`${reconcile} --json\` and then \`${review}\` to surface reconcile-ready approvals; nothing is auto-executable`;
     }
     return "nothing due — no broken ledgers and no due, manual-review, missing-path, or pending cleanup entries";
 }
@@ -58,7 +59,7 @@ export function buildStatusAgentPacketAll(report) {
         counts,
         attention: statusAttention(counts),
         blockers,
-        nextAction: statusNextAction(blockers, counts, "all"),
+        nextAction: statusNextAction(blockers, counts, "all", undefined, report.registryPath),
         verification: `artshelf status --all --agent --registry ${report.registryPath}`
     };
 }