harnery 0.41.0 → 0.42.0

package/dist/core/artifacts/index.js

@@ -5,15 +5,19 @@
  * become project records: screenshots, exports, audit dumps, rollback inputs,
  * and similar material. Each direct child of `.harnery/artifacts/` is one
  * managed unit with a small manifest. Cleanup fails closed: only a valid,
- * expired, inactive, untracked managed unit is deletable.
+ * unheld, inactive, untracked managed unit is deletable, and only when its
+ * retention expired or a size rule applies after its idle grace. Explicit
+ * removal lets a creating owner delete its reviewed, unheld workspace sooner.
  */
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statfsSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
-import { artifactAutoCleanEnabled, artifactAutoCleanIntervalHours, artifactDefaultRetentionDays, artifactMaxBytes, artifactMaxUnitBytes, coordFreshnessSeconds, resolveBinName, } from "../config.js";
+import { artifactAutoCleanEnabled, artifactAutoCleanIntervalHours, artifactDefaultRetentionDays, artifactHoldDays, artifactIdleGraceHours, artifactMaxBytes, artifactMaxHeldBytes, artifactMaxUnitBytes, artifactMinFreeBytes, coordFreshnessSeconds, resolveBinName, } from "../config.js";
+import { readCoordinationViewV3, requireAuthoritySafeCoordinationViewV3, } from "../events/v3/coordination-view.js";
+import { liveInstanceIdV3 } from "../events/v3/live-route-observer.js";
 import { stateFileMode } from "../storage/modes.js";
 import { artifactRootEntries, readArtifactActivity, validArtifactActivity, } from "./activity.js";
 import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.js";
@@ -29,6 +33,12 @@ export function artifactCapabilities() {
         explicit_v1_migration: true,
         minute_retention: true,
         discard_after_review: true,
+        owner_scoped_remove: true,
+        allow_big_after_create: true,
+        hold_expiry: true,
+        persistent_holds: true,
+        held_budget: true,
+        disk_free_report: true,
     };
 }
 export function artifactsRoot(repoRoot) {
@@ -57,7 +67,8 @@ function createArtifactUnlocked(repoRoot, input) {
     if (!isSafeId(artifactId)) {
         throw new Error("artifact id must use ASCII letters, digits, hyphens, or underscores");
     }
-    const holds = (input.holds ?? []).map((hold) => makeHold(hold, input.actor, now));
+    const holdDays = artifactHoldDays(repoRoot);
+    const holds = (input.holds ?? []).map((hold) => makeHold(hold, input.actor, now, holdDays));
     if (new Set(holds.map((hold) => hold.id)).size !== holds.length) {
         throw new Error("duplicate hold id");
     }
@@ -102,7 +113,7 @@ export function inventoryArtifacts(repoRoot, opts = {}) {
     for (const name of names) {
         rows.push(classifyArtifactPath(repoRoot, join(root, name), now, freshnessSeconds));
     }
-    return applyArtifactBudgets(repoRoot, rows);
+    return applyArtifactBudgets(repoRoot, rows, now);
 }
 export function showArtifact(repoRoot, ref, opts = {}) {
     const path = resolveArtifactRef(repoRoot, ref);
@@ -141,6 +152,24 @@ function renewArtifactUnlocked(repoRoot, ref, days, reason, input) {
     atomicWriteManifest(path, manifest, now);
     return manifest;
 }
+/**
+ * Record the `--big` acknowledgement on an existing workspace, for work that
+ * turns out larger than expected. Unlike a hold, it leaves expiry in force and
+ * exempts the unit only from the per-bundle ceiling. Idempotent.
+ */
+export function allowBigArtifact(repoRoot, ref, input = {}) {
+    return withArtifactLock(repoRoot, () => {
+        const path = resolveArtifactRef(repoRoot, ref);
+        const parsed = readManifest(path);
+        if (!parsed.ok)
+            throw new Error(parsed.reason);
+        if (parsed.manifest.oversize_acknowledged)
+            return parsed.manifest;
+        const manifest = { ...parsed.manifest, oversize_acknowledged: true };
+        atomicWriteManifest(path, manifest, input.now);
+        return manifest;
+    });
+}
 export function releaseArtifact(repoRoot, ref, input = {}) {
     return withArtifactLock(repoRoot, () => releaseArtifactUnlocked(repoRoot, ref, input));
 }
@@ -186,6 +215,95 @@ export function discardArtifact(repoRoot, ref, reason, input = {}) {
         return updated;
     });
 }
+/** Preview or immediately remove one reviewed workspace belonging to this actor. */
+export function removeArtifact(repoRoot, ref, reason, input = {}) {
+    const why = reason.trim();
+    if (!why)
+        throw new Error("remove requires a reason confirming the files are no longer needed");
+    if (!validActor(input.actor))
+        throw new Error("remove requires a current artifact owner identity");
+    const actor = input.actor;
+    const now = input.now ?? new Date();
+    assertValidDate(now, "now");
+    const store = artifactsRoot(repoRoot);
+    const checkStore = () => {
+        for (const path of [resolve(repoRoot), dirname(store), store]) {
+            const stat = lstatSync(path);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error("artifact store must use real directories, not symlinks");
+        }
+    };
+    checkStore();
+    return withArtifactLock(repoRoot, () => {
+        checkStore();
+        const path = resolveArtifactRef(repoRoot, ref);
+        const inspect = () => {
+            const target = realpathSync(path);
+            const cwd = realpathSync(process.cwd());
+            if (cwd === target || cwd.startsWith(`${target}${sep}`))
+                throw new Error("cannot remove the working directory or its ancestor");
+            if (lstatSync(path).dev !== lstatSync(store).dev)
+                throw new Error("artifact removal cannot cross a mount boundary");
+            const entry = classifyArtifactPath(repoRoot, path, now, coordFreshnessSeconds(repoRoot));
+            if (!["managed-current", "managed-expired", "managed-active"].includes(entry.classification))
+                throw new Error(`cannot remove artifact: ${entry.reason}`);
+            if (entry.owner_instance_id !== actor.instance_id)
+                throw new Error("only the creating artifact owner may remove this workspace");
+            const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(repoRoot));
+            for (const peer of Object.values(view.instances)) {
+                if (!peer.authority_eligible || peer.instance_id === liveInstanceIdV3(actor.instance_id))
+                    continue;
+                for (const claim of peer.files_touched) {
+                    const claimed = resolve(repoRoot, claim);
+                    if (path === claimed ||
+                        path.startsWith(`${claimed}${sep}`) ||
+                        claimed.startsWith(`${path}${sep}`))
+                        throw new Error(`artifact overlaps another agent's claim: ${claim}`);
+                }
+            }
+            return entry;
+        };
+        const entry = inspect();
+        const before = artifactRemovalSnapshot(path);
+        if (!input.yes)
+            return { entry, reason: why, deleted: false };
+        // Metadata mutations share this lock. Recheck payload, claims, and protections
+        // immediately before removal because ordinary file writers do not take it.
+        checkStore();
+        const current = inspect();
+        if (!isDeepStrictEqual(entry, current) ||
+            !isDeepStrictEqual(before, artifactRemovalSnapshot(path)))
+            throw new Error("artifact changed during removal inspection; preview it again");
+        rmSync(path, { recursive: true, force: false });
+        const removed = { ...current, action: "deleted", reason: why };
+        recordArtifactDeletion(repoRoot, removed, now, actor);
+        return { entry: removed, reason: why, deleted: true };
+    });
+}
+/** Refuse links, mounts, special files, and embedded stores; fingerprint every entry. */
+function artifactRemovalSnapshot(path) {
+    const device = lstatSync(path).dev;
+    const entries = new Map();
+    const walk = (target) => {
+        const stat = lstatSync(target);
+        if (stat.isSymbolicLink() || stat.dev !== device || (!stat.isFile() && !stat.isDirectory()))
+            throw new Error(`unsafe artifact removal path: ${target}`);
+        if (target !== path && [".git", ".harnery"].includes(basename(target)))
+            throw new Error(`embedded repository or coordination state cannot be removed: ${target}`);
+        if (target !== join(path, ARTIFACT_MANIFEST) && basename(target) === ARTIFACT_MANIFEST)
+            throw new Error(`nested artifact must be managed separately: ${target}`);
+        entries.set(target, [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":"));
+        if (stat.isDirectory()) {
+            const names = readdirSync(target).sort();
+            if (names.includes("HEAD") && names.includes("objects") && names.includes("config"))
+                throw new Error(`embedded Git metadata cannot be removed: ${target}`);
+            for (const name of names)
+                walk(join(target, name));
+        }
+    };
+    walk(path);
+    return entries;
+}
 /** Advice only: a successful check does not establish that its evidence is disposable. */
 export function artifactReviewGuidance(repoRoot, ref) {
     const target = isAbsolute(ref) ? basename(ref) : ref;
@@ -209,7 +327,7 @@ function releaseArtifactUnlocked(repoRoot, ref, input) {
     return manifest;
 }
 export function holdArtifact(repoRoot, ref, input) {
-    const hold = makeHold(input, input.actor, input.now ?? new Date());
+    const hold = makeHold(input, input.actor, input.now ?? new Date(), artifactHoldDays(repoRoot));
     return withArtifactLock(repoRoot, () => {
         const path = resolveArtifactRef(repoRoot, ref);
         const parsed = readManifest(path);
@@ -221,7 +339,18 @@ export function holdArtifact(repoRoot, ref, input) {
                 previous.reason !== hold.reason) {
                 throw new Error("hold id already exists with a different owner or reason");
             }
-            return parsed.manifest;
+            // Repeating a hold renews it: the original owner and set_at stay, and the
+            // window restarts from now. A persistent hold stays persistent.
+            const { expires_at: _expires, persistent: _persistent, ...kept } = previous;
+            const renewed = previous.persistent || hold.persistent
+                ? { ...kept, persistent: true }
+                : { ...kept, expires_at: hold.expires_at };
+            const manifest = {
+                ...parsed.manifest,
+                holds: parsed.manifest.holds.map((item) => (item.id === hold.id ? renewed : item)),
+            };
+            atomicWriteManifest(path, manifest, input.now);
+            return manifest;
         }
         const manifest = { ...parsed.manifest, holds: [...parsed.manifest.holds, hold] };
         atomicWriteManifest(path, manifest, input.now);
@@ -388,7 +517,7 @@ function cleanArtifactsUnlocked(repoRoot, opts) {
         // per-unit size are local decisions; recheck all their guards on the target.
         const current = entry.classification === "managed-over-budget"
             ? inventoryArtifacts(repoRoot, { now, freshnessSeconds }).find((row) => row.path === entry.path)
-            : applyArtifactUnitBudget(repoRoot, classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds));
+            : applyArtifactUnitBudget(repoRoot, classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds), now);
         if (!current) {
             return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
         }
@@ -410,6 +539,7 @@ function cleanArtifactsUnlocked(repoRoot, opts) {
                 };
             }
             rmSync(current.path, { recursive: true, force: false });
+            recordArtifactDeletion(repoRoot, current, now);
             return { ...current, action: "deleted" };
         }
         catch (error) {
@@ -422,6 +552,220 @@ function cleanArtifactsUnlocked(repoRoot, opts) {
         }
     });
 }
+/** Sibling of the artifacts root, like the stamp, so it never enters the inventory. */
+const DELETION_LOG = ".harnery/artifact-deletions.jsonl";
+const DELETION_LOG_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Append one deletion to the log, keeping 30 days. Callers hold the artifact
+ * lock. Best-effort: the directory is already gone, so a failed write must not
+ * turn a completed deletion into a reported failure.
+ */
+function recordArtifactDeletion(repoRoot, row, now, removedBy) {
+    const record = {
+        deleted_at: now.toISOString(),
+        name: row.name,
+        relative_path: row.relative_path,
+        artifact_id: row.artifact_id,
+        slug: row.slug,
+        owner_instance_id: row.owner_instance_id,
+        classification: row.classification,
+        reason: row.reason,
+        bytes: row.bytes,
+        apparent_bytes: row.apparent_bytes,
+        expires_at: row.expires_at,
+        idle_since: row.idle_since,
+        ...(removedBy ? { removed_by: removedBy } : {}),
+    };
+    try {
+        const path = join(resolve(repoRoot), DELETION_LOG);
+        const kept = readArtifactDeletions(repoRoot, {
+            since: new Date(now.getTime() - DELETION_LOG_RETENTION_MS),
+        });
+        const temp = `${path}.${randomUUID()}.tmp`;
+        writeFileSync(temp, [...kept, record].map((item) => `${JSON.stringify(item)}\n`).join(""), {
+            mode: stateFileMode(),
+        });
+        renameSync(temp, path);
+    }
+    catch {
+        // See the doc comment: the deletion stands even if its record cannot.
+    }
+}
+/** Deletions the cleanup recorded, oldest first. Unreadable lines are skipped. */
+export function readArtifactDeletions(repoRoot, opts = {}) {
+    let text;
+    try {
+        text = readFileSync(join(resolve(repoRoot), DELETION_LOG), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const since = opts.since?.getTime() ?? -Infinity;
+    const records = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const record = JSON.parse(line);
+            if (typeof record?.name === "string" && Date.parse(record.deleted_at) >= since)
+                records.push(record);
+        }
+        catch {
+            // A torn or foreign line does not hide the others.
+        }
+    }
+    return records;
+}
+/** Sibling of the artifacts root, like the deletion log, so it never enters the inventory. */
+const USAGE_CACHE = ".harnery/artifact-usage.json";
+const LARGEST_HOLDS = 5;
+/** Bytes available to this user on the artifact store's filesystem, or null. */
+export function artifactFreeBytes(repoRoot) {
+    try {
+        const root = artifactsRoot(repoRoot);
+        const stat = statfsSync(existsSync(root) ? root : resolve(repoRoot));
+        const free = Number(stat.bavail) * Number(stat.bsize);
+        return Number.isFinite(free) && free >= 0 ? free : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Held bytes, free disk, and warnings for one full inventory. Held work is
+ * never deleted: the held budget and the disk floor only report. Records the
+ * measurement in `.harnery/artifact-usage.json` so `create` and `hold` can
+ * warn without walking the store.
+ */
+export function artifactUsageReport(repoRoot, rows, opts = {}) {
+    const now = opts.now ?? new Date();
+    const kept = rows.filter((row) => row.action !== "deleted");
+    const held = kept.filter((row) => row.classification === "managed-held");
+    const heldBytes = held.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
+    const largest = [...held]
+        .sort((left, right) => (right.bytes ?? 0) - (left.bytes ?? 0))
+        .slice(0, LARGEST_HOLDS)
+        .map((row) => heldSummary(row));
+    const freeBytes = artifactFreeBytes(repoRoot);
+    if (existsSync(artifactsRoot(repoRoot))) {
+        writeUsageCache(repoRoot, {
+            measured_at: now.toISOString(),
+            bytes: kept.reduce((sum, row) => sum + (row.bytes ?? 0), 0),
+            held_bytes: heldBytes,
+            free_bytes: freeBytes,
+            largest_holds: largest,
+        });
+    }
+    return usageReport(repoRoot, heldBytes, largest, freeBytes, null);
+}
+/** The cached measurement, or null when none was recorded or it is unreadable. */
+export function readArtifactUsageCache(repoRoot) {
+    try {
+        const value = JSON.parse(readFileSync(join(resolve(repoRoot), USAGE_CACHE), "utf8"));
+        if (!value ||
+            !validIso(value.measured_at) ||
+            typeof value.held_bytes !== "number" ||
+            typeof value.bytes !== "number")
+            return null;
+        return {
+            measured_at: value.measured_at,
+            bytes: value.bytes,
+            held_bytes: value.held_bytes,
+            free_bytes: typeof value.free_bytes === "number" ? value.free_bytes : null,
+            largest_holds: Array.isArray(value.largest_holds) ? value.largest_holds : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Usage for commands that must stay cheap (`create`, `hold`): held bytes from
+ * the last full inventory, free disk measured now. Never walks the store.
+ */
+export function artifactQuickUsage(repoRoot) {
+    const cache = readArtifactUsageCache(repoRoot);
+    const freeBytes = artifactFreeBytes(repoRoot);
+    const report = usageReport(repoRoot, cache?.held_bytes ?? 0, cache?.largest_holds ?? [], freeBytes, cache?.measured_at ?? null);
+    return {
+        usage: {
+            held_bytes: cache?.held_bytes ?? null,
+            held_measured_at: cache?.measured_at ?? null,
+            free_bytes: freeBytes,
+        },
+        low_disk: report.low_disk,
+        min_free_bytes: report.min_free_bytes,
+        warnings: report.warnings,
+    };
+}
+/**
+ * Refuse new large work when the artifact store's disk is below its floor.
+ * `create --big` calls this; `--allow-low-disk` is the deliberate override.
+ */
+export function assertArtifactDiskFloor(repoRoot) {
+    const minFree = artifactMinFreeBytes(repoRoot);
+    const freeBytes = artifactFreeBytes(repoRoot);
+    if (minFree === 0 || freeBytes === null || freeBytes >= minFree)
+        return;
+    const bin = resolveBinName(repoRoot);
+    throw new Error(`only ${gib(freeBytes)} is free on the artifact store's disk, below the ${gib(minFree)} floor (artifacts.min_free_bytes), so a --big workspace was not created. Free space with \`${bin} artifacts clean --yes\`, \`${bin} artifacts discard <ref> --reason <text>\` for reviewed work, or \`${bin} artifacts unhold <ref> --id <id>\` for finished holds, then retry. Pass --allow-low-disk to create it anyway.`);
+}
+function heldSummary(row) {
+    const parsed = readManifest(row.path);
+    return {
+        name: row.name,
+        bytes: row.bytes ?? 0,
+        holds: parsed.ok
+            ? parsed.manifest.holds.map((hold) => ({
+                id: hold.id,
+                set_by: hold.set_by.name ?? hold.set_by.instance_id,
+                expires_at: hold.expires_at ?? null,
+                persistent: hold.persistent === true,
+            }))
+            : [],
+    };
+}
+function usageReport(repoRoot, heldBytes, largest, freeBytes, measuredAt) {
+    const maxHeld = artifactMaxHeldBytes(repoRoot);
+    const minFree = artifactMinFreeBytes(repoRoot);
+    const heldOver = heldBytes > maxHeld;
+    const lowDisk = minFree > 0 && freeBytes !== null && freeBytes < minFree;
+    const bin = resolveBinName(repoRoot);
+    const warnings = [];
+    if (heldOver) {
+        const list = largest
+            .map((item) => `${item.name} (${gib(item.bytes)}${item.holds.length ? `, hold ${item.holds.map((hold) => hold.id).join(", ")}` : ""})`)
+            .join("; ");
+        warnings.push(`Held artifacts use ${gib(heldBytes)}${measuredAt ? ` as of ${measuredAt}` : ""}, above the ${gib(maxHeld)} held budget (artifacts.max_held_bytes). Holds are never deleted automatically; release or prune the largest${list ? `: ${list}` : ""}. Remove a finished hold with \`${bin} artifacts unhold <name> --id <id>\`.`);
+    }
+    if (lowDisk) {
+        warnings.push(`Only ${gib(freeBytes)} is free on the artifact store's disk, below the ${gib(minFree)} floor (artifacts.min_free_bytes). Free space with \`${bin} artifacts clean --yes\`, discard reviewed workspaces, or unhold finished work; \`${bin} artifacts create --big\` refuses until then.`);
+    }
+    return {
+        held_bytes: heldBytes,
+        max_held_bytes: maxHeld,
+        held_over_budget: heldOver,
+        largest_holds: largest,
+        free_bytes: freeBytes,
+        min_free_bytes: minFree,
+        low_disk: lowDisk,
+        warnings,
+    };
+}
+function writeUsageCache(repoRoot, cache) {
+    try {
+        const path = join(resolve(repoRoot), USAGE_CACHE);
+        const temp = `${path}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(cache, null, 2)}\n`, { mode: stateFileMode() });
+        renameSync(temp, path);
+    }
+    catch {
+        // The cache only feeds warnings; a failed write must not fail the inventory.
+    }
+}
+function gib(bytes) {
+    return `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+}
 /** Sibling of the artifacts root so the stamp never appears in the inventory scan. */
 const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
 /**
@@ -429,9 +773,11 @@ const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
  *
  * Retention was previously enforced only when someone remembered to run
  * `artifacts clean --yes`, so expired workspaces accumulated indefinitely on
- * busy hosts. This runs the exact same guarded deletion (expired or over-budget
- * managed entries, each re-classified immediately before removal;
- * unmanaged and legacy directories are never touched) at most once per
+ * busy hosts. This runs the exact same guarded deletion as `artifacts clean
+ * --yes` (expired entries, plus oversize or over-budget entries idle past
+ * `artifacts.idle_grace_hours`, each re-classified immediately before removal
+ * and recorded in the deletion log; unmanaged and legacy directories are never
+ * touched) at most once per
  * interval (default 1h after completion, 1m between partial/failed slices).
  * The owner-aware lock serializes callers; interrupted attempts can retry.
  * Disable with `artifacts.auto_clean: false` or
@@ -495,6 +841,7 @@ function autoCleanArtifactsUnlocked(repoRoot, opts) {
             .filter((row) => row.classification === "unknown")
             .map((row) => ({ name: row.name, reason: row.reason }));
         const status = failures.length ? "failed" : remaining ? "partial" : "completed";
+        artifactUsageReport(repoRoot, rows, { now });
         writeStamp({
             ...attempt,
             status,
@@ -564,13 +911,18 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         return rowFor(path, name, repoRoot, classification, parsed.reason);
     }
     const manifest = parsed.manifest;
-    const bytes = safeTreeSize(path);
+    const usage = safeTreeUsage(path);
     const lastModifiedMs = safeTreeLastModified(path, now, manifest.activity);
     const retentionAnchorMs = Date.parse(manifest.retention.renewed_at ?? manifest.created_at);
     const retentionWindowMs = Date.parse(manifest.retention.expires_at) - retentionAnchorMs;
     const effectiveLastModifiedMs = Math.max(retentionAnchorMs, lastModifiedMs ?? 0);
-    const effectiveExpiresAt = new Date(effectiveLastModifiedMs + retentionWindowMs).toISOString();
-    const base = rowFor(path, name, repoRoot, "managed-current", "retention has not expired", bytes);
+    const holds = artifactHoldState(manifest, now);
+    // A lapsed hold protected the files until its deadline, so ordinary expiry
+    // and the size-rule idle clock both count from the latest lapse.
+    const lapsedMs = Math.max(0, ...holds.lapsed.map((hold) => Date.parse(hold.expires_at)));
+    const effectiveExpiresAt = new Date(Math.max(effectiveLastModifiedMs + retentionWindowMs, lapsedMs)).toISOString();
+    const base = rowFor(path, name, repoRoot, "managed-current", "retention has not expired", usage);
+    const releasedMs = Math.max(manifest.released_at ? Date.parse(manifest.released_at) : 0, lapsedMs);
     Object.assign(base, {
         artifact_id: manifest.artifact_id,
         slug: manifest.slug,
@@ -579,13 +931,15 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         expires_at: effectiveExpiresAt,
         owner_instance_id: manifest.created_by?.instance_id ?? null,
         oversize_acknowledged: manifest.oversize_acknowledged === true,
+        idle_since: new Date(Math.max(effectiveLastModifiedMs, releasedMs)).toISOString(),
     });
-    if (manifest.holds.length > 0) {
+    if (holds.active.length > 0) {
         return {
             ...base,
             classification: "managed-held",
-            reason: `held: ${manifest.holds.map((hold) => hold.id).join(", ")}`,
+            reason: `held: ${holds.active.map((hold) => hold.id).join(", ")}`,
             action: "keep",
+            warning: holdWarning(repoRoot, name, holds.active, now),
         };
     }
     if (base.bytes === null || lastModifiedMs === null) {
@@ -605,7 +959,12 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         };
     }
     if (!manifest.released_at && manifest.created_by?.instance_id) {
-        const live = ownerLiveness(repoRoot, manifest.created_by.instance_id, now, freshnessSeconds);
+        const { state: live, heartbeatMs } = ownerLiveness(repoRoot, manifest.created_by.instance_id, now, freshnessSeconds);
+        // A stale heartbeat only starts the idle clock. The owner may be waiting
+        // for a human reply, so size rules still wait out the grace from here.
+        if (heartbeatMs !== null && heartbeatMs > Date.parse(base.idle_since)) {
+            base.idle_since = new Date(Math.min(heartbeatMs, now.getTime())).toISOString();
+        }
         if (live === "live") {
             return {
                 ...base,
@@ -625,44 +984,95 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
     }
     if (Date.parse(effectiveExpiresAt) > now.getTime())
         return base;
+    const lapsedNote = holds.lapsed.length
+        ? `; hold ${holds.lapsed.map((hold) => `${hold.id} lapsed at ${hold.expires_at}`).join(", ")}`
+        : "";
     return {
         ...base,
         classification: "managed-expired",
-        reason: `retention expired at ${effectiveExpiresAt}`,
+        reason: `retention expired at ${effectiveExpiresAt}${lapsedNote}`,
         action: "would-delete",
     };
 }
-function applyArtifactUnitBudget(repoRoot, row) {
+/** Advice for held rows: an imminent lapse, or a hold that never expires. */
+function holdWarning(repoRoot, name, active, now) {
+    const bin = resolveBinName(repoRoot);
+    const notes = [];
+    for (const hold of active) {
+        if (hold.persistent)
+            continue;
+        const renew = `${bin} artifacts hold ${name} --id ${hold.id} --reason ${JSON.stringify(hold.reason)}`;
+        if (!hold.expires_at) {
+            notes.push(`hold ${hold.id} has no expiry because it predates hold expiry; re-holding with \`${renew}\` starts one, or unhold it when the work is done`);
+        }
+        else if (Date.parse(hold.expires_at) - now.getTime() <= HOLD_LAPSE_WARNING_MS) {
+            notes.push(`hold ${hold.id} lapses at ${hold.expires_at}; renew with \`${renew}\``);
+        }
+    }
+    return notes.length ? notes.join("; ") : null;
+}
+/** When a size rule may first delete this unit, or null when it never may. */
+function sizeEvictableAt(repoRoot, row) {
+    if (!row.idle_since)
+        return null;
+    const idleSince = Date.parse(row.idle_since);
+    if (!Number.isFinite(idleSince))
+        return null;
+    return idleSince + artifactIdleGraceHours(repoRoot) * 60 * 60 * 1000;
+}
+function applyArtifactUnitBudget(repoRoot, row, now) {
     const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+    if (!["managed-current", "managed-active"].includes(row.classification) ||
+        row.bytes === null ||
+        row.bytes <= maxUnitBytes ||
+        row.oversize_acknowledged) {
+        return row;
+    }
+    const evictableAt = sizeEvictableAt(repoRoot, row);
     if (row.classification === "managed-current" &&
-        row.bytes !== null &&
-        row.bytes > maxUnitBytes &&
-        !row.oversize_acknowledged) {
+        evictableAt !== null &&
+        now.getTime() >= evictableAt) {
         return {
             ...row,
             classification: "managed-oversize",
             action: "would-delete",
-            reason: `bundle uses ${row.bytes} bytes, above the ${maxUnitBytes}-byte ceiling without --big`,
+            reason: `bundle uses ${row.bytes} bytes on disk, above the ${maxUnitBytes}-byte ceiling without --big, and has been idle for ${artifactIdleGraceHours(repoRoot)}h`,
         };
     }
-    return row;
+    const when = row.classification === "managed-active" || evictableAt === null
+        ? `${artifactIdleGraceHours(repoRoot)}h after its owner goes idle`
+        : `after ${new Date(evictableAt).toISOString()} unless it changes first`;
+    return {
+        ...row,
+        warning: `uses ${row.bytes} bytes on disk, above the ${maxUnitBytes}-byte per-workspace ceiling; cleanup will delete it ${when}. If it is meant to be this large, run ${resolveBinName(repoRoot)} artifacts allow-big ${row.name}; otherwise move rebuildable content out of the artifact store`,
+    };
 }
-function applyArtifactBudgets(repoRoot, inputRows) {
+function applyArtifactBudgets(repoRoot, inputRows, now) {
     const maxBytes = artifactMaxBytes(repoRoot);
-    const rows = inputRows.map((row) => applyArtifactUnitBudget(repoRoot, { ...row }));
-    const managedBytes = rows.reduce((sum, row) => sum + (row.artifact_id && row.bytes !== null ? row.bytes : 0), 0);
+    const rows = inputRows.map((row) => applyArtifactUnitBudget(repoRoot, { ...row }, now));
+    // Held units can never be evicted, so counting them would push every other
+    // unit out without bringing the store under budget.
+    const managedBytes = rows.reduce((sum, row) => sum +
+        (row.artifact_id && row.classification !== "managed-held" && row.bytes !== null
+            ? row.bytes
+            : 0), 0);
     let retainedBytes = managedBytes -
         rows.reduce((sum, row) => sum + (row.action === "would-delete" && row.bytes !== null ? row.bytes : 0), 0);
     if (retainedBytes <= maxBytes)
         return rows;
     const candidates = rows
-        .filter((row) => row.classification === "managed-current" && row.action === "keep" && row.bytes !== null)
+        .filter((row) => {
+        if (row.classification !== "managed-current" || row.action !== "keep" || row.bytes === null)
+            return false;
+        const evictableAt = sizeEvictableAt(repoRoot, row);
+        return evictableAt !== null && now.getTime() >= evictableAt;
+    })
         .sort((left, right) => `${left.expires_at ?? ""}\0${left.created_at ?? ""}\0${left.name}`.localeCompare(`${right.expires_at ?? ""}\0${right.created_at ?? ""}\0${right.name}`));
     for (const row of candidates) {
         if (retainedBytes <= maxBytes)
             break;
         row.classification = "managed-over-budget";
-        row.reason = `repository artifact budget is ${maxBytes} bytes; earliest-expiring inactive bundles are removed first`;
+        row.reason = `repository artifact budget is ${maxBytes} bytes of disk use; earliest-expiring bundles idle for ${artifactIdleGraceHours(repoRoot)}h are removed first`;
         row.action = "would-delete";
         retainedBytes -= row.bytes ?? 0;
     }
@@ -966,9 +1376,29 @@ function validHold(value) {
         typeof hold.reason === "string" &&
         !!hold.reason.trim() &&
         validActor(hold.set_by) &&
-        validIso(hold.set_at));
+        validIso(hold.set_at) &&
+        (hold.expires_at === undefined || validIso(hold.expires_at)) &&
+        (hold.persistent === undefined || hold.persistent === true) &&
+        !(hold.persistent && hold.expires_at !== undefined));
+}
+const HOLD_LAPSE_WARNING_MS = 48 * 60 * 60 * 1000;
+/**
+ * Split holds into those still in force and those that lapsed. A persistent
+ * hold never lapses. A hold recorded before holds expired has no `expires_at`
+ * and stays in force until its owner removes or renews it.
+ */
+export function artifactHoldState(manifest, now = new Date()) {
+    const active = [];
+    const lapsed = [];
+    for (const hold of manifest.holds) {
+        if (hold.persistent || !hold.expires_at || Date.parse(hold.expires_at) > now.getTime())
+            active.push(hold);
+        else
+            lapsed.push(hold);
+    }
+    return { active, lapsed };
 }
-function makeHold(input, actor, now) {
+function makeHold(input, actor, now, defaultDays) {
     assertValidDate(now, "now");
     if (!validActor(actor))
         throw new Error("a valid hold actor is required");
@@ -976,25 +1406,48 @@ function makeHold(input, actor, now) {
         throw new Error("invalid hold id");
     if (typeof input.reason !== "string" || !input.reason.trim())
         throw new Error("hold reason must not be empty");
-    return {
+    if (input.days !== undefined && input.minutes !== undefined)
+        throw new Error("choose either hold days or hold minutes");
+    if (input.persistent && (input.days !== undefined || input.minutes !== undefined))
+        throw new Error("a persistent hold takes no duration");
+    const hold = {
         id: input.id,
         reason: input.reason.trim(),
         set_by: { ...actor },
         set_at: now.toISOString(),
     };
+    if (input.persistent)
+        return { ...hold, persistent: true };
+    const minutes = input.minutes !== undefined
+        ? holdMinutes(input.minutes)
+        : holdDaysValue(input.days ?? defaultDays) * 24 * 60;
+    return { ...hold, expires_at: addMinutes(now, minutes).toISOString() };
+}
+function holdDaysValue(value) {
+    if (!Number.isInteger(value) || value <= 0 || value > 365)
+        throw new Error("hold days must be between 1 and 365");
+    return value;
+}
+function holdMinutes(value) {
+    if (!Number.isInteger(value) || value <= 0 || value > 365 * 24 * 60)
+        throw new Error("hold minutes must be between 1 and 525600");
+    return value;
 }
 function ownerLiveness(repoRoot, instanceId, now, freshnessSeconds) {
     try {
         const row = readLiveCoordinationRow(repoRoot, instanceId);
         if (!row)
-            return "stale";
+            return { state: "stale", heartbeatMs: null };
         const ts = Date.parse(row.last_heartbeat);
         if (!Number.isFinite(ts))
-            return "unknown";
-        return now.getTime() - ts <= freshnessSeconds * 1000 ? "live" : "stale";
+            return { state: "unknown", heartbeatMs: null };
+        return {
+            state: now.getTime() - ts <= freshnessSeconds * 1000 ? "live" : "stale",
+            heartbeatMs: ts,
+        };
     }
     catch {
-        return "unknown";
+        return { state: "unknown", heartbeatMs: null };
     }
 }
 function containsTrackedPath(repoRoot, path) {
@@ -1008,21 +1461,35 @@ function containsTrackedPath(repoRoot, path) {
     // If Git itself cannot answer, fail closed.
     return result.status !== 0 || result.stdout.length > 0;
 }
-function safeTreeSize(path) {
+/** Disk bytes for one entry. Windows reports no block count, so length stands in. */
+function allocatedBytes(st) {
+    return process.platform !== "win32" && Number.isFinite(st.blocks) ? st.blocks * 512 : st.size;
+}
+/**
+ * Measure a tree without following symlinks. Size rules read `disk`: a sparse
+ * image or a hard-linked environment would otherwise count many times its real
+ * footprint and push healthy workspaces over a budget they do not exceed.
+ */
+function safeTreeUsage(path, seen = new Set()) {
     try {
         const st = lstatSync(path);
-        if (st.isSymbolicLink())
-            return st.size;
-        if (st.isFile())
-            return st.size;
-        if (!st.isDirectory())
-            return 0;
-        let total = st.size;
+        if (!st.isDirectory()) {
+            if (!st.isFile() && !st.isSymbolicLink())
+                return { disk: 0, apparent: 0 };
+            const key = `${st.dev}:${st.ino}`;
+            if (st.nlink > 1 && seen.has(key))
+                return { disk: 0, apparent: st.size };
+            if (st.nlink > 1)
+                seen.add(key);
+            return { disk: allocatedBytes(st), apparent: st.size };
+        }
+        const total = { disk: allocatedBytes(st), apparent: st.size };
         for (const child of readdirSync(path)) {
-            const size = safeTreeSize(join(path, child));
-            if (size === null)
+            const usage = safeTreeUsage(join(path, child), seen);
+            if (usage === null)
                 return null;
-            total += size;
+            total.disk += usage.disk;
+            total.apparent += usage.apparent;
         }
         return total;
     }
@@ -1030,6 +1497,9 @@ function safeTreeSize(path) {
         return null;
     }
 }
+function safeTreeSize(path) {
+    return safeTreeUsage(path)?.disk ?? null;
+}
 /**
  * Return the newest filesystem change in a managed tree without following
  * symlinks. A small future tolerance protects a write racing the inventory
@@ -1043,7 +1513,7 @@ function safeTreeLastModified(path, now, activity) {
         return null;
     }
 }
-function rowFor(path, name, repoRoot, classification, reason, bytes = safeTreeSize(path)) {
+function rowFor(path, name, repoRoot, classification, reason, usage = safeTreeUsage(path)) {
     return {
         name,
         path,
@@ -1051,7 +1521,8 @@ function rowFor(path, name, repoRoot, classification, reason, bytes = safeTreeSi
         classification,
         reason,
         action: classification === "managed-expired" ? "would-delete" : "keep",
-        bytes,
+        bytes: usage?.disk ?? null,
+        apparent_bytes: usage?.apparent ?? null,
         artifact_id: null,
         slug: null,
         created_at: null,
@@ -1059,6 +1530,8 @@ function rowFor(path, name, repoRoot, classification, reason, bytes = safeTreeSi
         expires_at: null,
         owner_instance_id: null,
         oversize_acknowledged: false,
+        idle_since: null,
+        warning: null,
     };
 }
 function normalizeSlug(value) {