harnery 0.38.0 → 0.40.0

package/src/core/artifacts/index.ts

@@ -18,11 +18,11 @@ import {
   readdirSync,
   readFileSync,
   renameSync,
-  rmdirSync,
   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.ts";
 import {
   artifactAutoCleanEnabled,
@@ -30,10 +30,36 @@ import {
   artifactDefaultRetentionDays,
   artifactMaxBytes,
   artifactMaxUnitBytes,
+  coordFreshnessSeconds,
+  resolveBinName,
 } from "../config.ts";
+import {
+  type ArtifactActivity,
+  artifactRootEntries,
+  readArtifactActivity,
+  validArtifactActivity,
+} from "./activity.ts";
 import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
+import { withArtifactLock } from "./mutation-lock.ts";
 
 export { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
+export type {
+  ArtifactDeliveryCard,
+  ArtifactDeliveryItem,
+  ArtifactDeliveryManifest,
+  ArtifactDeliveryPath,
+  ArtifactDeliveryUrl,
+} from "./delivery-card.ts";
+export {
+  ARTIFACT_DELIVERY_AUTO_ITEM_LIMIT,
+  ARTIFACT_DELIVERY_MANIFEST,
+  ARTIFACT_DELIVERY_SCHEMA_VERSION,
+  parseArtifactDeliverySpec,
+  readArtifactDeliveryManifest,
+  renderArtifactDeliveryCard,
+  resolveArtifactDeliveryManifest,
+  writeArtifactDeliveryManifest,
+} from "./delivery-card.ts";
 
 export interface ArtifactActor {
   instance_id: string;
@@ -57,6 +83,7 @@ export interface ArtifactManifestV2 {
   released_at?: string;
   released_by?: ArtifactActor;
   oversize_acknowledged?: boolean;
+  activity?: ArtifactActivity;
 }
 
 export interface ArtifactHold {
@@ -78,6 +105,8 @@ export function artifactCapabilities() {
     atomic_create_holds: true,
     owner_scoped_unhold: true,
     explicit_v1_migration: true,
+    minute_retention: true,
+    discard_after_review: true,
   } as const;
 }
 
@@ -208,7 +237,7 @@ function createArtifactUnlocked(
     },
     ...(input.big ? { oversize_acknowledged: true } : {}),
   };
-  atomicWriteManifest(path, manifest);
+  atomicWriteManifest(path, manifest, now);
   return { path, manifest };
 }
 
@@ -258,7 +287,7 @@ export function showArtifact(
 export function renewArtifact(
   repoRoot: string,
   ref: string,
-  days: number,
+  days: number | { minutes: number },
   reason: string,
   input: ArtifactMutationInput = {},
 ): ArtifactManifestV2 {
@@ -270,13 +299,16 @@ export function renewArtifact(
 function renewArtifactUnlocked(
   repoRoot: string,
   ref: string,
-  days: number,
+  days: number | { minutes: number },
   reason: string,
   input: ArtifactMutationInput,
 ): ArtifactManifestV2 {
   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");
   const path = resolveArtifactRef(repoRoot, ref);
@@ -285,12 +317,12 @@ function renewArtifactUnlocked(
   const manifest: ArtifactManifestV2 = {
     ...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;
 }
 
@@ -302,6 +334,64 @@ export function releaseArtifact(
   return withArtifactLock(repoRoot, () => releaseArtifactUnlocked(repoRoot, ref, input));
 }
 
+/** Retire reviewed evidence without deleting it or extending an earlier deadline. */
+export function discardArtifact(
+  repoRoot: string,
+  ref: string,
+  reason: string,
+  input: ArtifactMutationInput & { minutes?: number } = {},
+): ArtifactManifestV2 {
+  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: ArtifactManifestV2 = {
+      ...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: string, ref: string): string {
+  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: string,
   ref: string,
@@ -317,7 +407,7 @@ function releaseArtifactUnlocked(
     released_at: now.toISOString(),
     released_by: input.actor,
   };
-  atomicWriteManifest(path, manifest);
+  atomicWriteManifest(path, manifest, now);
   return manifest;
 }
 
@@ -342,7 +432,7 @@ export function holdArtifact(
       return parsed.manifest;
     }
     const manifest = { ...parsed.manifest, holds: [...parsed.manifest.holds, hold] };
-    atomicWriteManifest(path, manifest);
+    atomicWriteManifest(path, manifest, input.now);
     return manifest;
   });
 }
@@ -368,7 +458,7 @@ export function unholdArtifact(
       ...parsed.manifest,
       holds: parsed.manifest.holds.filter((item) => item.id !== id),
     };
-    atomicWriteManifest(path, manifest);
+    atomicWriteManifest(path, manifest, input.now);
     return manifest;
   });
 }
@@ -515,20 +605,42 @@ export function cleanArtifacts(
 
 function cleanArtifactsUnlocked(
   repoRoot: string,
-  opts: { yes?: boolean; now?: Date; freshnessSeconds?: number },
+  opts: {
+    yes?: boolean;
+    now?: Date;
+    freshnessSeconds?: number;
+    maxDeletes?: number;
+    timeBudgetMs?: number;
+  },
 ): ArtifactInventoryEntry[] {
+  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" };
     }
@@ -569,26 +681,40 @@ const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
 
 export interface ArtifactAutoCleanResult {
   ran: boolean;
-  reason: "swept" | "disabled" | "fresh" | "no-root";
+  reason: "swept" | "partial" | "failed" | "disabled" | "fresh" | "no-root";
   deleted: number;
   bytes: number;
 }
 
 /**
- * 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: string,
-  opts: { now?: Date } = {},
+  opts: { now?: Date; maxDeletes?: number; timeBudgetMs?: number } = {},
+): ArtifactAutoCleanResult {
+  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: string,
+  opts: { now?: Date; maxDeletes?: number; timeBudgetMs?: number },
 ): ArtifactAutoCleanResult {
   const now = opts.now ?? new Date();
   assertValidDate(now, "now");
@@ -601,26 +727,73 @@ export function autoCleanArtifacts(
   const stampPath = join(resolve(repoRoot), AUTO_CLEAN_STAMP);
   const intervalMs = artifactAutoCleanIntervalHours() * 60 * 60 * 1000;
   try {
-    const stamp = JSON.parse(readFileSync(stampPath, "utf8")) as { last_run_at?: string };
-    const last = Date.parse(stamp.last_run_at ?? "");
-    if (Number.isFinite(last) && now.getTime() - last < intervalMs) {
+    const stamp = JSON.parse(readFileSync(stampPath, "utf8")) as {
+      status?: string;
+      last_completed_at?: string;
+      retry_after?: string;
+    };
+    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: object) => {
+    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: string, ref: string): string {
@@ -674,7 +847,7 @@ function classifyArtifactPath(
   }
   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);
@@ -742,26 +915,33 @@ function classifyArtifactPath(
   };
 }
 
+function applyArtifactUnitBudget(
+  repoRoot: string,
+  row: ArtifactInventoryEntry,
+): ArtifactInventoryEntry {
+  const maxUnitBytes = artifactMaxUnitBytes(repoRoot);
+  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: string,
   inputRows: ArtifactInventoryEntry[],
 ): ArtifactInventoryEntry[] {
-  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";
-    }
-  }
+  const rows = inputRows.map((row) => applyArtifactUnitBudget(repoRoot, { ...row }));
 
   const managedBytes = rows.reduce(
     (sum, row) => sum + (row.artifact_id && row.bytes !== null ? row.bytes : 0),
@@ -866,11 +1046,24 @@ export function parseArtifactManifest(value: unknown): ParsedManifest | Manifest
   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 as ArtifactManifestV2 };
 }
 
-function atomicWriteManifest(path: string, manifest: ArtifactManifestV2): void {
+function atomicWriteManifest(path: string, manifest: ArtifactManifestV2, now = new Date()): void {
   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`, {
@@ -894,7 +1087,7 @@ export interface ArtifactMigrationEntry {
 /** Explicit, bounded v1 cutover. Preview never writes; every applied unit keeps its exact preimage. */
 export function migrateArtifacts(
   repoRoot: string,
-  opts: { yes?: boolean } = {},
+  opts: { yes?: boolean; now?: Date } = {},
 ): ArtifactMigrationEntry[] {
   const migrate = (): ArtifactMigrationEntry[] => {
     const root = artifactsRoot(repoRoot);
@@ -961,7 +1154,7 @@ export function migrateArtifacts(
           }
           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",
@@ -976,25 +1169,141 @@ export function migrateArtifacts(
   return opts.yes ? withArtifactLock(repoRoot, migrate) : migrate();
 }
 
-/** A persistent directory lock fails closed on contention or a crashed owner. */
-function withArtifactLock<T>(repoRoot: string, action: () => T): T {
-  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);
-  }
+export interface ArtifactActivityRepairEntry {
+  path: string;
+  action: "keep" | "would-repair" | "repaired";
+  reason: string;
+  previous_expires_at?: string;
+  repaired_expires_at?: string;
+  receipt_path?: string;
+}
+
+/** 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: string,
+  opts: { yes?: boolean; now?: Date } = {},
+): ArtifactActivityRepairEntry[] {
+  const repair = (): ArtifactActivityRepairEntry[] => {
+    const now = opts.now ?? new Date();
+    assertValidDate(now, "now");
+    const preimageRoot = join(resolve(repoRoot), ".harnery/artifact-migrations");
+    const preimages = new Map<string, { value: unknown; path: string; mtime: number }[]>();
+    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): ArtifactActivityRepairEntry => {
+        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: string) =>
+            new Date(Math.max(Date.parse(anchor), Date.parse(changedAt)) + windowMs).toISOString();
+          const row: ArtifactActivityRepairEntry = {
+            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: unknown): value is string {
@@ -1082,24 +1391,9 @@ function safeTreeSize(path: string): number | null {
  * symlinks. A small future tolerance protects a write racing the inventory
  * scan; timestamps farther ahead are ignored as clock-skewed metadata.
  */
-function safeTreeLastModified(path: string, now: Date): number | null {
-  const nowMs = now.getTime();
-  const futureToleranceMs = 5 * 60 * 1000;
+function safeTreeLastModified(path: string, now: Date, activity?: ArtifactActivity): number | null {
   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;
   }