@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/runs-ownership.ts

@@ -0,0 +1,136 @@
+/**
+ * Async run state-directory ownership.
+ * Owns: the marker proof required before launch and destructive retention.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+export const RUN_STATE_OWNERSHIP_FILE = ".pi-actors-run-state.json";
+
+interface RunStateOwnershipMarker {
+  created_at: string;
+  ownership_token: string;
+  run: string;
+  state_dir: string;
+  version: 1;
+}
+
+function markerPath(stateDir: string): string {
+  return join(stateDir, RUN_STATE_OWNERSHIP_FILE);
+}
+
+function comparablePath(path: string): string {
+  const resolved = resolve(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function isSystemTempRootAlias(resolved: string, canonical: string): boolean {
+  const tempRoot = resolve(tmpdir());
+  const relativeStateDir = relative(tempRoot, resolved);
+  if (
+    relativeStateDir === ".." ||
+    relativeStateDir.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) ||
+    isAbsolute(relativeStateDir)
+  ) {
+    return false;
+  }
+  const canonicalTempRoot = realpathSync.native(tempRoot);
+  const expectedCanonical = resolve(canonicalTempRoot, relativeStateDir);
+  return comparablePath(canonical) === comparablePath(expectedCanonical);
+}
+
+function assertCanonicalDirectory(stateDir: string): string {
+  const resolved = resolve(stateDir);
+  if (lstatSync(resolved).isSymbolicLink()) {
+    throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+  }
+  const canonical = realpathSync.native(resolved);
+  if (
+    comparablePath(canonical) !== comparablePath(resolved) &&
+    !isSystemTempRootAlias(resolved, canonical)
+  ) {
+    throw new Error(`Run state directory has an ambiguous symlink alias: ${resolved}`);
+  }
+  return resolved;
+}
+
+function readMarker(stateDir: string): RunStateOwnershipMarker | undefined {
+  try {
+    const value = JSON.parse(readFileSync(markerPath(stateDir), "utf8")) as Partial<RunStateOwnershipMarker>;
+    if (
+      value.version !== 1 ||
+      typeof value.run !== "string" ||
+      typeof value.state_dir !== "string" ||
+      typeof value.ownership_token !== "string" ||
+      !value.ownership_token
+    ) {
+      return undefined;
+    }
+    return value as RunStateOwnershipMarker;
+  } catch {
+    return undefined;
+  }
+}
+
+function assertMarkerMatches(
+  marker: RunStateOwnershipMarker | undefined,
+  stateDir: string,
+  run: string,
+): RunStateOwnershipMarker {
+  if (!marker) {
+    throw new Error(`Run state ownership marker is missing or invalid: ${stateDir}`);
+  }
+  if (marker.state_dir !== stateDir || marker.run !== run) {
+    throw new Error(`Run state ownership marker does not match run ${run}: ${stateDir}`);
+  }
+  return marker;
+}
+
+export function claimRunStateDirectory(stateDir: string, run: string): string {
+  const resolved = resolve(stateDir);
+  if (existsSync(resolved) && lstatSync(resolved).isSymbolicLink()) {
+    throw new Error(`Run state directory cannot be a symlink: ${resolved}`);
+  }
+  mkdirSync(resolved, { recursive: true });
+  const canonical = assertCanonicalDirectory(resolved);
+  const existing = readMarker(canonical);
+  if (existing) {
+    assertMarkerMatches(existing, canonical, run);
+    return canonical;
+  }
+  const existingEntries = readdirSync(canonical).filter(
+    (entry) => entry !== ".start.lock",
+  );
+  if (existingEntries.length > 0) {
+    throw new Error(`Refusing to claim existing non-run directory: ${canonical}`);
+  }
+  writeJsonAtomic(markerPath(canonical), {
+    created_at: new Date().toISOString(),
+    ownership_token: randomUUID(),
+    run,
+    state_dir: canonical,
+    version: 1,
+  } satisfies RunStateOwnershipMarker);
+  return canonical;
+}
+
+export function assertOwnedRunStateDirectory(
+  stateDir: string,
+  run: string,
+): string {
+  const canonical = assertCanonicalDirectory(stateDir);
+  assertMarkerMatches(readMarker(canonical), canonical, run);
+  return canonical;
+}

package/node_modules/@llblab/pi-actors/lib/runs-parent-teardown.ts

@@ -0,0 +1,257 @@
+/**
+ * Parent-session actor teardown.
+ * Owns: exact-owner running-run selection, kill revalidation, bounded outcomes, and partial-failure continuation.
+ */
+
+export interface ParentRunTeardownCandidate {
+  ownerId: string;
+  run: string;
+  runInstanceId?: string;
+  stateDir: string;
+}
+
+export type ParentRunTeardownOutcome =
+  | "killed"
+  | "skipped"
+  | "failed";
+
+export interface ParentRunTeardownAttempt extends ParentRunTeardownCandidate {
+  outcome: ParentRunTeardownOutcome;
+  reason?: string;
+}
+
+export interface ParentRunTeardownDiscoveryFailure {
+  path: string;
+  reason: string;
+}
+
+export interface ParentRunTeardownResult {
+  attempted: number;
+  discoveryFailed: number;
+  discoveryFailures: ParentRunTeardownDiscoveryFailure[];
+  failed: number;
+  killed: number;
+  skipped: number;
+  attempts: ParentRunTeardownAttempt[];
+}
+
+export interface ParentRunTeardownSummary extends ParentRunTeardownResult {
+  attemptsOmitted: number;
+  discoveryFailuresOmitted: number;
+  ownerId: string;
+  trigger: string;
+  ts: string;
+  version: 1;
+}
+
+const SUMMARY_ENTRY_LIMIT = 200;
+const SUMMARY_TEXT_LIMIT = 500;
+
+function boundedSummaryText(value: string): string {
+  return value.length > SUMMARY_TEXT_LIMIT
+    ? `${value.slice(0, SUMMARY_TEXT_LIMIT - 1)}…`
+    : value;
+}
+
+export function buildBoundedParentTeardownSummary(
+  result: ParentRunTeardownResult,
+  ownerId: string,
+  trigger: string,
+  ts: string,
+): ParentRunTeardownSummary {
+  const attempts = result.attempts.slice(0, SUMMARY_ENTRY_LIMIT).map((attempt) => ({
+    ownerId: boundedSummaryText(attempt.ownerId),
+    outcome: attempt.outcome,
+    ...(attempt.reason ? { reason: boundedSummaryText(attempt.reason) } : {}),
+    run: boundedSummaryText(attempt.run),
+    ...(attempt.runInstanceId
+      ? { runInstanceId: boundedSummaryText(attempt.runInstanceId) }
+      : {}),
+    stateDir: boundedSummaryText(attempt.stateDir),
+  }));
+  const discoveryFailures = result.discoveryFailures
+    .slice(0, SUMMARY_ENTRY_LIMIT)
+    .map((failure) => ({
+      path: boundedSummaryText(failure.path),
+      reason: boundedSummaryText(failure.reason),
+    }));
+  return {
+    attempted: result.attempted,
+    attempts,
+    attemptsOmitted: Math.max(0, result.attempts.length - attempts.length),
+    discoveryFailed: result.discoveryFailed,
+    discoveryFailures,
+    discoveryFailuresOmitted: Math.max(
+      0,
+      result.discoveryFailures.length - discoveryFailures.length,
+    ),
+    failed: result.failed,
+    killed: result.killed,
+    ownerId: boundedSummaryText(ownerId),
+    skipped: result.skipped,
+    trigger: boundedSummaryText(trigger),
+    ts: boundedSummaryText(ts),
+    version: 1,
+  };
+}
+
+export interface ParentRunTeardownDeps {
+  getRunStatus: (stateDir: string) => Record<string, unknown>;
+  killRun: (
+    stateDir: string,
+    expected: { ownerId: string; runInstanceId: string },
+  ) => Record<string, unknown>;
+  listRunStatuses: () =>
+    | Array<Record<string, unknown>>
+    | {
+        failures: ParentRunTeardownDiscoveryFailure[];
+        statuses: Array<Record<string, unknown>>;
+      };
+  recordAttempt: (attempt: ParentRunTeardownAttempt) => void;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function candidateFrom(
+  ownerId: string,
+  status: Record<string, unknown>,
+): ParentRunTeardownCandidate | undefined {
+  if (
+    status.ownerId !== ownerId ||
+    status.status !== "running" ||
+    typeof status.run !== "string" ||
+    typeof status.state_dir !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    ownerId,
+    run: status.run,
+    ...(typeof status.run_instance_id === "string"
+      ? { runInstanceId: status.run_instance_id }
+      : {}),
+    stateDir: status.state_dir,
+  };
+}
+
+export function selectParentRunTeardownCandidates(
+  ownerId: string | undefined,
+  statuses: Array<Record<string, unknown>>,
+): ParentRunTeardownCandidate[] {
+  if (!ownerId) return [];
+  const byStateDir = new Map<string, ParentRunTeardownCandidate>();
+  for (const status of statuses) {
+    const candidate = candidateFrom(ownerId, status);
+    if (candidate && !byStateDir.has(candidate.stateDir)) {
+      byStateDir.set(candidate.stateDir, candidate);
+    }
+  }
+  return [...byStateDir.values()].sort((left, right) =>
+    left.run.localeCompare(right.run),
+  );
+}
+
+function recordAttempt(
+  deps: ParentRunTeardownDeps,
+  attempt: ParentRunTeardownAttempt,
+): ParentRunTeardownAttempt {
+  try {
+    deps.recordAttempt(attempt);
+    return attempt;
+  } catch (error) {
+    return {
+      ...attempt,
+      outcome: "failed",
+      reason: `${attempt.reason ? `${attempt.reason}; ` : ""}evidence: ${errorMessage(error)}`,
+    };
+  }
+}
+
+export function teardownParentRuns(
+  ownerId: string | undefined,
+  deps: ParentRunTeardownDeps,
+): ParentRunTeardownResult {
+  let discovery: ReturnType<ParentRunTeardownDeps["listRunStatuses"]>;
+  try {
+    const listed = deps.listRunStatuses();
+    discovery = Array.isArray(listed)
+      ? { failures: [], statuses: listed }
+      : listed;
+  } catch (error) {
+    discovery = {
+      failures: [{ path: "<state-root>", reason: errorMessage(error) }],
+      statuses: [],
+    };
+  }
+  const candidates = selectParentRunTeardownCandidates(
+    ownerId,
+    discovery.statuses,
+  );
+  const attempts: ParentRunTeardownAttempt[] = [];
+  for (const candidate of candidates) {
+    let attempt: ParentRunTeardownAttempt;
+    try {
+      const current = deps.getRunStatus(candidate.stateDir);
+      if (!candidate.runInstanceId) {
+        attempt = {
+          ...candidate,
+          outcome: "failed",
+          reason: "run generation unavailable",
+        };
+      } else if (current.ownerId !== candidate.ownerId) {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "ownership changed",
+        };
+      } else if (current.run_instance_id !== candidate.runInstanceId) {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "run generation changed",
+        };
+      } else if (current.status !== "running") {
+        attempt = {
+          ...candidate,
+          outcome: "skipped",
+          reason: "already terminal",
+        };
+      } else {
+        const killed = deps.killRun(candidate.stateDir, {
+          ownerId: candidate.ownerId,
+          runInstanceId: candidate.runInstanceId,
+        });
+        attempt = killed.killed === true
+          ? { ...candidate, outcome: "killed" }
+          : {
+              ...candidate,
+              outcome: "failed",
+              reason:
+                typeof killed.reason === "string"
+                  ? killed.reason
+                  : "kill rejected",
+            };
+      }
+    } catch (error) {
+      attempt = {
+        ...candidate,
+        outcome: "failed",
+        reason: errorMessage(error),
+      };
+    }
+    attempts.push(recordAttempt(deps, attempt));
+  }
+  return {
+    attempted: candidates.length,
+    discoveryFailed: discovery.failures.length,
+    discoveryFailures: discovery.failures,
+    failed:
+      attempts.filter((attempt) => attempt.outcome === "failed").length +
+      discovery.failures.length,
+    killed: attempts.filter((attempt) => attempt.outcome === "killed").length,
+    skipped: attempts.filter((attempt) => attempt.outcome === "skipped").length,
+    attempts,
+  };
+}

package/node_modules/@llblab/pi-actors/lib/runs-process.ts

@@ -0,0 +1,174 @@
+/**
+ * Async run process identity helpers.
+ * Owns: cross-platform liveness and stable runner process identity proofs.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { platform } from "node:os";
+import { posix, win32 } from "node:path";
+
+export interface RunProcessIdentity {
+  command: string;
+  cwd?: string;
+  platform: NodeJS.Platform;
+  start_time: string;
+}
+
+export type RunProcessIdentityStatus =
+  | "valid"
+  | "dead_pid"
+  | "owner_mismatch"
+  | "unsupported_proof";
+
+export interface RunProcessIdentityResult {
+  status: RunProcessIdentityStatus;
+  valid: boolean;
+}
+
+type ProcessIdentityReader = (
+  pid: number,
+  runtimePlatform: NodeJS.Platform,
+) => RunProcessIdentity | undefined;
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readLinuxIdentity(pid: number): RunProcessIdentity | undefined {
+  if (!existsSync(`/proc/${pid}`)) return undefined;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const close = stat.lastIndexOf(")");
+    const fields = stat.slice(close + 2).trim().split(/\s+/);
+    const startTime = fields[19];
+    if (!startTime) return undefined;
+    return {
+      command: readFileSync(`/proc/${pid}/cmdline`, "utf8").replaceAll("\0", " ").trim(),
+      cwd: readlinkSync(`/proc/${pid}/cwd`),
+      platform: "linux",
+      start_time: startTime,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readDarwinIdentity(pid: number): RunProcessIdentity | undefined {
+  const result = spawnSync(
+    "ps",
+    ["-p", String(pid), "-o", "lstart=", "-o", "command="],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) return undefined;
+  const match = result.stdout.trim().match(/^(.{24})\s+(.+)$/s);
+  if (!match) return undefined;
+  return {
+    command: match[2].trim(),
+    platform: "darwin",
+    start_time: match[1].trim(),
+  };
+}
+
+function readWindowsIdentity(pid: number): RunProcessIdentity | undefined {
+  const command = [
+    `$p = Get-CimInstance Win32_Process -Filter \"ProcessId = ${pid}\";`,
+    "if ($null -eq $p) { exit 3 };",
+    "$p | Select-Object CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress",
+  ].join(" ");
+  const result = spawnSync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", command],
+    { encoding: "utf8", windowsHide: true },
+  );
+  if (result.status !== 0) return undefined;
+  try {
+    const value = JSON.parse(result.stdout) as Record<string, unknown>;
+    if (typeof value.CreationDate !== "string") return undefined;
+    const executable = typeof value.ExecutablePath === "string" ? value.ExecutablePath : "";
+    const commandLine = typeof value.CommandLine === "string" ? value.CommandLine : "";
+    return {
+      command: `${executable}\n${commandLine}`.trim(),
+      platform: "win32",
+      start_time: value.CreationDate,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readProcessIdentity(
+  pid: number,
+  runtimePlatform: NodeJS.Platform = platform(),
+): RunProcessIdentity | undefined {
+  if (runtimePlatform === "linux") return readLinuxIdentity(pid);
+  if (runtimePlatform === "darwin") return readDarwinIdentity(pid);
+  if (runtimePlatform === "win32") return readWindowsIdentity(pid);
+  return undefined;
+}
+
+export function captureRunProcessIdentity(
+  pid: number,
+  cwd: string,
+  stateDir: string,
+  runnerPath: string,
+  runtimePlatform: NodeJS.Platform = platform(),
+  reader: ProcessIdentityReader = readProcessIdentity,
+): RunProcessIdentity | undefined {
+  const identity = reader(pid, runtimePlatform);
+  if (!identity) return undefined;
+  if (!identity.command.includes(runnerPath) || !identity.command.includes(stateDir)) {
+    return undefined;
+  }
+  const pathApi = runtimePlatform === "win32" ? win32 : posix;
+  const resolvedCwd = pathApi.resolve(cwd);
+  const canonicalCwd = runtimePlatform === platform() && existsSync(resolvedCwd)
+    ? realpathSync.native(resolvedCwd)
+    : resolvedCwd;
+  const expectedCwd =
+    runtimePlatform === "win32" ? canonicalCwd.toLowerCase() : canonicalCwd;
+  const actualCwd =
+    runtimePlatform === "win32" && identity.cwd
+      ? identity.cwd.toLowerCase()
+      : identity.cwd;
+  if (actualCwd && actualCwd !== expectedCwd) return undefined;
+  return identity;
+}
+
+export function verifyRunProcessIdentity(
+  pid: number,
+  expected: RunProcessIdentity | undefined,
+  runtimePlatform: NodeJS.Platform = platform(),
+  reader: ProcessIdentityReader = readProcessIdentity,
+  alive: (pid: number) => boolean = isAlive,
+): RunProcessIdentityResult {
+  if (!alive(pid)) return { status: "dead_pid", valid: false };
+  if (!expected || expected.platform !== runtimePlatform) {
+    return { status: "unsupported_proof", valid: false };
+  }
+  const current = reader(pid, runtimePlatform);
+  if (!current) return { status: "unsupported_proof", valid: false };
+  const valid =
+    current.start_time === expected.start_time &&
+    current.command === expected.command &&
+    current.cwd === expected.cwd;
+  return { status: valid ? "valid" : "owner_mismatch", valid };
+}
+
+export function isWithinRunnerIdentityGrace(
+  meta: Record<string, unknown>,
+  graceMs: number,
+): boolean {
+  const createdAt =
+    typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
+  return (
+    Number.isFinite(createdAt) &&
+    Date.now() - createdAt >= 0 &&
+    Date.now() - createdAt <= graceMs
+  );
+}

package/node_modules/@llblab/pi-actors/lib/runs-retention.ts

@@ -0,0 +1,140 @@
+/**
+ * Async run retention operations.
+ * Owns: terminal-run archive and prune filesystem behavior.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } from "./file-state.ts";
+import * as Limits from "./limits.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
+import {
+  resolveArtifactManifest,
+  type RunArtifactDeclaration,
+} from "./runs-artifacts.ts";
+import { safeRunId } from "./runs-identity.ts";
+import { assertOwnedRunStateDirectory } from "./runs-ownership.ts";
+
+export type RunRetentionAction = "archive" | "prune";
+export type RunRetentionOutcome = "queued" | "handled" | "failed";
+
+export function appendRunRetentionEvidence(
+  status: Record<string, unknown>,
+  action: RunRetentionAction,
+  outcome: RunRetentionOutcome,
+  options: { error?: string; id?: string; result?: Record<string, unknown> } = {},
+): string {
+  const stateDir = String(status.state_dir);
+  const path = join(dirname(stateDir), "retention.jsonl");
+  const id = options.id ?? randomUUID();
+  const record = {
+    action,
+    ...(options.error ? { error: options.error } : {}),
+    id,
+    outcome,
+    ...(options.result ? { result: options.result } : {}),
+    run: String(status.run ?? basename(stateDir)),
+    ...(typeof status.run_instance_id === "string" ? { run_instance_id: status.run_instance_id } : {}),
+    ts: new Date().toISOString(),
+  };
+  const release = acquireFileMutationLock(path);
+  try {
+    const records = [...readJsonlFileResilient<Record<string, unknown>>(path).records, record]
+      .slice(-Limits.RUN_RETENTION_MAX_RECORDS);
+    let content = encodeRecords(records);
+    while (records.length && Buffer.byteLength(content) > Limits.RUN_RETENTION_MAX_BYTES) {
+      records.shift();
+      content = encodeRecords(records);
+    }
+    if (!records.includes(record)) throw new Error("Run retention record exceeds journal byte limit");
+    writeTextAtomic(path, content);
+  } finally { release(); }
+  return id;
+}
+
+function encodeRecords(records: Record<string, unknown>[]): string {
+  return records.length ? `${records.map((value) => JSON.stringify(value)).join("\n")}\n` : "";
+}
+
+function retainedArtifactFilename(name: string, path: string): string {
+  const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
+  const identity = createHash("sha256")
+    .update(`${name}\0${path}`)
+    .digest("hex")
+    .slice(0, 8);
+  return `${readableName}-${identity}--${basename(path)}`;
+}
+
+function archivePathFor(run: string, stateDir: string): string {
+  const archiveRoot = join(dirname(stateDir), "archived");
+  mkdirSync(archiveRoot, { recursive: true });
+  return join(
+    archiveRoot,
+    `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`,
+  );
+}
+
+export function archiveTerminalRun(
+  status: Record<string, unknown>,
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  assertOwnedRunStateDirectory(stateDir, run);
+  const archiveDir = archivePathFor(run, stateDir);
+  renameSync(stateDir, archiveDir);
+  mkdirSync(stateDir, { recursive: true });
+  const tombstone = {
+    archived: true,
+    archive_dir: archiveDir,
+    original_state_dir: stateDir,
+    run,
+    status: status.status,
+    ts: new Date().toISOString(),
+  };
+  writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
+  return tombstone;
+}
+
+export function pruneTerminalRun(
+  status: Record<string, unknown>,
+  options: { preserveArtifacts?: boolean } = {},
+  deps: { copyArtifact?: typeof cpSync } = {},
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  assertOwnedRunStateDirectory(stateDir, run);
+  const manifest = resolveArtifactManifest(
+    status.artifacts as Record<string, RunArtifactDeclaration> | undefined,
+  );
+  const preserved: Record<string, string> = {};
+  if (options.preserveArtifacts && manifest) {
+    const preserveRoot = join(
+      dirname(stateDir),
+      "preserved-artifacts",
+      safeRunId(run),
+    );
+    mkdirSync(preserveRoot, { recursive: true });
+    for (const [name, artifact] of Object.entries(manifest)) {
+      if (!artifact.exists) continue;
+      const target = join(
+        preserveRoot,
+        retainedArtifactFilename(name, artifact.path),
+      );
+      (deps.copyArtifact ?? cpSync)(artifact.path, target, {
+        force: true,
+        preserveTimestamps: true,
+      });
+      preserved[name] = target;
+    }
+  }
+  rmSync(stateDir, { recursive: true, force: true });
+  return {
+    pruned: true,
+    preserved_artifacts: preserved,
+    run,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}