harnery 0.40.0 → 0.42.0

package/src/core/artifacts/index.ts

@@ -5,7 +5,9 @@
  * 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";
@@ -17,8 +19,10 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   rmSync,
+  statfsSync,
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -28,11 +32,21 @@ import {
   artifactAutoCleanEnabled,
   artifactAutoCleanIntervalHours,
   artifactDefaultRetentionDays,
+  artifactHoldDays,
+  artifactIdleGraceHours,
   artifactMaxBytes,
+  artifactMaxHeldBytes,
   artifactMaxUnitBytes,
+  artifactMinFreeBytes,
   coordFreshnessSeconds,
   resolveBinName,
 } from "../config.ts";
+import {
+  readCoordinationViewV3,
+  requireAuthoritySafeCoordinationViewV3,
+} from "../events/v3/coordination-view.ts";
+import { liveInstanceIdV3 } from "../events/v3/live-route-observer.ts";
+import { stateFileMode } from "../storage/modes.ts";
 import {
   type ArtifactActivity,
   artifactRootEntries,
@@ -91,11 +105,23 @@ export interface ArtifactHold {
   reason: string;
   set_by: ArtifactActor;
   set_at: string;
+  /** When the hold lapses unless renewed. Absent only on a persistent hold or
+   * a hold recorded before holds expired; the latter stays in force. */
+  expires_at?: string;
+  /** Set by embedding hosts whose hold mirrors an external lease. Never lapses. */
+  persistent?: true;
 }
 
 export interface ArtifactHoldInput {
   id: string;
   reason: string;
+  /** Hold lifetime in days (1 to 365); defaults to `artifacts.hold_days`. */
+  days?: number;
+  /** Hold lifetime in minutes (1 to 525,600); replaces `days`. */
+  minutes?: number;
+  /** For a hold that mirrors an external lease, such as an open checkout with
+   * unsynchronized work. The hold never lapses; its owner must remove it. */
+  persistent?: boolean;
 }
 
 export function artifactCapabilities() {
@@ -107,6 +133,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,
   } as const;
 }
 
@@ -130,7 +162,11 @@ export interface ArtifactInventoryEntry {
   classification: ArtifactClassification;
   reason: string;
   action: "keep" | "would-delete" | "deleted";
+  /** Disk use: allocated blocks, each hard-linked file counted once. Every
+   * size rule reads this figure. */
   bytes: number | null;
+  /** Sum of file lengths. A sparse file makes this larger than `bytes`. */
+  apparent_bytes: number | null;
   artifact_id: string | null;
   slug: string | null;
   created_at: string | null;
@@ -138,6 +174,11 @@ export interface ArtifactInventoryEntry {
   expires_at: string | null;
   owner_instance_id: string | null;
   oversize_acknowledged: boolean;
+  /** Latest file change, owner heartbeat, renewal, or release. Size rules wait
+   * `artifacts.idle_grace_hours` past this before they may delete. */
+  idle_since: string | null;
+  /** Advice for a unit that a size rule will delete once its grace ends. */
+  warning: string | null;
 }
 
 export interface ArtifactCreateInput {
@@ -213,7 +254,8 @@ function createArtifactUnlocked(
   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");
   }
@@ -268,7 +310,7 @@ export function inventoryArtifacts(
   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(
@@ -326,6 +368,27 @@ function renewArtifactUnlocked(
   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: string,
+  ref: string,
+  input: ArtifactMutationInput = {},
+): ArtifactManifestV2 {
+  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: ArtifactManifestV2 = { ...parsed.manifest, oversize_acknowledged: true };
+    atomicWriteManifest(path, manifest, input.now);
+    return manifest;
+  });
+}
+
 export function releaseArtifact(
   repoRoot: string,
   ref: string,
@@ -384,6 +447,112 @@ export function discardArtifact(
   });
 }
 
+export interface ArtifactRemovalResult {
+  entry: ArtifactInventoryEntry;
+  reason: string;
+  deleted: boolean;
+}
+
+/** Preview or immediately remove one reviewed workspace belonging to this actor. */
+export function removeArtifact(
+  repoRoot: string,
+  ref: string,
+  reason: string,
+  input: ArtifactMutationInput & { yes?: boolean } = {},
+): ArtifactRemovalResult {
+  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" as const, 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: string): Map<string, string> {
+  const device = lstatSync(path).dev;
+  const entries = new Map<string, string>();
+  const walk = (target: string) => {
+    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: string, ref: string): string {
   const target = isAbsolute(ref) ? basename(ref) : ref;
@@ -416,7 +585,7 @@ export function holdArtifact(
   ref: string,
   input: ArtifactHoldInput & { actor: ArtifactActor; now?: Date },
 ): ArtifactManifestV2 {
-  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);
@@ -429,7 +598,19 @@ export function holdArtifact(
       ) {
         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: ArtifactHold =
+        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);
@@ -640,6 +821,7 @@ function cleanArtifactsUnlocked(
         : applyArtifactUnitBudget(
             repoRoot,
             classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds),
+            now,
           );
     if (!current) {
       return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
@@ -664,6 +846,7 @@ function cleanArtifactsUnlocked(
         };
       }
       rmSync(current.path, { recursive: true, force: false });
+      recordArtifactDeletion(repoRoot, current, now);
       return { ...current, action: "deleted" };
     } catch (error) {
       return {
@@ -676,6 +859,314 @@ function cleanArtifactsUnlocked(
   });
 }
 
+/** 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;
+
+export interface ArtifactDeletionRecord {
+  deleted_at: string;
+  name: string;
+  relative_path: string;
+  artifact_id: string | null;
+  slug: string | null;
+  owner_instance_id: string | null;
+  classification: ArtifactClassification;
+  reason: string;
+  bytes: number | null;
+  apparent_bytes: number | null;
+  expires_at: string | null;
+  idle_since: string | null;
+  removed_by?: ArtifactActor;
+}
+
+/**
+ * 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: string,
+  row: ArtifactInventoryEntry,
+  now: Date,
+  removedBy?: ArtifactActor,
+): void {
+  const record: ArtifactDeletionRecord = {
+    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: string,
+  opts: { since?: Date } = {},
+): ArtifactDeletionRecord[] {
+  let text: string;
+  try {
+    text = readFileSync(join(resolve(repoRoot), DELETION_LOG), "utf8");
+  } catch {
+    return [];
+  }
+  const since = opts.since?.getTime() ?? -Infinity;
+  const records: ArtifactDeletionRecord[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line) as ArtifactDeletionRecord;
+      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;
+
+export interface ArtifactHeldSummary {
+  name: string;
+  bytes: number;
+  holds: Array<{
+    id: string;
+    /** The hold owner's name when recorded, otherwise its instance id. */
+    set_by: string;
+    expires_at: string | null;
+    persistent: boolean;
+  }>;
+}
+
+/** Last full-inventory measurement, read by commands that must not walk the store. */
+export interface ArtifactUsageCache {
+  measured_at: string;
+  bytes: number;
+  held_bytes: number;
+  free_bytes: number | null;
+  largest_holds: ArtifactHeldSummary[];
+}
+
+export interface ArtifactUsageReport {
+  held_bytes: number;
+  max_held_bytes: number;
+  held_over_budget: boolean;
+  largest_holds: ArtifactHeldSummary[];
+  free_bytes: number | null;
+  min_free_bytes: number;
+  low_disk: boolean;
+  /** Plain sentences for a human; empty when nothing needs attention. */
+  warnings: string[];
+}
+
+/** Bytes available to this user on the artifact store's filesystem, or null. */
+export function artifactFreeBytes(repoRoot: string): number | null {
+  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: string,
+  rows: ArtifactInventoryEntry[],
+  opts: { now?: Date } = {},
+): ArtifactUsageReport {
+  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: string): ArtifactUsageCache | null {
+  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: string): {
+  usage: { held_bytes: number | null; held_measured_at: string | null; free_bytes: number | null };
+  low_disk: boolean;
+  min_free_bytes: number;
+  warnings: string[];
+} {
+  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: string): void {
+  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: ArtifactInventoryEntry): ArtifactHeldSummary {
+  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: string,
+  heldBytes: number,
+  largest: ArtifactHeldSummary[],
+  freeBytes: number | null,
+  measuredAt: string | null,
+): ArtifactUsageReport {
+  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: string[] = [];
+  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: string, cache: ArtifactUsageCache): void {
+  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: number): string {
+  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";
 
@@ -691,9 +1182,11 @@ export interface ArtifactAutoCleanResult {
  *
  * 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
@@ -773,6 +1266,7 @@ function autoCleanArtifactsUnlocked(
       .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,
@@ -846,13 +1340,23 @@ function classifyArtifactPath(
     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,
@@ -861,14 +1365,16 @@ function classifyArtifactPath(
     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) {
@@ -888,7 +1394,17 @@ function classifyArtifactPath(
     };
   }
   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,
@@ -907,44 +1423,101 @@ function classifyArtifactPath(
     }
   }
   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",
   };
 }
 
+/** Advice for held rows: an imminent lapse, or a hold that never expires. */
+function holdWarning(
+  repoRoot: string,
+  name: string,
+  active: ArtifactHold[],
+  now: Date,
+): string | null {
+  const bin = resolveBinName(repoRoot);
+  const notes: string[] = [];
+  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: string, row: ArtifactInventoryEntry): number | null {
+  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: string,
   row: ArtifactInventoryEntry,
+  now: Date,
 ): ArtifactInventoryEntry {
   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: string,
   inputRows: ArtifactInventoryEntry[],
+  now: Date,
 ): ArtifactInventoryEntry[] {
   const maxBytes = artifactMaxBytes(repoRoot);
-  const rows = inputRows.map((row) => applyArtifactUnitBudget(repoRoot, { ...row }));
+  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.bytes !== null ? row.bytes : 0),
+    (sum, row) =>
+      sum +
+      (row.artifact_id && row.classification !== "managed-held" && row.bytes !== null
+        ? row.bytes
+        : 0),
     0,
   );
   let retainedBytes =
@@ -956,10 +1529,12 @@ function applyArtifactBudgets(
   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}`,
@@ -968,7 +1543,7 @@ function applyArtifactBudgets(
   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;
   }
@@ -1068,7 +1643,7 @@ function atomicWriteManifest(path: string, manifest: ArtifactManifestV2, now = n
   try {
     writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
       encoding: "utf8",
-      mode: 0o600,
+      mode: stateFileMode(),
       flag: "wx",
     });
     renameSync(tmp, target);
@@ -1143,7 +1718,7 @@ export function migrateArtifacts(
             };
           mkdirSync(dirname(preimagePath), { recursive: true });
           try {
-            writeFileSync(preimagePath, preimage, { flag: "wx", mode: 0o600 });
+            writeFileSync(preimagePath, preimage, { flag: "wx", mode: stateFileMode() });
           } catch (error) {
             if (
               (error as NodeJS.ErrnoException).code !== "EEXIST" ||
@@ -1287,7 +1862,7 @@ export function repairArtifactActivity(
               null,
               2,
             )}\n`,
-            { flag: "wx", mode: 0o600 },
+            { flag: "wx", mode: stateFileMode() },
           );
           const current = lstatSync(path);
           if (
@@ -1318,26 +1893,73 @@ function validHold(value: unknown): value is ArtifactHold {
     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: Pick<ArtifactManifestV2, "holds">,
+  now: Date = new Date(),
+): { active: ArtifactHold[]; lapsed: ArtifactHold[] } {
+  const active: ArtifactHold[] = [];
+  const lapsed: ArtifactHold[] = [];
+  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: ArtifactHoldInput,
   actor: ArtifactActor | undefined,
   now: Date,
+  defaultDays: number,
 ): ArtifactHold {
   assertValidDate(now, "now");
   if (!validActor(actor)) throw new Error("a valid hold actor is required");
   if (!validHoldId(input.id)) 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: ArtifactHold = {
     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: number): number {
+  if (!Number.isInteger(value) || value <= 0 || value > 365)
+    throw new Error("hold days must be between 1 and 365");
+  return value;
+}
+
+function holdMinutes(value: number): number {
+  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(
@@ -1345,15 +1967,18 @@ function ownerLiveness(
   instanceId: string,
   now: Date,
   freshnessSeconds: number,
-): "live" | "stale" | "unknown" {
+): { state: "live" | "stale" | "unknown"; heartbeatMs: number | null } {
   try {
     const row = readLiveCoordinationRow(repoRoot, instanceId);
-    if (!row) return "stale";
+    if (!row) 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";
+    if (!Number.isFinite(ts)) return { state: "unknown", heartbeatMs: null };
+    return {
+      state: now.getTime() - ts <= freshnessSeconds * 1000 ? "live" : "stale",
+      heartbeatMs: ts,
+    };
   } catch {
-    return "unknown";
+    return { state: "unknown", heartbeatMs: null };
   }
 }
 
@@ -1368,17 +1993,39 @@ function containsTrackedPath(repoRoot: string, path: string): boolean {
   return result.status !== 0 || result.stdout.length > 0;
 }
 
-function safeTreeSize(path: string): number | null {
+interface TreeUsage {
+  /** Allocated disk bytes, counting each hard-linked inode once. */
+  disk: number;
+  /** Sum of file lengths, as `ls -l` reports them. */
+  apparent: number;
+}
+
+/** Disk bytes for one entry. Windows reports no block count, so length stands in. */
+function allocatedBytes(st: Stats): number {
+  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: string, seen = new Set<string>()): TreeUsage | null {
   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: TreeUsage = { disk: allocatedBytes(st), apparent: st.size };
     for (const child of readdirSync(path)) {
-      const size = safeTreeSize(join(path, child));
-      if (size === null) return null;
-      total += size;
+      const usage = safeTreeUsage(join(path, child), seen);
+      if (usage === null) return null;
+      total.disk += usage.disk;
+      total.apparent += usage.apparent;
     }
     return total;
   } catch {
@@ -1386,6 +2033,10 @@ function safeTreeSize(path: string): number | null {
   }
 }
 
+function safeTreeSize(path: string): number | null {
+  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
@@ -1405,7 +2056,7 @@ function rowFor(
   repoRoot: string,
   classification: ArtifactClassification,
   reason: string,
-  bytes: number | null = safeTreeSize(path),
+  usage: TreeUsage | null = safeTreeUsage(path),
 ): ArtifactInventoryEntry {
   return {
     name,
@@ -1414,7 +2065,8 @@ function rowFor(
     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,
@@ -1422,6 +2074,8 @@ function rowFor(
     expires_at: null,
     owner_instance_id: null,
     oversize_acknowledged: false,
+    idle_since: null,
+    warning: null,
   };
 }