@llblab/pi-actors 0.22.4 → 0.23.0

package/lib/async-runs.ts

@@ -5,7 +5,7 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   closeSync,
   constants,
@@ -14,7 +14,9 @@ import {
   openSync,
   readdirSync,
   readFileSync,
+  cpSync,
   readlinkSync,
+  renameSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -65,7 +67,7 @@ export interface AsyncRunStartParams {
   timeout?: number | string;
   delay?: number | string;
   output?: string;
-  artifacts?: Record<string, string>;
+  artifacts?: Record<string, RunArtifactDeclaration>;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
   retire_when?: "children_terminal";
   retry?: number | string;
@@ -121,7 +123,7 @@ export interface AsyncRunMeta {
   tool?: string;
   template: CommandTemplateValue;
   values: Record<string, unknown>;
-  artifacts?: Record<string, string>;
+  artifacts?: Record<string, RunArtifactDeclaration>;
   control?: AsyncRunControlEndpoint;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
   recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
@@ -160,23 +162,93 @@ function safeRunId(value: string | undefined): string {
   return run;
 }
 
+export type RunArtifactDeclaration =
+  | string
+  | { path: string; kind?: string; media_type?: string; required?: boolean };
+
+export interface RunArtifactManifestEntry {
+  exists: boolean;
+  kind?: string;
+  media_type?: string;
+  path: string;
+  required?: boolean;
+  sha256?: string;
+  size?: number;
+}
+
 function resolveArtifactPaths(
-  artifacts: Record<string, string> | undefined,
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
   values: Record<string, unknown>,
-): Record<string, string> | undefined {
+): Record<string, RunArtifactDeclaration> | undefined {
   if (!artifacts) return undefined;
-  const resolved: Record<string, string> = {};
+  const resolved: Record<string, RunArtifactDeclaration> = {};
   for (const [key, value] of Object.entries(artifacts)) {
     if (!key.trim()) continue;
-    resolved[key] = substituteCommandTemplateToken(
-      value,
-      values,
-      `recipe artifacts.${key}`,
-    );
+    if (typeof value === "string") {
+      resolved[key] = substituteCommandTemplateToken(
+        value,
+        values,
+        `recipe artifacts.${key}`,
+      );
+    } else if (
+      value &&
+      typeof value === "object" &&
+      typeof value.path === "string"
+    ) {
+      resolved[key] = {
+        ...value,
+        path: substituteCommandTemplateToken(
+          value.path,
+          values,
+          `recipe artifacts.${key}.path`,
+        ),
+      };
+    }
   }
   return Object.keys(resolved).length > 0 ? resolved : undefined;
 }
 
+export function resolveArtifactManifest(
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
+): Record<string, RunArtifactManifestEntry> | undefined {
+  if (!artifacts) return undefined;
+  const manifest: Record<string, RunArtifactManifestEntry> = {};
+  for (const [name, artifact] of Object.entries(artifacts)) {
+    const declaration =
+      typeof artifact === "string" ? { path: artifact } : artifact;
+    if (!declaration?.path) continue;
+    try {
+      const content = readFileSync(declaration.path);
+      manifest[name] = {
+        exists: true,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+        sha256: createHash("sha256").update(content).digest("hex"),
+        size: content.byteLength,
+      };
+    } catch {
+      manifest[name] = {
+        exists: false,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+      };
+    }
+  }
+  return Object.keys(manifest).length > 0 ? manifest : undefined;
+}
+
 function resolveRunTemplate(params: AsyncRunStartParams): {
   template: CommandTemplateValue;
 } {
@@ -426,7 +498,11 @@ export function startRun(
         ? RecipeReferences.buildRecipeContextRecords(recipeFile)
         : undefined;
     if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
-      RecipeUsage.recordRecipeLaunch(recipeFile);
+      RecipeUsage.recordRecipeLaunch(
+        recipeFile,
+        new Date(),
+        startParams.launch_source === "tool" ? "tool" : "spawn",
+      );
     }
     const outFd = openSync(stdout, "a");
     const errFd = openSync(stderr, "a");
@@ -611,6 +687,16 @@ export function getRunStatus(runOrDir: string): Record<string, unknown> {
   };
 }
 
+export interface RunStateIndexEntry {
+  ownerId?: string;
+  recipe?: string;
+  run: string;
+  state_dir: string;
+  status: AsyncRunStatus;
+  tool?: string;
+  updated_at?: string;
+}
+
 function matchesStatusFilter(
   status: unknown,
   filter: string | undefined,
@@ -621,30 +707,125 @@ function matchesStatusFilter(
   return status === filter;
 }
 
+export function listRunStateDirs(
+  stateRoot = DEFAULT_STATE_ROOT,
+  depth = 0,
+  seen = new Set<string>(),
+): string[] {
+  if (!existsSync(stateRoot) || seen.has(resolve(stateRoot))) return [];
+  seen.add(resolve(stateRoot));
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(stateRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(stateRoot, entry.name);
+    if (existsSync(join(child, "run.json"))) result.push(child);
+    if (depth + 1 < 8) result.push(...listRunStateDirs(child, depth + 1, seen));
+  }
+  return result;
+}
+
+function runIndexPath(stateRoot: string): string {
+  return join(stateRoot, "index.json");
+}
+
+function indexEntryFromStatus(
+  status: Record<string, unknown>,
+): RunStateIndexEntry {
+  const progress =
+    status.progress && typeof status.progress === "object"
+      ? (status.progress as Record<string, unknown>)
+      : {};
+  return {
+    ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+    ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+    run: String(status.run),
+    state_dir: String(status.state_dir),
+    status: status.status as AsyncRunStatus,
+    ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+    updated_at:
+      typeof progress.updatedAt === "string"
+        ? progress.updatedAt
+        : typeof status.createdAt === "string"
+          ? status.createdAt
+          : new Date(0).toISOString(),
+  };
+}
+
+export function rebuildRunStateIndex(
+  stateRoot = DEFAULT_STATE_ROOT,
+): RunStateIndexEntry[] {
+  mkdirSync(stateRoot, { recursive: true });
+  const entries = listRunStateDirs(stateRoot)
+    .flatMap((stateDir) => {
+      try {
+        return [indexEntryFromStatus(getRunStatus(stateDir))];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+  writeJsonAtomic(runIndexPath(stateRoot), {
+    entries,
+    rebuilt_at: new Date().toISOString(),
+  });
+  return entries;
+}
+
+export function readRunStateIndex(
+  stateRoot = DEFAULT_STATE_ROOT,
+): RunStateIndexEntry[] | undefined {
+  const index = readJson(runIndexPath(stateRoot));
+  if (!index || typeof index !== "object") return undefined;
+  const entries = (index as Record<string, unknown>).entries;
+  if (!Array.isArray(entries)) return undefined;
+  const valid = entries.filter((entry): entry is RunStateIndexEntry => {
+    const record =
+      entry && typeof entry === "object"
+        ? (entry as Record<string, unknown>)
+        : {};
+    return (
+      typeof record.run === "string" &&
+      typeof record.state_dir === "string" &&
+      typeof record.status === "string"
+    );
+  });
+  if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+    return undefined;
+  return valid;
+}
+
 export function listRuns(
   stateRoot = DEFAULT_STATE_ROOT,
   statusFilter?: string,
 ): Array<Record<string, unknown>> {
   if (!existsSync(stateRoot)) return [];
-  const runs: Array<Record<string, unknown>> = [];
-  for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    try {
-      const stateDir = join(stateRoot, entry.name);
-      const status = getRunStatus(stateDir);
-      if (!matchesStatusFilter(status.status, statusFilter)) continue;
-      runs.push({
-        run: status.run,
-        state_dir: stateDir,
-        status: status.status,
-        ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
-        ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
-      });
-    } catch {
-      // Ignore malformed run dirs.
-    }
+  const indexed = readRunStateIndex(stateRoot);
+  if (indexed) {
+    return indexed
+      .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+      .map((entry) => ({
+        run: entry.run,
+        state_dir: entry.state_dir,
+        status: entry.status,
+        ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.recipe ? { recipe: entry.recipe } : {}),
+      }));
   }
-  return runs;
+  return rebuildRunStateIndex(stateRoot)
+    .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+    .map((entry) => ({
+      run: entry.run,
+      state_dir: entry.state_dir,
+      status: entry.status,
+      ...(entry.tool ? { tool: entry.tool } : {}),
+      ...(entry.recipe ? { recipe: entry.recipe } : {}),
+    }));
 }
 
 export function tailRun(runOrDir: string, lines = 40): string {
@@ -879,12 +1060,19 @@ export function appendRunOutboxEvent(
   const run = String(status.run ?? runOrDir);
   const type = event.type || event.event || "run.message";
   const to = event.to || "coordinator";
+  const metadata = event.metadata ?? {};
+  const requiresResponse = metadata.requires_response === true;
   const payload = {
     ...(event.body !== undefined ? { body: event.body } : {}),
     ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
     ...(event.data !== undefined ? { data: event.data } : {}),
     delivery: normalizeRunOutboxDelivery(
-      event.delivery ?? (to === "coordinator" ? "followup" : "log"),
+      event.delivery ??
+        (requiresResponse
+          ? "followup"
+          : to === "coordinator"
+            ? "notify"
+            : "log"),
     ),
     event: type,
     from: event.from || `run:${run}`,
@@ -1242,6 +1430,77 @@ export function cancelRun(runOrDir: string): Record<string, unknown> {
     : result;
 }
 
+function assertTerminalRun(runOrDir: string): Record<string, unknown> {
+  const status = getRunStatus(runOrDir);
+  if (status.status === "running") {
+    throw new Error("Only terminal runs can be archived or pruned.");
+  }
+  return status;
+}
+
+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 archiveRun(runOrDir: string): Record<string, unknown> {
+  const status = assertTerminalRun(runOrDir);
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  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 pruneRun(
+  runOrDir: string,
+  options: { preserveArtifacts?: boolean } = {},
+): Record<string, unknown> {
+  const status = assertTerminalRun(runOrDir);
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  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, basename(artifact.path));
+      cpSync(artifact.path, target, { force: true });
+      preserved[name] = target;
+    }
+  }
+  rmSync(stateDir, { recursive: true, force: true });
+  return {
+    pruned: true,
+    preserved_artifacts: preserved,
+    run,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}
+
 export function killRun(runOrDir: string): Record<string, unknown> {
   const result = stopRun(runOrDir, "SIGKILL", "run.kill");
   return Object.hasOwn(result, "stopped")

package/lib/command-templates.ts

@@ -193,7 +193,7 @@ function getLeafCommandTemplateWarnings(
       ? "shell command strings"
       : "shell scripts";
     warnings.push(
-      `${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting.`,
+      `${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting. Mitigation: keep scripts local, reviewed, and parameterized with explicit placeholders.`,
     );
   }
   if (
@@ -201,7 +201,7 @@ function getLeafCommandTemplateWarnings(
     hasAnyFlag(args, ["-e", "--eval"])
   ) {
     warnings.push(
-      `${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`,
+      `${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`,
     );
   }
   if (
@@ -209,7 +209,7 @@ function getLeafCommandTemplateWarnings(
     hasAnyFlag(args, ["-c", "-e"])
   ) {
     warnings.push(
-      `${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`,
+      `${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed. Mitigation: prefer a checked-in script file or keep eval input fixed and reviewed.`,
     );
   }
   if (
@@ -218,12 +218,12 @@ function getLeafCommandTemplateWarnings(
       hasRiskyPathArg(args))
   ) {
     warnings.push(
-      `${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`,
+      `${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands. Mitigation: constrain path placeholders and consider dry-run or explicit confirmation.`,
     );
   }
   if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
     warnings.push(
-      `${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`,
+      `${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands. Mitigation: constrain path placeholders and prefer narrow source/destination paths.`,
     );
   }
   return warnings;

package/lib/limits.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared output and preview size limits.
+ * Zones: output governance, actor-message previews, inspect defaults
+ */
+
+export const DEFAULT_INSPECT_LINES = 40;
+export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
+export const TOOL_OUTPUT_MAX_LINES = 2_000;
+export const COMPACT_PREVIEW_CHARS = 160;
+export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
+export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
+export const DOCTOR_ACTION_PREVIEW_CHARS = 72;

package/lib/observability.ts

@@ -144,7 +144,7 @@ function getUpdatedAt(status: Record<string, unknown>): string | undefined {
       : undefined;
 }
 
-function listRunStateDirs(
+function scanRunStateDirs(
   stateRoot: string,
   depth = 0,
   seen = new Set<string>(),
@@ -163,7 +163,7 @@ function listRunStateDirs(
     const child = join(stateRoot, entry.name);
     if (existsSync(join(child, "run.json"))) result.push(child);
     if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
-      result.push(...listRunStateDirs(child, depth + 1, seen));
+      result.push(...scanRunStateDirs(child, depth + 1, seen));
   }
   return result;
 }
@@ -226,7 +226,10 @@ export function summarizeRuns(
       total: 0,
     };
   }
-  const runs = listRunStateDirs(stateRoot)
+  const runs = (
+    AsyncRuns.readRunStateIndex(stateRoot)?.map((entry) => entry.state_dir) ??
+    scanRunStateDirs(stateRoot)
+  )
     .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
@@ -331,7 +334,10 @@ function summarizeRunsWithoutSubagents(
       runs: [],
       total: 0,
     };
-  const runs = listRunStateDirs(stateRoot)
+  const runs = (
+    AsyncRuns.readRunStateIndex(stateRoot)?.map((entry) => entry.state_dir) ??
+    scanRunStateDirs(stateRoot)
+  )
     .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)

package/lib/output.ts

@@ -8,6 +8,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { sanitizeFilePart } from "./identity.ts";
+import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
 
 export interface FormattedOutput {
@@ -16,9 +17,6 @@ export interface FormattedOutput {
   fullOutputPath?: string;
 }
 
-const MAX_OUTPUT_BYTES = 50 * 1024;
-const MAX_OUTPUT_LINES = 2_000;
-
 export function writeFullOutput(
   toolName: string,
   stream: string,
@@ -70,10 +68,10 @@ export function truncateTailContent(content: string): {
   const lines = content.split("\n");
   const totalLines = lines.length;
   let output =
-    totalLines > MAX_OUTPUT_LINES
-      ? lines.slice(-MAX_OUTPUT_LINES).join("\n")
+    totalLines > Limits.TOOL_OUTPUT_MAX_LINES
+      ? lines.slice(-Limits.TOOL_OUTPUT_MAX_LINES).join("\n")
       : content;
-  output = trimToTailBytes(output, MAX_OUTPUT_BYTES);
+  output = trimToTailBytes(output, Limits.TOOL_OUTPUT_MAX_BYTES);
   const outputBytes = byteLength(output);
   const outputLines = output ? output.split("\n").length : 0;
   return {

package/lib/recipe-discovery.ts

@@ -493,6 +493,7 @@ export function summarizeDiscovery(
         disabled: entry.disabled,
         invalid: entry.invalid,
         shadows: entry.shadows,
+        ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
         ...(recipeUsage(entry.config)
           ? { usage: recipeUsage(entry.config) }
           : {}),

package/lib/recipe-references.ts

@@ -26,9 +26,21 @@ export interface TemplateRecipeImportBinding {
 
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 
+export type TemplateRecipeMailboxEntry =
+  | string
+  | {
+      type: string;
+      body_schema?: unknown;
+      ack?: boolean | string;
+      idempotency?: string;
+      requires_response?: boolean;
+      level?: string;
+      summary?: string;
+    };
+
 export interface TemplateRecipeMailbox {
-  accepts?: string[];
-  emits?: string[];
+  accepts?: TemplateRecipeMailboxEntry[];
+  emits?: TemplateRecipeMailboxEntry[];
 }
 
 export interface TemplateRecipeDefinition {
@@ -834,14 +846,18 @@ export function readResolvedRecipeConfig(
             ...(Array.isArray(substituted.mailbox.accepts)
               ? {
                   accepts: substituted.mailbox.accepts.filter(
-                    (value): value is string => typeof value === "string",
+                    (value): value is TemplateRecipeMailboxEntry =>
+                      typeof value === "string" ||
+                      (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),
             ...(Array.isArray(substituted.mailbox.emits)
               ? {
                   emits: substituted.mailbox.emits.filter(
-                    (value): value is string => typeof value === "string",
+                    (value): value is TemplateRecipeMailboxEntry =>
+                      typeof value === "string" ||
+                      (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),

package/lib/recipe-usage.ts

@@ -11,9 +11,14 @@ import { writeJsonAtomic } from "./file-state.ts";
 
 interface RecipeUsageRecord {
   calls?: number;
-  last_called?: string;
+  direct_calls?: number;
   fingerprint?: string;
+  last_called?: string;
+  launch_kind?: string;
   reset_at?: string;
+  reset_reason?: string;
+  spawn_calls?: number;
+  tool_calls?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -40,23 +45,45 @@ function getRecipeFingerprint(raw: Record<string, unknown>): string {
   return createHash("sha256").update(stableStringify(content)).digest("hex");
 }
 
-export function recordRecipeLaunch(path: string, now = new Date()): boolean {
+export type RecipeLaunchKind = "direct" | "spawn" | "tool";
+
+function launchCounterKey(
+  kind: RecipeLaunchKind,
+): "direct_calls" | "spawn_calls" | "tool_calls" {
+  return `${kind}_calls` as "direct_calls" | "spawn_calls" | "tool_calls";
+}
+
+export function recordRecipeLaunch(
+  path: string,
+  now = new Date(),
+  kind: RecipeLaunchKind = "direct",
+): boolean {
   if (!existsSync(path)) return false;
   try {
     const raw = JSON.parse(readFileSync(path, "utf8"));
     if (!isRecord(raw)) return false;
     const usage: RecipeUsageRecord = isRecord(raw.usage) ? raw.usage : {};
     const fingerprint = getRecipeFingerprint(raw);
-    const changed = typeof usage.fingerprint === "string" && usage.fingerprint !== fingerprint;
+    const changed =
+      typeof usage.fingerprint === "string" &&
+      usage.fingerprint !== fingerprint;
     const nowIso = now.toISOString();
+    const counterKey = launchCounterKey(kind);
     writeJsonAtomic(path, {
       ...raw,
       usage: {
         ...usage,
         calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+        [counterKey]: (changed ? 0 : normalizeCalls(usage[counterKey])) + 1,
         last_called: nowIso,
+        launch_kind: kind,
         fingerprint,
-        ...(changed ? { reset_at: nowIso } : {}),
+        ...(changed
+          ? {
+              reset_at: nowIso,
+              reset_reason: "recipe content fingerprint changed",
+            }
+          : {}),
       },
     });
     return true;