artshelf 0.13.1 → 0.15.0

package/dist/src/inspect.js

@@ -0,0 +1,204 @@
+import * as fs from "node:fs";
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { shellArg } from "./shared/shell-quote.js";
+import { ageOf, now as currentTime } from "./time.js";
+const DIRECTORY_SIZE_MAX_ENTRIES = 10_000;
+const openDirectorySync = fs.opendirSync;
+export function buildInspectReport(record, options) {
+    const at = options.now ?? currentTime();
+    const subjectPath = subjectPathOf(record);
+    const node = describeNode(subjectPath, record.status === "active");
+    const dueState = classifyDueState(record, at, node.existence);
+    const { recommendation, nextAction } = recommend(record, node.existence, dueState, options.ledgerPath);
+    return {
+        schemaVersion: 1,
+        id: record.id,
+        path: record.path,
+        subjectPath,
+        kind: record.kind,
+        owner: record.owner,
+        labels: record.labels,
+        status: record.status,
+        cleanup: record.cleanup,
+        reason: record.reason,
+        existence: node.existence,
+        nodeKind: node.nodeKind,
+        byteSize: node.byteSize,
+        byteSizeTruncated: node.byteSizeTruncated,
+        age: ageOf(at, record.createdAt),
+        retention: record.retention,
+        retainUntil: record.retainUntil ?? null,
+        dueState,
+        recommendation,
+        nextAction
+    };
+}
+function subjectPathOf(record) {
+    if (record.status === "trashed" && record.targetPath)
+        return record.targetPath;
+    return record.path;
+}
+function describeNode(subjectPath, followSymlinkExistence = false) {
+    if (followSymlinkExistence && !existsSync(subjectPath)) {
+        return { existence: "missing", nodeKind: null, byteSize: null, byteSizeTruncated: false };
+    }
+    let stat;
+    try {
+        stat = lstatSync(subjectPath);
+    }
+    catch {
+        return { existence: "missing", nodeKind: null, byteSize: null, byteSizeTruncated: false };
+    }
+    if (stat.isSymbolicLink())
+        return { existence: "present", nodeKind: "other", byteSize: null, byteSizeTruncated: false };
+    if (stat.isFile())
+        return { existence: "present", nodeKind: "file", byteSize: stat.size, byteSizeTruncated: false };
+    if (stat.isDirectory()) {
+        const size = directorySize(subjectPath);
+        return { existence: "present", nodeKind: "directory", byteSize: size.bytes, byteSizeTruncated: size.truncated };
+    }
+    return { existence: "present", nodeKind: "other", byteSize: null, byteSizeTruncated: false };
+}
+// Bounded recursive size: sums regular-file bytes, never follows symlinks, and stops at
+// a fixed entry budget so a pathological tree cannot stall a read-only inspect.
+function directorySize(root) {
+    let total = 0;
+    let visited = 0;
+    let incomplete = false;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let entries;
+        try {
+            entries = openDirectorySync(dir);
+        }
+        catch {
+            incomplete = true;
+            continue;
+        }
+        try {
+            while (true) {
+                let entry;
+                try {
+                    entry = entries.readSync();
+                }
+                catch {
+                    incomplete = true;
+                    break;
+                }
+                if (entry === null)
+                    break;
+                if (visited >= DIRECTORY_SIZE_MAX_ENTRIES)
+                    return { bytes: total, truncated: true };
+                visited += 1;
+                const child = join(dir, entry.name);
+                let stat;
+                try {
+                    stat = lstatSync(child);
+                }
+                catch {
+                    incomplete = true;
+                    continue;
+                }
+                if (stat.isSymbolicLink())
+                    continue;
+                if (stat.isDirectory()) {
+                    stack.push(child);
+                    continue;
+                }
+                if (stat.isFile())
+                    total += stat.size;
+            }
+        }
+        finally {
+            try {
+                entries.closeSync();
+            }
+            catch {
+                incomplete = true;
+            }
+        }
+    }
+    return { bytes: total, truncated: incomplete };
+}
+// Mirrors ledger due classification, but reuses the existence already observed so a
+// trashed/terminal record never re-stats. Only active records carry a due state.
+function classifyDueState(record, at, existence) {
+    if (record.status !== "active")
+        return null;
+    if (existence === "missing")
+        return "missing-path";
+    if (record.retention.mode === "manual-review")
+        return "manual-review";
+    if (!record.retainUntil)
+        return "due";
+    return new Date(record.retainUntil).getTime() <= at.getTime() ? "due" : "kept";
+}
+function recommend(record, existence, dueState, ledgerPath) {
+    const idArg = shellArg(record.id);
+    const ledgerArg = shellArg(ledgerPath);
+    if (record.status === "resolved") {
+        return { recommendation: "keep", nextAction: "Already resolved — no action needed." };
+    }
+    if (record.status === "trashed") {
+        if (existence === "missing") {
+            return {
+                recommendation: "resolve-only",
+                nextAction: `Trashed target is missing — confirm the artifact is gone, then run \`artshelf resolve ${idArg} --ledger ${ledgerArg} --status resolved --reason '<why>'\` (ledger-only).`
+            };
+        }
+        return {
+            recommendation: "keep",
+            nextAction: "Already trashed — permanent removal is the separate approval-gated `artshelf trash purge` flow."
+        };
+    }
+    if (record.status === "review-required") {
+        return {
+            recommendation: "blocked",
+            nextAction: "A cleanup run flagged this for manual review — inspect the artifact, then resolve or re-plan deliberately."
+        };
+    }
+    if (record.status === "cleanup-refused") {
+        return {
+            recommendation: "blocked",
+            nextAction: "A prior cleanup refused this record — handle it manually; Artshelf will not retry automatically."
+        };
+    }
+    if (existence === "missing" || dueState === "missing-path") {
+        return {
+            recommendation: "resolve-only",
+            nextAction: `Path is missing — confirm the artifact is gone, then run \`artshelf resolve ${idArg} --ledger ${ledgerArg} --status resolved --reason '<why>'\` (ledger-only).`
+        };
+    }
+    if (dueState === "kept") {
+        return {
+            recommendation: "snooze",
+            nextAction: `Retention holds until ${record.retainUntil ?? "the configured date"} — re-inspect after it expires; nothing is due now.`
+        };
+    }
+    if (dueState === "manual-review") {
+        return {
+            recommendation: "keep",
+            nextAction: "Held for manual review — keep it, change its retention, or resolve it explicitly; no cleanup is scheduled."
+        };
+    }
+    if (record.cleanup === "trash") {
+        return {
+            recommendation: "trash-safe",
+            nextAction: `Due and disposable — run \`artshelf cleanup --dry-run --ledger ${ledgerArg}\`, then approve the reviewed plan id.`
+        };
+    }
+    if (record.cleanup === "delete") {
+        return {
+            recommendation: "blocked",
+            nextAction: "Due with cleanup=delete, which Artshelf refuses — switch it to cleanup=trash and plan a cleanup, or resolve it manually."
+        };
+    }
+    return {
+        recommendation: "keep",
+        nextAction: "Due and held for review — keep it, change its retention, resolve it, or switch cleanup to trash and plan a cleanup."
+    };
+}

package/dist/src/registry-prune.js

@@ -0,0 +1,259 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertSafeGeneratedId } from "./ledger.js";
+import { withPathLock } from "./locks.js";
+import { listRegisteredLedgers, normalizeRegistryPath, removeRegisteredLedgers } from "./registry.js";
+import { now, toIso } from "./time.js";
+// Classify the registry into prune findings (read-only). A registration is prunable
+// when its ledger file is missing — the same "missing/stale" signal `ledgers list`
+// reports via existence of the ledger path. Registrations whose resolved path appears
+// more than once are ambiguous: pruning one would silently drop a sibling, so they are
+// blocked for manual resolution instead of pruned. Present ledger files yield nothing.
+export function classifyRegistryPruneFindings(registryPath) {
+    const entries = listRegisteredLedgers(normalizeRegistryPath(registryPath));
+    const pathCounts = new Map();
+    for (const entry of entries) {
+        pathCounts.set(entry.path, (pathCounts.get(entry.path) ?? 0) + 1);
+    }
+    const findings = [];
+    for (const entry of entries) {
+        if ((pathCounts.get(entry.path) ?? 0) > 1) {
+            findings.push(finding(entry, "blocked", "ambiguous duplicate registry path; resolve manually before pruning"));
+            continue;
+        }
+        if (existsSync(entry.path))
+            continue;
+        findings.push(finding(entry, "prune", "registered ledger file is missing"));
+    }
+    return findings;
+}
+// Build the registry-prune plan without persisting anything (dry-run preview). Fully
+// read-only: it classifies the registry and returns the plan a `--dry-run` would
+// create, but never writes a plan file or mutates the registry. A plan with no
+// actionable entries collapses to the not-created shape so callers can render
+// "nothing to prune" the same way cleanup and reconcile do.
+export function previewRegistryPrunePlan(registryPath) {
+    const plan = buildRegistryPrunePlan(normalizeRegistryPath(registryPath));
+    return plan.entries.length === 0 ? noCreatedRegistryPrunePlan(plan) : plan;
+}
+// Create (or reuse) a reviewed registry-prune plan (dry-run). This is the only part of
+// dry-run that writes, and it only writes the plan file — never the registry. When an
+// earlier plan already covers the same prunable entries 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. The plan file lives next to the registry under
+// `registry-prune-plans/` so a later `--execute` can discover it by exact plan id.
+export function createRegistryPrunePlan(registryPath) {
+    const normalized = normalizeRegistryPath(registryPath);
+    const plan = buildRegistryPrunePlan(normalized);
+    if (plan.entries.length === 0)
+        return noCreatedRegistryPrunePlan(plan);
+    const existing = matchingExistingRegistryPrunePlan(normalized, plan);
+    const reviewed = existing ? { ...plan, planId: existing.planId, planPath: existing.planPath } : plan;
+    if (!reviewed.planPath)
+        throw new Error("registry prune plan path was not created");
+    writeRegistryPrunePlanFile(reviewed.planPath, reviewed);
+    return reviewed;
+}
+// Apply a reviewed registry-prune plan (NGX-481 `ledgers prune --execute`). This is the
+// only mutating registry-prune entrypoint and it is deliberately conservative:
+//   * It refuses up front when the plan id is missing, the registry is absent, the plan
+//     file is absent, or the plan file's declared id/registry does not match the scoped
+//     request (no fresh plan, no `--all`; it binds to one exact reviewed plan id against
+//     one exact registry path).
+//   * Inside one registry lock it re-classifies the live registry and only removes a
+//     planned entry that still classifies as prunable; entries whose ledger file
+//     reappeared or whose path became an ambiguous duplicate are skipped, not removed.
+//   * It writes a rollback copy of the registry before mutating and a receipt after,
+//     then verifies the removed registrations are actually gone.
+export function executeRegistryPrunePlan(registryPath, planId) {
+    if (!planId)
+        throw new Error("ledgers prune --execute requires --plan-id");
+    const normalized = normalizeRegistryPath(registryPath);
+    if (!existsSync(normalized))
+        throw new Error(`Registry not found: ${normalized}`);
+    const planPath = registryPrunePlanPath(normalized, planId);
+    if (!existsSync(planPath))
+        throw new Error(`Registry prune plan not found: ${planId}`);
+    const plan = JSON.parse(readFileSync(planPath, "utf8"));
+    assertRegistryPrunePlanExecutable(plan, planId, normalized);
+    const receiptPath = registryPruneReceiptPath(normalized, planId);
+    const rollbackPath = registryPruneRollbackPath(normalized, planId);
+    return withPathLock(normalized, () => {
+        const existingReceipt = readExistingRegistryPruneReceipt(receiptPath, planId, normalized);
+        if (existingReceipt)
+            return existingReceipt;
+        const liveByKey = new Map(classifyRegistryPruneFindings(normalized).map((item) => [pruneKey(item.name, item.path), item]));
+        const removable = [];
+        const skipped = [];
+        for (const entry of plan.entries) {
+            if (liveByKey.get(pruneKey(entry.name, entry.path))?.status === "prune")
+                removable.push(entry);
+            else
+                skipped.push(removal(entry.name, entry.path, entry.scope));
+        }
+        let removedEntries = [];
+        const receiptRollbackPath = removable.length > 0 ? rollbackPath : null;
+        if (removable.length > 0) {
+            copyRegistrySnapshot(normalized, rollbackPath);
+            removedEntries = removeRegisteredLedgers(normalized, removable.map((entry) => ({ name: entry.name, path: entry.path })));
+        }
+        const removed = removedEntries.map((entry) => removal(entry.name, entry.path, entry.scope));
+        const verification = verifyRegistryPrune(normalized, removed);
+        const receipt = {
+            planId,
+            registryPath: normalized,
+            executedAt: toIso(now()),
+            rollbackPath: receiptRollbackPath,
+            removed,
+            skipped,
+            verification,
+            receiptPath
+        };
+        writeRegistryPruneReceiptFile(receiptPath, receipt);
+        return receipt;
+    }, "Artshelf ledger registry");
+}
+function finding(entry, status, reason) {
+    return { name: entry.name, path: entry.path, scope: entry.scope, status, reason };
+}
+function buildRegistryPrunePlan(registryPath) {
+    const generatedAt = now();
+    const findings = classifyRegistryPruneFindings(registryPath);
+    const entries = findings.filter((item) => item.status === "prune").map(planEntry);
+    const skipped = findings.filter((item) => item.status === "blocked").map(planEntry);
+    const planId = makeRegistryPrunePlanId(generatedAt);
+    return {
+        planId,
+        generatedAt: toIso(generatedAt),
+        registryPath,
+        entries,
+        skipped,
+        planPath: registryPrunePlanPath(registryPath, planId)
+    };
+}
+function planEntry(item) {
+    return { name: item.name, path: item.path, scope: item.scope, reason: item.reason };
+}
+function noCreatedRegistryPrunePlan(plan) {
+    return { ...plan, planId: "not-created", planPath: null };
+}
+// Reuse an unexecuted earlier plan whose prunable entries match this one's, so repeated
+// dry-runs converge on a single stable plan id (mirrors cleanup/reconcile plan reuse).
+// Only the structural entry fields are fingerprinted; volatile fields (generatedAt) and
+// the review-only skipped list do not affect reuse.
+function matchingExistingRegistryPrunePlan(registryPath, plan) {
+    const plansDir = join(dirname(registryPath), "registry-prune-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.registryPath !== registryPath)
+                continue;
+            if (registryPrunePlanFingerprint(candidate) !== registryPrunePlanFingerprint(plan))
+                continue;
+            if (existsSync(registryPruneReceiptPath(registryPath, candidate.planId)))
+                continue;
+            return { ...candidate, planPath };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function registryPrunePlanFingerprint(plan) {
+    return JSON.stringify(plan.entries.map((entry) => ({ name: entry.name, path: entry.path, scope: entry.scope })));
+}
+function writeRegistryPrunePlanFile(planPath, plan) {
+    mkdirSync(dirname(planPath), { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function makeRegistryPrunePlanId(date) {
+    return `registry-prune_${toIso(date).replace(/[-:]/g, "").replace("T", "_").replace("Z", "")}_${randomBytes(2).toString("hex")}`;
+}
+function registryPrunePlanPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-plans", `${planId}.json`);
+}
+// Bind a loaded registry-prune plan to the request before any registry mutation,
+// mirroring reconcile's assertReconcilePlanExecutable: the plan must declare the
+// requested id, belong to the executing registry, and carry well-formed entries.
+function assertRegistryPrunePlanExecutable(plan, planId, registryPath) {
+    if (plan.planId !== planId) {
+        throw new Error(`Registry prune plan id mismatch: plan file declares ${plan.planId}, requested ${planId}`);
+    }
+    if (plan.registryPath !== registryPath) {
+        throw new Error(`Registry prune plan registry mismatch: plan was created for ${plan.registryPath}, executing ${registryPath}`);
+    }
+    if (!Array.isArray(plan.entries)) {
+        throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+    }
+    for (const entry of plan.entries) {
+        if (!entry || typeof entry.name !== "string" || typeof entry.path !== "string") {
+            throw new Error(`Registry prune plan entries are malformed: ${planId}`);
+        }
+    }
+}
+// Re-scan the registry after mutation and confirm every removed registration is gone.
+// `ok` stays true only when none of them resurface; `remainingPrunable` counts any
+// prunable registrations left registry-wide so the receipt reflects whether the
+// registry is fully clean or other plans still have work.
+function verifyRegistryPrune(registryPath, removed) {
+    const live = classifyRegistryPruneFindings(registryPath);
+    const stillPresent = removed.filter((entry) => live.some((item) => item.name === entry.name && item.path === entry.path));
+    const remainingPrunable = live.filter((item) => item.status === "prune").length;
+    return {
+        ok: stillPresent.length === 0,
+        remainingPrunable,
+        detail: stillPresent.length === 0
+            ? "removed registrations are gone; registry re-scan is clean of them"
+            : `still registered after prune: ${stillPresent.map((entry) => entry.name).join(", ")}`
+    };
+}
+// Snapshot the registry verbatim before mutation so the receipt's rollbackPath points
+// at a restorable copy. The registry is always UTF-8 JSON, so a read/write round-trip
+// reproduces it byte-for-byte and keeps file I/O consistent with the rest of the code.
+function copyRegistrySnapshot(registryPath, rollbackPath) {
+    mkdirSync(dirname(rollbackPath), { recursive: true });
+    writeFileSync(rollbackPath, readFileSync(registryPath, "utf8"));
+}
+function readExistingRegistryPruneReceipt(receiptPath, planId, registryPath) {
+    if (!existsSync(receiptPath))
+        return null;
+    let receipt;
+    try {
+        receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    }
+    catch {
+        throw new Error(`Registry prune receipt already exists but is unreadable: ${receiptPath}`);
+    }
+    if (receipt.planId !== planId || receipt.registryPath !== registryPath || receipt.receiptPath !== receiptPath) {
+        throw new Error(`Registry prune receipt already exists for a different execution: ${receiptPath}`);
+    }
+    if (!Array.isArray(receipt.removed) || !Array.isArray(receipt.skipped) || !receipt.verification) {
+        throw new Error(`Registry prune receipt already exists but is malformed: ${receiptPath}`);
+    }
+    return receipt;
+}
+function removal(name, path, scope) {
+    return { name, path, scope };
+}
+function pruneKey(name, path) {
+    return JSON.stringify([name, path]);
+}
+function registryPruneReceiptPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-receipts", `${planId}.json`);
+}
+function registryPruneRollbackPath(registryPath, planId) {
+    assertSafeGeneratedId(planId, "registry prune plan id");
+    return join(dirname(registryPath), "registry-prune-rollbacks", `${planId}.json`);
+}
+function writeRegistryPruneReceiptFile(receiptPath, receipt) {
+    mkdirSync(dirname(receiptPath), { recursive: true });
+    writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+}

package/dist/src/registry.js

@@ -51,6 +51,33 @@ export function registerLedger(input) {
         return entry;
     });
 }
+// Remove registrations matching the given (name, path) targets, returning the entries
+// actually removed. The approval-gated registry prune execute composes this under its
+// own registry lock (re-entrant), so classification, rollback copy, mutation, and
+// verification all stay inside one critical section. Matching on both name and path
+// keeps removal precise when two registrations happen to share a path. The registry is
+// only rewritten when something is actually removed, so a no-op target list is inert.
+export function removeRegisteredLedgers(registryPath, targets) {
+    const normalized = normalizeRegistryPath(registryPath);
+    return withRegistryLock(normalized, () => {
+        const registry = readRegistry(normalized);
+        const wanted = new Set(targets.map((target) => removalKey(target.name, resolve(target.path))));
+        const removed = [];
+        const kept = [];
+        for (const entry of registry.ledgers) {
+            if (wanted.has(removalKey(entry.name, entry.path)))
+                removed.push(entry);
+            else
+                kept.push(entry);
+        }
+        if (removed.length > 0)
+            writeRegistry(normalized, { version: 1, ledgers: kept });
+        return removed;
+    });
+}
+function removalKey(name, path) {
+    return JSON.stringify([name, path]);
+}
 function writeRegistry(registryPath, registry) {
     mkdirSync(dirname(registryPath), { recursive: true });
     const tmpPath = `${registryPath}.${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}.tmp`;

package/dist/src/renderers/doctor.js

@@ -5,7 +5,17 @@ function doctorAttention(summary) {
 }
 function doctorNextAction(blockers, summary, registryPath) {
     if (blockers.length > 0) {
-        return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        const fixes = [];
+        if (summary.stale > 0) {
+            fixes.push(`run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`);
+        }
+        if (summary.invalid > 0) {
+            fixes.push(`repair ${summary.invalid} invalid ledger file(s) above`);
+        }
+        if (fixes.length === 0) {
+            return `repair ${blockers.length} registry/ledger issue(s) above, then re-run \`artshelf doctor\``;
+        }
+        return `${fixes.join("; ")}, then re-run \`artshelf doctor\``;
     }
     if (summary.warnings > 0) {
         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`;

package/dist/src/renderers/inspect.js

@@ -0,0 +1,108 @@
+import { shellArg } from "../shared/shell-quote.js";
+import { attentionGlyph } from "./attention.js";
+// Buckets whose next-safe action is something other than "leave it alone" get the
+// attention glyph so a scanned card reads as a decision, not just a status line.
+const ATTENTION_RECOMMENDATIONS = new Set([
+    "trash-safe",
+    "resolve-only",
+    "blocked"
+]);
+export function buildInspectAgentPacket(report, ledgerPath) {
+    return {
+        schemaVersion: 1,
+        command: "get",
+        mode: "inspect",
+        ledgerPath,
+        inspect: report,
+        safety: {
+            readOnly: true,
+            noFileMoves: true,
+            noLedgerMutation: true
+        },
+        nextAction: report.nextAction,
+        verification: `artshelf get ${shellArg(report.id)} --inspect --agent --ledger ${shellArg(ledgerPath)}`
+    };
+}
+export function printInspect(report, ledgerPath) {
+    const glyph = attentionGlyph(ATTENTION_RECOMMENDATIONS.has(report.recommendation));
+    const labels = report.labels.length > 0 ? report.labels.map(sanitizeHumanLine).join(", ") : "none";
+    const lines = [];
+    lines.push(`${glyph} ${sanitizeHumanLine(report.id)} [${sanitizeHumanLine(report.kind)}] — ${sanitizeHumanLine(report.recommendation)}`);
+    lines.push(`path: ${sanitizeHumanLine(report.path)}`);
+    // Trashed records point `path` at the now-empty original; existence and size
+    // describe the trash target, so name it explicitly when the two differ.
+    if (report.subjectPath !== report.path)
+        lines.push(`trash target: ${sanitizeHumanLine(report.subjectPath)}`);
+    lines.push(`status: ${sanitizeHumanLine(report.status)} · cleanup: ${sanitizeHumanLine(report.cleanup)} · owner: ${sanitizeHumanLine(report.owner)} · labels: ${labels}`);
+    lines.push(`existence: ${sanitizeHumanLine(formatExistence(report))} · age: ${sanitizeHumanLine(report.age)} · retention: ${sanitizeHumanLine(formatRetention(report.retention))} · due: ${sanitizeHumanLine(report.dueState ?? "n/a")}`);
+    lines.push(`reason: ${sanitizeHumanLine(report.reason)}`);
+    lines.push(`next: ${sanitizeHumanLine(report.nextAction)}`);
+    lines.push(`ledger: ${sanitizeHumanLine(ledgerPath)}`);
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+function formatExistence(report) {
+    if (report.existence === "missing")
+        return "missing";
+    if (report.nodeKind === "file" || report.nodeKind === "directory") {
+        const size = report.byteSize === null ? "size unavailable" : formatBytes(report.byteSize);
+        if (report.nodeKind === "directory" && report.byteSizeTruncated) {
+            return `present (directory, at least ${size}; scan capped)`;
+        }
+        return `present (${report.nodeKind}, ${size})`;
+    }
+    return "present (other)";
+}
+function formatRetention(retention) {
+    if (retention.mode === "ttl")
+        return `ttl ${retention.ttl}`;
+    if (retention.mode === "retain-until")
+        return `retain-until ${retention.retainUntil}`;
+    return "manual-review";
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function sanitizeHumanLine(value) {
+    let out = "";
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (code === undefined)
+            continue;
+        if (char === "\\") {
+            out += "\\\\";
+        }
+        else if (char === "\n") {
+            out += "\\n";
+        }
+        else if (char === "\r") {
+            out += "\\r";
+        }
+        else if (char === "\t") {
+            out += "\\t";
+        }
+        else if (code < 32 || (code >= 0x7f && code <= 0x9f) || isUnicodeFormatControl(code)) {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            out += char;
+        }
+    }
+    return out;
+}
+function isUnicodeFormatControl(code) {
+    if (code === 0x00ad || code === 0x061c)
+        return true;
+    if (code >= 0x200b && code <= 0x200f)
+        return true;
+    if (code >= 0x202a && code <= 0x202e)
+        return true;
+    if (code >= 0x2060 && code <= 0x206f)
+        return true;
+    if (code >= 0xfe00 && code <= 0xfe0f)
+        return true;
+    return code >= 0xfff9 && code <= 0xfffb;
+}

package/dist/src/renderers/review.js

@@ -11,6 +11,14 @@ export function reviewNextAction(summary, scope, ledgerPath, registryPath) {
     const broken = summary.invalid + summary.stale;
     const review = statusCommand(scope, "review", ledgerPath);
     if (broken > 0) {
+        if (scope === "all" && summary.stale > 0 && registryPath) {
+            const fixes = [
+                `run \`artshelf ledgers prune --dry-run --registry ${registryPath}\` to review removing ${summary.stale} missing/stale registration(s)`
+            ];
+            if (summary.invalid > 0)
+                fixes.push(`repair ${summary.invalid} invalid ledger(s) above (re-register or fix the file)`);
+            return `${fixes.join("; ")}, then re-run \`${review}\``;
+        }
         const repair = scope === "all" ? "re-register or fix the file" : "fix the file";
         return `repair ${broken} broken ledger(s) above (${repair}), then re-run \`${review}\``;
     }
@@ -45,7 +53,7 @@ export function printReview(results) {
         process.stdout.write(`ledger: ${result.ledger.path}\n`);
     }
 }
-function buildReviewDecisions(results, scope) {
+function buildReviewDecisions(results, scope, registryPath) {
     const readyForApproval = [];
     const needsReviewFirst = [];
     const blocked = [];
@@ -54,6 +62,20 @@ function buildReviewDecisions(results, scope) {
         const { ledger, validate, due } = result;
         if (!validate.ok) {
             const status = result.ledgerExists ? "invalid" : "missing";
+            // A missing registered ledger is repaired through the approval-gated registry-prune
+            // flow rather than hand-editing the registry; an invalid-but-present file still needs
+            // a manual re-register/fix.
+            if (scope === "all" && status === "missing" && registryPath) {
+                blocked.push({
+                    label: `Prune ${ledger.name} registration (missing)`,
+                    itemIds: [],
+                    actionType: "fix-registry",
+                    approvalTarget: null,
+                    reason: validate.errors[0] ?? "the registered ledger file is missing",
+                    nextStep: `run \`artshelf ledgers prune --dry-run --registry ${registryPath} --json\` to review removing it, then approve \`approve artshelf ledgers prune registry ${registryPath} plan <plan-id>\``
+                });
+                continue;
+            }
             const repair = scope === "all" ? `re-register or fix ${ledger.path}` : `fix ${ledger.path}`;
             blocked.push({
                 label: `Repair ${ledger.name} ledger (${status})`,
@@ -177,7 +199,7 @@ function reviewCounts(summary) {
     };
 }
 export function buildReviewAgentPacketAll(results, summary, registry) {
-    const groups = buildReviewDecisions(results, "all");
+    const groups = buildReviewDecisions(results, "all", registry.path);
     return {
         schemaVersion: 1,
         command: "review",