artshelf 0.14.0 → 0.16.0

package/dist/src/inspect.js

@@ -0,0 +1,207 @@
+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.disposeAction === "keep" && record.disposePlanId && record.disposeReceiptPath && record.disposedAt)
+        return "kept";
+    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);
+    const disposeDryRun = (action, extra = "") => `artshelf dispose --id ${idArg} --action ${action} --dry-run${extra} --ledger ${ledgerArg}`;
+    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 \`${disposeDryRun("resolve-only", " --reason '<why>'")}\`, then approve the reviewed plan id.`
+        };
+    }
+    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 — run \`${disposeDryRun("keep", " --reason '<why>'")}\` to keep it quiet through a reviewed decision, or choose resolve-only/snooze deliberately.`
+        };
+    }
+    if (record.cleanup === "trash") {
+        return {
+            recommendation: "trash-safe",
+            nextAction: `Due and disposable after review — run \`${disposeDryRun("trash-resolve", " --reason '<why>'")}\`, 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 — run \`${disposeDryRun("keep", " --reason '<why>'")}\`, or choose resolve-only/snooze deliberately.`
+    };
+}

package/dist/src/ledger.js

@@ -17,6 +17,15 @@ const KINDS = new Set([
 const CLEANUP_ACTIONS = new Set(["trash", "review", "delete"]);
 const STATUSES = new Set(["active", "review-required", "trashed", "cleanup-refused", "resolved"]);
 const RESOLVE_STATUSES = new Set(["resolved"]);
+function trashProvenance(record) {
+    if (record.cleanedAt && record.receiptPath && record.cleanupPlanId) {
+        return { cleanedAt: record.cleanedAt, receiptPath: record.receiptPath, cleanupPlanId: record.cleanupPlanId };
+    }
+    if (record.disposedAt && record.disposeReceiptPath && record.disposePlanId) {
+        return { cleanedAt: record.disposedAt, receiptPath: record.disposeReceiptPath, cleanupPlanId: record.disposePlanId };
+    }
+    return null;
+}
 export function defaultLedgerPath(cwd = process.cwd()) {
     const repoRoot = findGitRoot(cwd);
     if (repoRoot)
@@ -85,16 +94,17 @@ export function listTrashedRecords(ledgerPath) {
     const records = readLedger(ledgerPath).filter((record) => record.status === "trashed");
     const current = now();
     return records.map((record) => {
-        if (!record.id || !record.targetPath || !record.cleanedAt || !record.receiptPath || !record.cleanupPlanId) {
-            throw new Error(`trashed record ${record.id ?? "<missing id>"} missing cleanup metadata`);
+        const provenance = trashProvenance(record);
+        if (!record.id || !record.targetPath || !provenance) {
+            throw new Error(`trashed record ${record.id ?? "<missing id>"} missing trash provenance`);
         }
         return {
             id: record.id,
             targetPath: record.targetPath,
-            cleanedAt: record.cleanedAt,
-            receiptPath: record.receiptPath,
-            cleanupPlanId: record.cleanupPlanId,
-            age: ageOf(current, record.cleanedAt)
+            cleanedAt: provenance.cleanedAt,
+            receiptPath: provenance.receiptPath,
+            cleanupPlanId: provenance.cleanupPlanId,
+            age: ageOf(current, provenance.cleanedAt)
         };
     });
 }
@@ -214,12 +224,8 @@ export function validateLedger(ledgerPath) {
             warnings.push(`${label}: recorded path is missing`);
         }
         if (record.status === "trashed") {
-            if (!record.cleanupPlanId)
-                errors.push(`${label}: trashed record missing cleanupPlanId`);
-            if (!record.receiptPath)
-                errors.push(`${label}: trashed record missing receiptPath`);
-            if (!record.cleanedAt)
-                errors.push(`${label}: trashed record missing cleanedAt`);
+            if (!trashProvenance(record))
+                errors.push(`${label}: trashed record missing trash provenance`);
             if (!record.targetPath) {
                 errors.push(`${label}: trashed record missing targetPath`);
             }
@@ -341,15 +347,17 @@ export function executeTrashPurgePlan(ledgerPath, purgePlanId) {
                 results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: `record is ${record.status}` });
                 continue;
             }
+            const provenance = trashProvenance(record);
             if (record.targetPath !== entry.targetPath ||
-                record.cleanedAt !== entry.cleanedAt ||
-                record.receiptPath !== entry.receiptPath ||
-                record.cleanupPlanId !== entry.cleanupPlanId) {
+                !provenance ||
+                provenance.cleanedAt !== entry.cleanedAt ||
+                provenance.receiptPath !== entry.receiptPath ||
+                provenance.cleanupPlanId !== entry.cleanupPlanId) {
                 results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "plan entry no longer matches ledger record" });
                 continue;
             }
             const targetPath = resolve(entry.targetPath);
-            const expectedPlanTrashRoot = resolve(trashRoot, record.cleanupPlanId);
+            const expectedPlanTrashRoot = resolve(trashRoot, entry.cleanupPlanId);
             if (!isPathWithin(trashRoot, targetPath)) {
                 results.push({ id: entry.id, status: "skipped", targetPath: entry.targetPath, reason: "target is outside Artshelf trash" });
                 continue;
@@ -502,15 +510,16 @@ function buildTrashPurgePlan(ledgerPath, olderThan) {
     for (const record of records) {
         if (record.status !== "trashed")
             continue;
-        if (!record.id || !record.targetPath || !record.cleanedAt || !record.receiptPath || !record.cleanupPlanId) {
+        const provenance = trashProvenance(record);
+        if (!record.id || !record.targetPath || !provenance) {
             skipped.push({
                 id: record.id ?? "",
                 targetPath: record.targetPath ?? "",
-                reason: "trashed record missing cleanup metadata"
+                reason: "trashed record missing trash provenance"
             });
             continue;
         }
-        const cleanedAt = new Date(record.cleanedAt);
+        const cleanedAt = new Date(provenance.cleanedAt);
         if (Number.isNaN(cleanedAt.getTime())) {
             skipped.push({
                 id: record.id,
@@ -526,9 +535,9 @@ function buildTrashPurgePlan(ledgerPath, olderThan) {
         entries.push({
             id: record.id,
             targetPath: record.targetPath,
-            cleanedAt: record.cleanedAt,
-            receiptPath: record.receiptPath,
-            cleanupPlanId: record.cleanupPlanId
+            cleanedAt: provenance.cleanedAt,
+            receiptPath: provenance.receiptPath,
+            cleanupPlanId: provenance.cleanupPlanId
         });
     }
     const purgePlanId = makePurgePlanId(generatedAt);
@@ -896,6 +905,8 @@ function buildRetention(input, createdAt) {
 function classifyDue(record, at) {
     if (!existsSync(record.path))
         return "missing-path";
+    if (record.disposeAction === "keep" && record.disposePlanId && record.disposeReceiptPath && record.disposedAt)
+        return "kept";
     if (record.retention.mode === "manual-review")
         return "manual-review";
     if (!record.retainUntil)

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/shared/flags.js

@@ -1,6 +1,9 @@
 export const BOOLEAN_FLAGS = new Set(["all", "json", "agent", "manual-review", "dry-run", "execute", "help", "version", "plain"]);
+const COMMAND_BOOLEAN_FLAGS = new Map([["get", new Set(["inspect"])]]);
 export const VALUE_FLAGS = new Set([
     "cleanup",
+    "action",
+    "id",
     "kind",
     "label",
     "ledger",
@@ -16,6 +19,9 @@ export const VALUE_FLAGS = new Set([
     "status",
     "ttl"
 ]);
+export function isBooleanFlag(name, command) {
+    return BOOLEAN_FLAGS.has(name) || (command !== undefined && (COMMAND_BOOLEAN_FLAGS.get(command)?.has(name) ?? false));
+}
 export function requiredStringFlag(parsed, name) {
     const value = stringFlag(parsed, name);
     if (!value)

package/dist/src/shared/help-text.js

@@ -53,6 +53,7 @@ const COMMAND_GROUPS = [
         group: "Clean",
         commands: [
             { name: "cleanup", summary: "Plan and execute approved cleanups" },
+            { name: "dispose", summary: "Plan and execute reviewed artifact decisions" },
             { name: "reconcile", summary: "Reconcile drifted ledger paths via approval-gated plans" },
             { name: "trash", summary: "Inspect and purge Artshelf trash" },
             { name: "resolve", summary: "Mark a record manually resolved" }
@@ -109,6 +110,29 @@ Dry-run writes and registers a plan only when executable cleanup entries exist;
 Matching dry-runs reuse the existing plan id and refresh its Artshelf-owned plan artifact.
 Execute writes and registers an Artshelf-owned receipt artifact.
 Global --all mode is dry-run only.
+`;
+    }
+    if (command === "dispose") {
+        return `Usage:
+  artshelf dispose --id <id> --action trash-resolve --dry-run [--reason <text>] [--ledger <path>] [--json|--agent]
+  artshelf dispose --id <id> --action resolve-only --dry-run --reason <text> [--ledger <path>] [--json|--agent]
+  artshelf dispose --id <id> --action snooze --dry-run (--ttl <ttl>|--retain-until <date>) [--reason <text>] [--ledger <path>] [--json|--agent]
+  artshelf dispose --id <id> --action keep --dry-run [--reason <text>] [--ledger <path>] [--json|--agent]
+  artshelf dispose --execute --plan-id <id> [--ledger <path>] [--json]
+
+Dispose is for records after human review, usually from \`get --inspect\`.
+Dry-run classifies exactly one record/action, writes a reviewed dispose plan when
+actionable, and prints the exact approval target:
+  approve artshelf dispose ledger <ledger-path> plan <plan-id>
+
+Actions:
+  trash-resolve   Move the recorded path into plan-scoped Artshelf trash and resolve the row
+  resolve-only    Resolve the ledger row only; requires --reason
+  snooze          Extend retention; requires --ttl or --retain-until
+  keep            Stamp that the record was reviewed and kept
+
+Execute applies exactly one reviewed plan id against one ledger. There is no
+dispose --all, no fresh-plan-then-execute, no daemon, and no physical delete.
 `;
     }
     if (command === "reconcile") {
@@ -170,8 +194,24 @@ Find is read-only. Use it before put when an integration needs idempotent artifa
         return `Usage:
   artshelf get <id> [--ledger <path>] [--json]
   artshelf get <id> --all [--registry <path>] [--json]
+  artshelf get <id> --inspect [--ledger <path>] [--json|--agent]
+  artshelf get <id> --inspect --all [--registry <path>] [--json|--agent]
 
 Get is read-only and returns one ledger record by Artshelf id.
+
+--inspect adds a read-only review decision card for one record: existence,
+size, age, retention/due state, a recommendation bucket (keep, snooze,
+trash-safe, resolve-only, blocked), and the exact next-safe action. It never
+moves files or touches the ledger. It does not read or preview arbitrary
+file contents; agents can inspect contents separately when appropriate.
+With --all, the registry is only used to find the id; the card reports the
+concrete ledger that owns the record.
+
+Render modes:
+  (default)  Human record line, or a decision card with --inspect.
+  --json     Full read-only report (record, or { inspect } with --inspect).
+  --agent    Compact single-line JSON decision packet (requires --inspect);
+             takes precedence over --json.
 `;
     }
     if (command === "resolve") {

package/dist/src/shared/shell-quote.js

@@ -0,0 +1,6 @@
+const SHELL_SAFE = /^[A-Za-z0-9_./:@%+=,-]+$/;
+export function shellArg(value) {
+    if (value.length > 0 && SHELL_SAFE.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/docs/agent-clean.html

@@ -77,6 +77,29 @@ artshelf cleanup --execute --plan-id &lt;id&gt;</code></pre>
             </div>
           </section>
 
+          <section>
+            <h2>Dispose one reviewed record</h2>
+            <p>
+              <code>dispose</code> is the per-record reviewed path that follows
+              <code>get --inspect</code>: one record id, one action, one reviewed plan id.
+              It never runs in batch and never deletes physically.
+            </p>
+            <pre><code><span class="c"># classify one inspected record into a reviewed plan</span>
+artshelf dispose --id &lt;id&gt; --action trash-resolve|resolve-only|snooze|keep --dry-run [--reason &lt;text&gt;] [--ttl &lt;ttl&gt;|--retain-until &lt;date&gt;] --ledger &lt;ledger-path&gt; --json
+
+<span class="c"># approve: approve artshelf dispose ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;</span>
+<span class="c"># only after a human approves this exact plan id</span>
+artshelf dispose --execute --plan-id &lt;plan-id&gt; --ledger &lt;ledger-path&gt;</code></pre>
+            <p>
+              Actions: <code>trash-resolve</code> moves the subject into plan-scoped Artshelf
+              trash and resolves the row; <code>resolve-only</code> resolves the ledger row only
+              (requires <code>--reason</code>); <code>snooze</code> extends retention (requires
+              <code>--ttl</code> or <code>--retain-until</code>); <code>keep</code> stamps the
+              record reviewed-and-kept. Execute re-snapshots the subject and refuses drift or a
+              target conflict; reruns are idempotent and a receipt is left for audit.
+            </p>
+          </section>
+
           <section>
             <h2>Resolve confirmed records</h2>
             <p>Resolve only updates the ledger; it does not move or delete files.</p>
@@ -88,13 +111,15 @@ artshelf resolve &lt;id&gt; --status resolved --reason &lt;text&gt;</code></pre>
 
           <section>
             <h2>Verify quiet</h2>
-            <p>After cleanup execute or resolve, verify with <code>artshelf review --all --json</code>.</p>
+            <p>After cleanup execute, dispose execute, or resolve, verify with <code>artshelf review --all --json</code>.</p>
             <p>
-              Execution writes a started receipt before the first move, completes it after
+              Cleanup execution writes a started receipt before the first move, completes it after
               ledger updates, and updates touched ledger records to <code>trashed</code>,
-              <code>review-required</code>, or <code>cleanup-refused</code>. Rerunning the same
-              plan id resumes or idempotently replays durable receipt/trash evidence.
-              Generated plans and receipts are recorded as <code>owner=artshelf</code> artifacts.
+              <code>review-required</code>, or <code>cleanup-refused</code>. Dispose execution writes
+              its own receipt, stamps dispose audit fields, and either resolves, snoozes,
+              or keeps the reviewed row. Rerunning the same plan id resumes or idempotently
+              replays durable receipt/trash evidence. Generated plans and receipts are
+              recorded as <code>owner=artshelf</code> artifacts.
             </p>
           </section>
         </article>

package/docs/agent-monitor.html

@@ -93,7 +93,7 @@ artshelf find --all --owner &lt;agent-or-runtime&gt; --json</code></pre>
               <li><strong>Read-only.</strong> Validate, status, due, review, doctor, and trash list are fine.</li>
               <li><strong>Quiet by default.</strong> Send nothing when the review is clean unless a summary was requested.</li>
               <li><strong>No network mode.</strong> Set <code>ARTSHELF_NO_UPDATE_CHECK=1</code> when jobs must avoid npm update checks and cache writes.</li>
-              <li><strong>Never schedule execution.</strong> Scheduled jobs must not run cleanup execute or trash purge execute.</li>
+              <li><strong>Never schedule execution.</strong> Scheduled jobs must not run cleanup execute, dispose execute, or trash purge execute.</li>
             </ul>
             <pre><code><span class="c"># ledger health, current ledger or all registered ledgers</span>
 artshelf validate --json
@@ -159,6 +159,7 @@ artshelf trash purge --older-than 7d --dry-run --ledger &lt;ledger-path&gt; --js
             </div>
             <pre><code><span class="c"># mutating commands: approval only, never from a schedule</span>
 artshelf cleanup --execute --plan-id &lt;id&gt;
+artshelf dispose --execute --plan-id &lt;id&gt;
 artshelf ledgers prune --execute --plan-id &lt;id&gt;
 artshelf trash purge --execute --plan-id &lt;id&gt;</code></pre>
           </section>

package/docs/agent-review.html

@@ -65,6 +65,42 @@
             </p>
           </section>
 
+          <section>
+            <h2>Inspect a single record</h2>
+            <p>
+              When a review flags one record — most often a stale
+              <code>cleanup=review</code> backup that <code>ledgers prune</code> and
+              <code>review --all</code> surface — drill into it with
+              <code>get &lt;id&gt; --inspect</code> instead of running <code>get</code>,
+              <code>ls</code>, and <code>du</code> by hand. It is read-only: it never
+              moves files or mutates the ledger.
+            </p>
+            <pre><code><span class="c"># review one record as a decision card</span>
+artshelf get &lt;id&gt; --inspect --ledger &lt;ledger-path&gt;
+
+<span class="c"># compact, deterministic packet for an acting agent</span>
+artshelf get &lt;id&gt; --inspect --agent --ledger &lt;ledger-path&gt;</code></pre>
+            <p>
+              Each card reports existence, size, age, retention/due state, cleanup
+              mode, and reason, then ends with a recommendation bucket and the exact
+              next-safe action. It does not read or preview arbitrary file contents:
+              <code>keep</code>, <code>snooze</code>, <code>trash-safe</code>,
+              <code>resolve-only</code>, or <code>blocked</code>. These map onto the
+              daily-review classifications — a missing-path record reads as
+              <code>resolve-only</code> and points at a reviewed
+              <code>dispose</code> plan, while a due disposable record reads as
+              <code>trash-safe</code> and points at a reviewed <code>dispose</code>
+              plan.
+            </p>
+            <pre><code>✓ &lt;id&gt; [backup] — keep
+path: &lt;backup-path&gt;
+status: active · cleanup: review · owner: agent · labels: registry-prune
+existence: present (directory, 49 B) · age: 14d · retention: manual-review · due: manual-review
+reason: rollback backup before registry prune
+next: Held for manual review — run `artshelf dispose --id &lt;id&gt; --action keep --dry-run --reason '&lt;why&gt;' --ledger &lt;ledger-path&gt;` to keep it quiet through a reviewed decision, or choose resolve-only/snooze deliberately.
+ledger: &lt;ledger-path&gt;</code></pre>
+          </section>
+
           <section>
             <h2>Review plan report schema</h2>
             <p>For richer host cards, attachments, or audit packets, construct an <code>ArtshelfReviewReport</code> JSON packet first, then render a compact decision card.</p>
@@ -111,6 +147,7 @@ Dry-run only. No execute, resolve, or delete ran.</code></pre>
               asks for it. Always include the exact approval target in the message body as a fallback.
             </p>
             <pre><code>approve artshelf cleanup ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;
+approve artshelf dispose ledger &lt;ledger-path&gt; plan &lt;dispose-plan-id&gt;
 approve artshelf trash purge ledger &lt;ledger-path&gt; plan &lt;purge-plan-id&gt;
 approve artshelf resolve missing ledger &lt;ledger-path&gt; ids &lt;id...&gt;
 approve artshelf reconcile ledger &lt;ledger-path&gt; plan &lt;plan-id&gt;