harnery 0.38.0 → 0.40.0

package/dist/core/artifacts/index.js

@@ -9,12 +9,16 @@
  */
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, 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, } from "../config.js";
+import { artifactAutoCleanEnabled, artifactAutoCleanIntervalHours, artifactDefaultRetentionDays, artifactMaxBytes, artifactMaxUnitBytes, coordFreshnessSeconds, resolveBinName, } from "../config.js";
+import { artifactRootEntries, readArtifactActivity, validArtifactActivity, } from "./activity.js";
 import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.js";
+import { withArtifactLock } from "./mutation-lock.js";
 export { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.js";
+export { ARTIFACT_DELIVERY_AUTO_ITEM_LIMIT, ARTIFACT_DELIVERY_MANIFEST, ARTIFACT_DELIVERY_SCHEMA_VERSION, parseArtifactDeliverySpec, readArtifactDeliveryManifest, renderArtifactDeliveryCard, resolveArtifactDeliveryManifest, writeArtifactDeliveryManifest, } from "./delivery-card.js";
 export function artifactCapabilities() {
     return {
         schema_version: ARTIFACT_SCHEMA_VERSION,
@@ -22,6 +26,8 @@ export function artifactCapabilities() {
         atomic_create_holds: true,
         owner_scoped_unhold: true,
         explicit_v1_migration: true,
+        minute_retention: true,
+        discard_after_review: true,
     };
 }
 export function artifactsRoot(repoRoot) {
@@ -72,7 +78,7 @@ function createArtifactUnlocked(repoRoot, input) {
         },
         ...(input.big ? { oversize_acknowledged: true } : {}),
     };
-    atomicWriteManifest(path, manifest);
+    atomicWriteManifest(path, manifest, now);
     return { path, manifest };
 }
 export function inventoryArtifacts(repoRoot, opts = {}) {
@@ -113,7 +119,9 @@ export function renewArtifact(repoRoot, ref, days, reason, input = {}) {
 function renewArtifactUnlocked(repoRoot, ref, days, reason, input) {
     const now = input.now ?? new Date();
     assertValidDate(now, "now");
-    const retentionDays = positiveDays(days);
+    const expiresAt = typeof days === "number"
+        ? addDays(now, positiveDays(days))
+        : addMinutes(now, positiveMinutes(days.minutes));
     const why = reason.trim();
     if (!why)
         throw new Error("renewal reason must not be empty");
@@ -124,17 +132,66 @@ function renewArtifactUnlocked(repoRoot, ref, days, reason, input) {
     const manifest = {
         ...parsed.manifest,
         retention: {
-            expires_at: addDays(now, retentionDays).toISOString(),
+            expires_at: expiresAt.toISOString(),
             renewed_at: now.toISOString(),
             reason: why,
         },
     };
-    atomicWriteManifest(path, manifest);
+    atomicWriteManifest(path, manifest, now);
     return manifest;
 }
 export function releaseArtifact(repoRoot, ref, input = {}) {
     return withArtifactLock(repoRoot, () => releaseArtifactUnlocked(repoRoot, ref, input));
 }
+/** Retire reviewed evidence without deleting it or extending an earlier deadline. */
+export function discardArtifact(repoRoot, ref, reason, input = {}) {
+    return withArtifactLock(repoRoot, () => {
+        const now = input.now ?? new Date();
+        assertValidDate(now, "now");
+        const minutes = positiveMinutes(input.minutes ?? 60);
+        const why = reason.trim();
+        if (!why)
+            throw new Error("discard requires a reason confirming the files are no longer needed");
+        const path = resolveArtifactRef(repoRoot, ref);
+        const entry = classifyArtifactPath(repoRoot, path, now, coordFreshnessSeconds(repoRoot));
+        if (!["managed-current", "managed-expired", "managed-active"].includes(entry.classification) ||
+            (entry.classification === "managed-active" &&
+                entry.owner_instance_id !== input.actor?.instance_id))
+            throw new Error(`cannot discard artifact: ${entry.reason}`);
+        const parsed = readManifest(path);
+        if (!parsed.ok)
+            throw new Error(parsed.reason);
+        const manifest = parsed.manifest;
+        const remaining = Date.parse(entry.expires_at) - now.getTime();
+        const priorWindow = Date.parse(manifest.retention.expires_at) -
+            Date.parse(manifest.retention.renewed_at ?? manifest.created_at);
+        const windowMs = Math.min(minutes * 60_000, remaining, priorWindow);
+        const updated = {
+            ...manifest,
+            retention: {
+                ...manifest.retention,
+                ...(windowMs > 0
+                    ? {
+                        renewed_at: now.toISOString(),
+                        expires_at: new Date(now.getTime() + windowMs).toISOString(),
+                    }
+                    : {}),
+                reason: why,
+            },
+            released_at: now.toISOString(),
+            released_by: input.actor,
+        };
+        atomicWriteManifest(path, updated, now);
+        return updated;
+    });
+}
+/** 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;
+    if (!/^[A-Za-z0-9_.-]+$/.test(target))
+        throw new Error("review guidance requires an artifact id or directory name");
+    return `After reviewing these files, if they are disposable or superseded and no review, handoff, failure investigation, or final evidence depends on them, run ${resolveBinName(repoRoot)} artifacts discard ${target} --reason "Reviewed; no longer needed" (60-minute grace). Otherwise retain them; use a hold for pending review.`;
+}
 function releaseArtifactUnlocked(repoRoot, ref, input) {
     const now = input.now ?? new Date();
     assertValidDate(now, "now");
@@ -147,7 +204,7 @@ function releaseArtifactUnlocked(repoRoot, ref, input) {
         released_at: now.toISOString(),
         released_by: input.actor,
     };
-    atomicWriteManifest(path, manifest);
+    atomicWriteManifest(path, manifest, now);
     return manifest;
 }
 export function holdArtifact(repoRoot, ref, input) {
@@ -166,7 +223,7 @@ export function holdArtifact(repoRoot, ref, input) {
             return parsed.manifest;
         }
         const manifest = { ...parsed.manifest, holds: [...parsed.manifest.holds, hold] };
-        atomicWriteManifest(path, manifest);
+        atomicWriteManifest(path, manifest, input.now);
         return manifest;
     });
 }
@@ -190,7 +247,7 @@ export function unholdArtifact(repoRoot, ref, id, input) {
             ...parsed.manifest,
             holds: parsed.manifest.holds.filter((item) => item.id !== id),
         };
-        atomicWriteManifest(path, manifest);
+        atomicWriteManifest(path, manifest, input.now);
         return manifest;
     });
 }
@@ -310,17 +367,27 @@ export function cleanArtifacts(repoRoot, opts = {}) {
     }
 }
 function cleanArtifactsUnlocked(repoRoot, opts) {
+    const started = performance.now();
     const now = opts.now ?? new Date();
     const freshnessSeconds = opts.freshnessSeconds ?? 600;
     const rows = inventoryArtifacts(repoRoot, { now, freshnessSeconds });
     if (!opts.yes)
         return rows;
+    let attempted = 0;
     return rows.map((entry) => {
         if (entry.action !== "would-delete")
             return entry;
+        if (attempted >= (opts.maxDeletes ?? Infinity) ||
+            (attempted > 0 && performance.now() - started >= (opts.timeBudgetMs ?? Infinity)))
+            return entry;
+        attempted++;
         // Reclassify immediately before removal. A renewal, release-state change,
         // heartbeat, symlink swap, or tracked file added since inventory must win.
-        const current = inventoryArtifacts(repoRoot, { now, freshnessSeconds }).find((row) => row.path === entry.path);
+        // Only repository-budget eviction needs a new whole-store plan. Expiry and
+        // 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));
         if (!current) {
             return { ...entry, classification: "unknown", reason: "entry disappeared", action: "keep" };
         }
@@ -357,18 +424,28 @@ function cleanArtifactsUnlocked(repoRoot, opts) {
 /** Sibling of the artifacts root so the stamp never appears in the inventory scan. */
 const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
 /**
- * Throttled expired-artifact sweep, fired as a SessionStart effect.
+ * Throttled expired-artifact sweep, fired at SessionStart and before new work.
  *
  * 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 (only
- * `managed-expired` entries, each re-classified immediately before removal;
+ * 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
- * interval (default 24h), claim-first via a stamp file so concurrent session
- * starts do not double-sweep. Disable with `artifacts.auto_clean: false` or
+ * 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
  * `HARNERY_ARTIFACT_AUTO_CLEAN=0`.
  */
 export function autoCleanArtifacts(repoRoot, opts = {}) {
+    if (!existsSync(artifactsRoot(repoRoot))) {
+        return { ran: false, reason: "no-root", deleted: 0, bytes: 0 };
+    }
+    if (!artifactAutoCleanEnabled(repoRoot)) {
+        return { ran: false, reason: "disabled", deleted: 0, bytes: 0 };
+    }
+    return withArtifactLock(repoRoot, () => autoCleanArtifactsUnlocked(repoRoot, opts));
+}
+function autoCleanArtifactsUnlocked(repoRoot, opts) {
     const now = opts.now ?? new Date();
     assertValidDate(now, "now");
     if (!existsSync(artifactsRoot(repoRoot))) {
@@ -381,23 +458,64 @@ export function autoCleanArtifacts(repoRoot, opts = {}) {
     const intervalMs = artifactAutoCleanIntervalHours() * 60 * 60 * 1000;
     try {
         const stamp = JSON.parse(readFileSync(stampPath, "utf8"));
-        const last = Date.parse(stamp.last_run_at ?? "");
-        if (Number.isFinite(last) && now.getTime() - last < intervalMs) {
+        const last = Date.parse(stamp.last_completed_at ?? "");
+        if ((stamp.status === "completed" &&
+            Number.isFinite(last) &&
+            now.getTime() - last < intervalMs) ||
+            (["partial", "failed"].includes(stamp.status ?? "") &&
+                Date.parse(stamp.retry_after ?? "") > now.getTime())) {
             return { ran: false, reason: "fresh", deleted: 0, bytes: 0 };
         }
     }
     catch {
         // Missing or unreadable stamp: sweep now and write a fresh one.
     }
-    // Claim first: a crash mid-sweep costs one skipped interval, while claiming
-    // after would let two concurrent session starts both walk the store.
-    writeFileSync(stampPath, `${JSON.stringify({ last_run_at: now.toISOString() }, null, 2)}\n`);
-    const rows = cleanArtifacts(repoRoot, { yes: true, now });
-    const deletedRows = rows.filter((row) => row.action === "deleted");
-    const deleted = deletedRows.length;
-    const bytes = deletedRows.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
-    writeFileSync(stampPath, `${JSON.stringify({ last_run_at: now.toISOString(), deleted, bytes }, null, 2)}\n`);
-    return { ran: true, reason: "swept", deleted, bytes };
+    const maxDeletes = opts.maxDeletes ?? 10;
+    const timeBudgetMs = opts.timeBudgetMs ?? 5000;
+    if (!Number.isSafeInteger(maxDeletes) ||
+        maxDeletes < 1 ||
+        !Number.isFinite(timeBudgetMs) ||
+        timeBudgetMs < 0)
+        throw new Error("cleanup limits must allow at least one deletion and a nonnegative time budget");
+    const attempt = { last_attempt_at: now.toISOString() };
+    const writeStamp = (state) => {
+        const temp = `${stampPath}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`);
+        renameSync(temp, stampPath);
+    };
+    writeStamp({ ...attempt, status: "running" });
+    try {
+        const rows = cleanArtifactsUnlocked(repoRoot, { yes: true, now, maxDeletes, timeBudgetMs });
+        const deletedRows = rows.filter((row) => row.action === "deleted");
+        const deleted = deletedRows.length;
+        const bytes = deletedRows.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
+        const remaining = rows.filter((row) => row.action === "would-delete").length;
+        const failures = rows
+            .filter((row) => row.classification === "unknown")
+            .map((row) => ({ name: row.name, reason: row.reason }));
+        const status = failures.length ? "failed" : remaining ? "partial" : "completed";
+        writeStamp({
+            ...attempt,
+            status,
+            deleted,
+            bytes,
+            remaining,
+            failures,
+            ...(status === "completed"
+                ? { last_completed_at: now.toISOString() }
+                : { retry_after: new Date(now.getTime() + 60_000).toISOString() }),
+        });
+        return { ran: true, reason: status === "completed" ? "swept" : status, deleted, bytes };
+    }
+    catch (error) {
+        writeStamp({
+            ...attempt,
+            status: "failed",
+            error: errorMessage("cleanup failed", error),
+            retry_after: new Date(now.getTime() + 60_000).toISOString(),
+        });
+        throw error;
+    }
 }
 export function resolveArtifactRef(repoRoot, ref) {
     const root = artifactsRoot(repoRoot);
@@ -446,7 +564,7 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
     }
     const manifest = parsed.manifest;
     const bytes = safeTreeSize(path);
-    const lastModifiedMs = safeTreeLastModified(path, now);
+    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);
@@ -513,20 +631,24 @@ function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
         action: "would-delete",
     };
 }
-function applyArtifactBudgets(repoRoot, inputRows) {
+function applyArtifactUnitBudget(repoRoot, row) {
     const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
-    const maxBytes = artifactMaxBytes(repoRoot);
-    const rows = inputRows.map((row) => ({ ...row }));
-    for (const row of rows) {
-        if (row.classification === "managed-current" &&
-            row.bytes !== null &&
-            row.bytes > maxUnitBytes &&
-            !row.oversize_acknowledged) {
-            row.classification = "managed-oversize";
-            row.reason = `bundle uses ${row.bytes} bytes, above the ${maxUnitBytes}-byte ceiling without --big`;
-            row.action = "would-delete";
-        }
+    if (row.classification === "managed-current" &&
+        row.bytes !== null &&
+        row.bytes > maxUnitBytes &&
+        !row.oversize_acknowledged) {
+        return {
+            ...row,
+            classification: "managed-oversize",
+            action: "would-delete",
+            reason: `bundle uses ${row.bytes} bytes, above the ${maxUnitBytes}-byte ceiling without --big`,
+        };
     }
+    return row;
+}
+function applyArtifactBudgets(repoRoot, inputRows) {
+    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);
     let retainedBytes = managedBytes -
         rows.reduce((sum, row) => sum + (row.action === "would-delete" && row.bytes !== null ? row.bytes : 0), 0);
@@ -614,10 +736,19 @@ export function parseArtifactManifest(value) {
     if (m.oversize_acknowledged !== undefined && typeof m.oversize_acknowledged !== "boolean") {
         return { ok: false, reason: "invalid oversize_acknowledged" };
     }
+    if (m.activity !== undefined && !validArtifactActivity(m.activity)) {
+        return { ok: false, reason: "invalid activity checkpoint" };
+    }
     return { ok: true, manifest: m };
 }
-function atomicWriteManifest(path, manifest) {
+function atomicWriteManifest(path, manifest, now = new Date()) {
     const target = join(path, ARTIFACT_MANIFEST);
+    manifest.activity = readArtifactActivity(path, now, existsSync(target)
+        ? manifest.activity
+        : {
+            last_changed_at: manifest.created_at,
+            root_entries_sha256: artifactRootEntries(path),
+        });
     const tmp = `${target}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;
     try {
         writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
@@ -693,7 +824,7 @@ export function migrateArtifacts(repoRoot, opts = {}) {
                 }
                 if (readFileSync(target, "utf8") !== preimage)
                     throw new Error("manifest changed before migration");
-                atomicWriteManifest(path, parsed.manifest);
+                atomicWriteManifest(path, parsed.manifest, opts.now);
                 return {
                     path,
                     action: "migrated",
@@ -708,22 +839,120 @@ export function migrateArtifacts(repoRoot, opts = {}) {
     };
     return opts.yes ? withArtifactLock(repoRoot, migrate) : migrate();
 }
-/** A persistent directory lock fails closed on contention or a crashed owner. */
-function withArtifactLock(repoRoot, action) {
-    const lock = join(resolve(repoRoot), ".harnery/artifacts-mutation.lock");
-    mkdirSync(dirname(lock), { recursive: true });
-    try {
-        mkdirSync(lock);
-    }
-    catch (error) {
-        throw new Error(errorMessage("artifact store mutation lock unavailable; retry after its owner finishes", error));
-    }
-    try {
-        return action();
-    }
-    finally {
-        rmdirSync(lock);
-    }
+/** Repair only a provable, untouched v1-to-v2 migration. Never delete payloads.
+ * Old migrations saved the original manifest but not the original root stat.
+ * The exact preimage and coincident root/manifest/receipt timestamps bound this
+ * correction. Any later root change or metadata mutation requires manual review.
+ */
+export function repairArtifactActivity(repoRoot, opts = {}) {
+    const repair = () => {
+        const now = opts.now ?? new Date();
+        assertValidDate(now, "now");
+        const preimageRoot = join(resolve(repoRoot), ".harnery/artifact-migrations");
+        const preimages = new Map();
+        if (existsSync(preimageRoot) && !lstatSync(preimageRoot).isSymbolicLink()) {
+            for (const name of readdirSync(preimageRoot)) {
+                if (!/^[a-f0-9]{64}\.v1\.json$/.test(name))
+                    continue;
+                const file = join(preimageRoot, name);
+                try {
+                    const stat = lstatSync(file);
+                    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+                        continue;
+                    const bytes = readFileSync(file, "utf8");
+                    if (`${createHash("sha256").update(bytes).digest("hex")}.v1.json` !== name)
+                        continue;
+                    const old = JSON.parse(bytes);
+                    if (old?.schema_version !== 1 ||
+                        Object.hasOwn(old, "holds") ||
+                        Object.hasOwn(old, "activity"))
+                        continue;
+                    const upgraded = { ...old, schema_version: ARTIFACT_SCHEMA_VERSION, holds: [] };
+                    const parsed = parseArtifactManifest(upgraded);
+                    if (!parsed.ok)
+                        continue;
+                    const items = preimages.get(parsed.manifest.artifact_id) ?? [];
+                    items.push({ value: upgraded, path: file, mtime: stat.mtimeMs });
+                    preimages.set(parsed.manifest.artifact_id, items);
+                }
+                catch {
+                    // Unverifiable preimages confer no repair authority.
+                }
+            }
+        }
+        const root = artifactsRoot(repoRoot);
+        if (!existsSync(root))
+            return [];
+        return readdirSync(root)
+            .sort()
+            .map((name) => {
+            const path = join(root, name);
+            try {
+                const parsed = readManifest(path);
+                if (!parsed.ok)
+                    throw new Error(parsed.reason);
+                const manifest = parsed.manifest;
+                if (manifest.activity)
+                    return { path, action: "keep", reason: "activity already recorded" };
+                const source = preimages
+                    .get(manifest.artifact_id)
+                    ?.find((item) => isDeepStrictEqual(item.value, manifest));
+                if (!source)
+                    throw new Error("no exact migration preimage");
+                if (containsTrackedPath(repoRoot, path))
+                    throw new Error("artifact contains tracked files");
+                const target = join(path, ARTIFACT_MANIFEST);
+                const before = readFileSync(target, "utf8");
+                const unitStat = lstatSync(path);
+                const manifestStat = lstatSync(target);
+                if (unitStat.mtimeMs !== manifestStat.mtimeMs ||
+                    unitStat.ctimeMs !== manifestStat.ctimeMs ||
+                    manifestStat.mtimeMs !== manifestStat.ctimeMs ||
+                    manifestStat.mtimeMs < source.mtime ||
+                    manifestStat.mtimeMs - source.mtime > 5000)
+                    throw new Error("root or manifest changed outside the recorded migration");
+                const anchor = manifest.retention.renewed_at ?? manifest.created_at;
+                const oldActivity = readArtifactActivity(path, now);
+                const activity = readArtifactActivity(path, now, {
+                    last_changed_at: anchor,
+                    root_entries_sha256: artifactRootEntries(path),
+                });
+                const windowMs = Date.parse(manifest.retention.expires_at) - Date.parse(anchor);
+                const expiry = (changedAt) => new Date(Math.max(Date.parse(anchor), Date.parse(changedAt)) + windowMs).toISOString();
+                const row = {
+                    path,
+                    action: opts.yes ? "repaired" : "would-repair",
+                    reason: "exact migration preimage; unchanged root; payload activity and retention preserved",
+                    previous_expires_at: expiry(oldActivity.last_changed_at),
+                    repaired_expires_at: expiry(activity.last_changed_at),
+                };
+                if (!opts.yes)
+                    return row;
+                const receipt = join(preimageRoot, `${manifest.artifact_id}.${randomUUID()}.activity-repair.json`);
+                writeFileSync(receipt, `${JSON.stringify({
+                    schema_version: 1,
+                    repaired_at: now.toISOString(),
+                    path: relative(repoRoot, path),
+                    preimage_path: relative(repoRoot, source.path),
+                    original_manifest: before,
+                    activity,
+                    previous_expires_at: row.previous_expires_at,
+                    repaired_expires_at: row.repaired_expires_at,
+                }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+                const current = lstatSync(path);
+                if (readFileSync(target, "utf8") !== before ||
+                    current.mtimeMs !== unitStat.mtimeMs ||
+                    current.ctimeMs !== unitStat.ctimeMs)
+                    throw new Error("artifact changed before repair");
+                atomicWriteManifest(path, { ...manifest, activity }, now);
+                return { ...row, receipt_path: receipt };
+            }
+            catch (error) {
+                return { path, action: "keep", reason: errorMessage("activity repair refused", error) };
+            }
+        });
+    };
+    return opts.yes ? withArtifactLock(repoRoot, repair) : repair();
 }
 function validHoldId(value) {
     return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value);
@@ -805,26 +1034,9 @@ function safeTreeSize(path) {
  * symlinks. A small future tolerance protects a write racing the inventory
  * scan; timestamps farther ahead are ignored as clock-skewed metadata.
  */
-function safeTreeLastModified(path, now) {
-    const nowMs = now.getTime();
-    const futureToleranceMs = 5 * 60 * 1000;
+function safeTreeLastModified(path, now, activity) {
     try {
-        const st = lstatSync(path);
-        let latest = 0;
-        for (const timestamp of [st.mtimeMs, st.ctimeMs]) {
-            if (Number.isFinite(timestamp) && timestamp <= nowMs + futureToleranceMs) {
-                latest = Math.max(latest, Math.min(timestamp, nowMs));
-            }
-        }
-        if (st.isSymbolicLink() || !st.isDirectory())
-            return latest;
-        for (const child of readdirSync(path)) {
-            const childLatest = safeTreeLastModified(join(path, child), now);
-            if (childLatest === null)
-                return null;
-            latest = Math.max(latest, childLatest);
-        }
-        return latest;
+        return Date.parse(readArtifactActivity(path, now, activity).last_changed_at);
     }
     catch {
         return null;

package/dist/core/artifacts/mutation-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withArtifactLock<T>(repoRoot: string, action: () => T): T;
+//# sourceMappingURL=mutation-lock.d.ts.map

package/dist/core/artifacts/mutation-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-lock.d.ts","sourceRoot":"","sources":["../../../src/core/artifacts/mutation-lock.ts"],"names":[],"mappings":"AAqEA,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAoCxE"}

package/dist/core/artifacts/mutation-lock.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { processStartToken } from "../agents/state/proc-start.js";
+/** Age is never authority to evict an owner. Unknown owners fail closed. */
+function reclaimDeadOwner(lock) {
+    try {
+        const stat = lstatSync(lock);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return false;
+        const names = readdirSync(lock);
+        if (names.length !== 1 || !/^owner-[0-9a-f-]{36}\.json$/.test(names[0]))
+            return false;
+        const ownerPath = join(lock, names[0]);
+        const ownerStat = lstatSync(ownerPath);
+        if (!ownerStat.isFile() || ownerStat.isSymbolicLink() || ownerStat.size > 4096)
+            return false;
+        const owner = JSON.parse(readFileSync(ownerPath, "utf8"));
+        if (owner.version !== 1 ||
+            owner.host !== hostname() ||
+            !Number.isSafeInteger(owner.pid) ||
+            owner.pid <= 0 ||
+            !(owner.process_start === null || typeof owner.process_start === "string"))
+            return false;
+        let dead = false;
+        try {
+            process.kill(owner.pid, 0);
+            const current = processStartToken(owner.pid);
+            // Wall-clock ps lstart output can drift even for a live process. Only
+            // boot-scoped procfs ticks establish PID reuse; other probes need ESRCH.
+            const bootScoped = /^l[0-9a-f]{8}\.\d+$/;
+            dead =
+                typeof owner.process_start === "string" &&
+                    bootScoped.test(owner.process_start) &&
+                    typeof current === "string" &&
+                    bootScoped.test(current) &&
+                    current !== owner.process_start;
+        }
+        catch (error) {
+            dead = error.code === "ESRCH";
+        }
+        if (!dead)
+            return false;
+        // Only the contender that removes this unique owner's file may remove the
+        // directory. A losing reaper must not unlink a replacement owner's lock.
+        unlinkSync(ownerPath);
+        rmdirSync(lock);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function withArtifactLock(repoRoot, action) {
+    // Probe before mkdir so a slow platform process probe cannot hold an
+    // ownerless lock open while other writers are trying to acquire it.
+    const owner = {
+        version: 1,
+        host: hostname(),
+        pid: process.pid,
+        process_start: processStartToken(process.pid),
+        acquired_at: new Date().toISOString(),
+    };
+    const lock = join(resolve(repoRoot), ".harnery/artifacts-mutation.lock");
+    mkdirSync(dirname(lock), { recursive: true });
+    try {
+        mkdirSync(lock);
+    }
+    catch {
+        if (!reclaimDeadOwner(lock)) {
+            throw new Error("artifact store mutation lock unavailable; a live or unverifiable owner holds it. " +
+                "Dead local owners recover automatically; an empty or invalid lock requires explicit inspection.");
+        }
+        // Another caller may win after recovery. Never retry by removing its lock.
+        mkdirSync(lock);
+    }
+    const ownerPath = join(lock, `owner-${randomUUID()}.json`);
+    try {
+        writeFileSync(ownerPath, JSON.stringify(owner), { flag: "wx" });
+        return action();
+    }
+    finally {
+        // A crash before publication or between these two calls leaves an empty
+        // directory. It cannot be distinguished safely from an initializing owner.
+        // Publication may have failed before creating a file. Remove only our
+        // unique file, then the empty directory; never recursively delete contents.
+        rmSync(ownerPath, { force: true });
+        rmdirSync(lock);
+    }
+}

package/dist/core/backup/host-snapshot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Freshness helpers shared by `harn backup snapshot` and the session-start
+ * scheduler. The host cache is a local, best-effort record of this machine's
+ * newest known snapshot: the scheduler reads it to skip a remote restic round
+ * trip when the host is plainly current, and restic stays the authority
+ * whenever the cache is missing, stale, or written by another host.
+ */
+export declare function parseBackupDuration(value: string): number | null;
+/** Newest snapshot time (epoch ms) in `restic snapshots --json` output, or null. */
+export declare function newestSnapshotTime(output: string): number | null;
+export interface HostSnapshotCache {
+    host: string;
+    snapshotAt: number;
+}
+export declare function hostSnapshotCachePath(harneryDir: string): string;
+export declare function readHostSnapshotCache(harneryDir: string): HostSnapshotCache | null;
+export declare function recordHostSnapshot(harneryDir: string, snapshotAt: number): void;
+//# sourceMappingURL=host-snapshot.d.ts.map

package/dist/core/backup/host-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-snapshot.d.ts","sourceRoot":"","sources":["../../../src/core/backup/host-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAShE;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWhE;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAalF;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAc/E"}