@llblab/pi-actors 0.41.0 → 0.42.0

package/dist/lib/inspector.d.ts

@@ -55,10 +55,19 @@ export interface ActorInspectorPreviewReadOptions {
 }
 export interface ActorInspectorRunItem {
     run: string;
+    runInstanceId?: string;
     status: string;
     updatedAt?: string;
 }
 export declare function readActorInspectorRuns(stateRoot: string, ownerId: string): ActorInspectorRunItem[];
+export interface ActorInspectorRecipeView {
+    composition: Array<Record<string, unknown>>;
+    definition?: Record<string, unknown>;
+    diagnostics: string[];
+    identity: Record<string, unknown>;
+    launch: Record<string, unknown>;
+}
+export declare function readActorInspectorRecipe(stateDir: string): ActorInspectorRecipeView;
 export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
     commandId: string;
     diagnostics: string[];

package/dist/lib/inspector.js

@@ -19,10 +19,14 @@ export function readActorInspectorRuns(stateRoot, ownerId) {
             const stateDir = path.join(stateRoot, entry.name);
             if (!matchesOwner(stateDir, ownerId))
                 return [];
+            const runMeta = readJsonFileResilient(path.join(stateDir, "run.json"), {}).value;
             const progress = readJsonFileResilient(path.join(stateDir, "progress.json"), {}).value;
             const result = readJsonFileResilient(path.join(stateDir, "result.json"), {}).value;
             return [{
                     run: entry.name,
+                    ...(typeof runMeta.run_instance_id === "string"
+                        ? { runInstanceId: runMeta.run_instance_id }
+                        : {}),
                     status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
                     ...(typeof progress.updatedAt === "string"
                         ? { updatedAt: progress.updatedAt }
@@ -31,7 +35,10 @@ export function readActorInspectorRuns(stateRoot, ownerId) {
                             : {}),
                 }];
         })
-            .sort((left, right) => String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")));
+            .sort((left, right) => {
+            const recency = String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? ""));
+            return recency || right.run.localeCompare(left.run);
+        });
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -39,6 +46,50 @@ export function readActorInspectorRuns(stateRoot, ownerId) {
         return [];
     }
 }
+export function readActorInspectorRecipe(stateDir) {
+    const result = readJsonFileResilient(path.join(stateDir, "run.json"), {});
+    const meta = result.value;
+    const contexts = Array.isArray(meta.recipe_context_records)
+        ? meta.recipe_context_records
+            .filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)))
+        : [];
+    const primary = contexts.find((entry) => entry.depth === 0) ?? contexts[0];
+    const definition = primary?.recipe && typeof primary.recipe === "object" &&
+        !Array.isArray(primary.recipe)
+        ? primary.recipe
+        : undefined;
+    const redacted = (value) => SessionEvidence.redactSessionEvidenceValue(value);
+    const redactedRecord = (value) => redacted(Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)));
+    return {
+        composition: contexts.map((entry) => redactedRecord({
+            ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
+            depth: entry.depth,
+            file: entry.file,
+            import_path: entry.import_path,
+            name: entry.name,
+        })),
+        ...(definition
+            ? { definition: redactedRecord(definition) }
+            : {}),
+        diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
+        identity: redactedRecord({
+            run: meta.run,
+            recipe: meta.recipe,
+            recipe_file: meta.recipe_file,
+            launch_source: meta.launch_source,
+        }),
+        launch: redactedRecord({
+            cwd: meta.cwd,
+            template: meta.template,
+            values: meta.values,
+            model_policy: meta.model_policy,
+            mailbox: meta.mailbox,
+            artifacts: meta.artifacts,
+            notification_policy: meta.notification_policy,
+            retire_when: meta.retire_when,
+        }),
+    };
+}
 function ownedSessionPath(stateDir, sessionFile) {
     if (path.isAbsolute(sessionFile))
         return undefined;

package/dist/lib/observability.d.ts

@@ -3,6 +3,7 @@
  * Zones: async runtime, ambient UI, diagnostics
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
+import { type FSWatcher } from "node:fs";
 import * as AsyncRuns from "./async-runs.ts";
 export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
 export type RunOutboxDelivery = "log" | "notify" | "followup";
@@ -16,6 +17,7 @@ export interface RunObservation {
     artifacts?: Record<string, string>;
     launchSource?: AsyncRuns.AsyncRunLaunchSource;
     modelPolicy?: Record<string, unknown>;
+    notificationPolicy?: "normal" | "silent";
     recipeFile?: string;
     terminalHandled?: boolean;
     retireWhen?: string;
@@ -58,9 +60,19 @@ export interface RunUiNotificationSink {
     }): void;
 }
 export declare function createRunUiObservationState(): RunUiObservationState;
-export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string): RunUiSnapshot;
+export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
+    includeOutbox?: boolean;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
-export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink): void;
+export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink, inFlight?: Set<string>): void;
+export declare function reconcileRunTerminalNotifications(input: {
+    inFlight?: Set<string>;
+    ownerId: string;
+    sink: RunUiNotificationSink;
+    state: RunUiObservationState;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function deliverRunOutboxNotifications(events: RunOutboxEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
     activeSubagents: number;
@@ -76,14 +88,38 @@ export interface RunRetirementExecution {
     run: string;
     stateDir: string;
 }
+export type RunStateWatcherDiagnosticCode = "attach_failed" | "error" | "removed" | "rearmed";
+export interface RunStateWatcherDiagnostic {
+    code: RunStateWatcherDiagnosticCode;
+    id: number;
+    message: string;
+    path: string;
+    scope: "root" | "run";
+    ts: string;
+}
 export interface RunStateWatcher {
     close(): void;
+    getDiagnostics(): RunStateWatcherDiagnostic[];
     refresh(): void;
 }
 export declare function createRunStateWatcher(input: {
-    stateRoot?: string;
+    exists?: (path: string) => boolean;
+    listDirectories?: (path: string) => string[];
     onChange: () => void;
+    stateRoot?: string;
+    watchPath?: (path: string, onChange: () => void) => FSWatcher;
 }): RunStateWatcher;
+export interface RunTerminalReconciliationLoop {
+    close(): void;
+    reconcileNow(): void;
+    start(): void;
+}
+export declare function createRunTerminalReconciliationLoop(input: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+    reconcile: () => void;
+    refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop;
 export interface RunRetirementExecutorOptions {
     attempted?: Set<string>;
     cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;

package/dist/lib/observability.js

@@ -16,11 +16,13 @@ export function createRunUiObservationState() {
         outboxEventIds: new Map(),
     };
 }
-export function readRunUiSnapshot(state, ownerId) {
-    const summary = summarizeRuns(undefined, ownerId);
+export function readRunUiSnapshot(state, ownerId, options = {}) {
+    const summary = summarizeRuns(options.stateRoot, ownerId);
     const status = renderRunStatus(summary, state.frame++);
     return {
-        outboxEvents: detectRunOutboxEvents(state.eventLines, summary, state.outboxEventIds),
+        outboxEvents: options.includeOutbox === false
+            ? []
+            : detectRunOutboxEvents(state.eventLines, summary, state.outboxEventIds),
         status,
         summary,
         transitions: detectRunTransitions(state.observed, summary),
@@ -29,25 +31,43 @@ export function readRunUiSnapshot(state, ownerId) {
 export function pruneRunUiObservationState(state, snapshot) {
     pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.outboxEventIds);
 }
-export function deliverRunTransitionNotifications(transitions, sink) {
+export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
         if (!shouldNotifyRunTransition(transition))
             continue;
-        const text = formatRunTransitionMessage(transition);
-        sink.notify(text, getRunTransitionNotificationType(transition));
-        if (!shouldSendRunTransitionFollowUp(transition))
+        const key = transition.stateDir ?? transition.run;
+        if (inFlight.has(key))
             continue;
-        sink.sendFollowUp({
-            customType: "pi-actors-run",
-            content: text,
-            display: true,
-            details: transition,
-        });
-        if (transition.stateDir) {
-            AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+        inFlight.add(key);
+        try {
+            const text = formatRunTransitionMessage(transition);
+            sink.notify(text, getRunTransitionNotificationType(transition));
+            if (!shouldSendRunTransitionFollowUp(transition))
+                continue;
+            sink.sendFollowUp({
+                customType: "pi-actors-run",
+                content: text,
+                display: true,
+                details: transition,
+            });
+            if (transition.stateDir) {
+                AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+            }
+        }
+        finally {
+            inFlight.delete(key);
         }
     }
 }
+export function reconcileRunTerminalNotifications(input) {
+    const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
+        includeOutbox: false,
+        stateRoot: input.stateRoot,
+    });
+    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
+    pruneRunUiObservationState(input.state, snapshot);
+    return snapshot;
+}
 export function deliverRunOutboxNotifications(events, sink) {
     for (const event of events) {
         if (!shouldNotifyRunOutboxEvent(event))
@@ -64,10 +84,58 @@ export function deliverRunOutboxNotifications(events, sink) {
         });
     }
 }
+const RUN_WATCHER_DIAGNOSTIC_LIMIT = 32;
 export function createRunStateWatcher(input) {
     const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+    const pathExists = input.exists ?? existsSync;
+    const listDirectories = input.listDirectories ??
+        ((path) => readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(path, entry.name)));
+    const watchPath = input.watchPath ?? ((path, onChange) => watch(path, onChange));
+    let diagnosticId = 0;
+    let rootDegraded = false;
     let stateRootWatcher;
+    const degradedRunDirs = new Set();
+    const diagnostics = [];
+    const lastDiagnosticSignatures = new Map();
     const runDirWatchers = new Map();
+    const record = (code, scope, path, error) => {
+        const detail = error instanceof Error ? `: ${error.message}` : "";
+        const signature = `${code}${detail}`;
+        const signatureKey = `${scope}:${path}`;
+        if (lastDiagnosticSignatures.get(signatureKey) === signature)
+            return;
+        lastDiagnosticSignatures.set(signatureKey, signature);
+        const recovery = code === "rearmed"
+            ? "; terminal watch acceleration restored"
+            : "; terminal reconciliation remains active and watcher rearm will retry";
+        diagnostics.push({
+            code,
+            id: ++diagnosticId,
+            message: `Run-state ${scope} watcher ${code.replace("_", " ")} for ${path}${detail}${recovery}`,
+            path,
+            scope,
+            ts: new Date().toISOString(),
+        });
+        if (diagnostics.length > RUN_WATCHER_DIAGNOSTIC_LIMIT)
+            diagnostics.shift();
+    };
+    const removeRunWatcher = (stateDir, watcher, options = {}) => {
+        if (runDirWatchers.get(stateDir) !== watcher)
+            return;
+        watcher.close();
+        runDirWatchers.delete(stateDir);
+        if (options.degraded === false) {
+            degradedRunDirs.delete(stateDir);
+            lastDiagnosticSignatures.delete(`run:${stateDir}`);
+            return;
+        }
+        degradedRunDirs.add(stateDir);
+        if (options.error)
+            record("error", "run", stateDir, options.error);
+        record("removed", "run", stateDir);
+    };
     const close = () => {
         stateRootWatcher?.close();
         stateRootWatcher = undefined;
@@ -76,42 +144,92 @@ export function createRunStateWatcher(input) {
         runDirWatchers.clear();
     };
     const watchRunDir = (stateDir) => {
-        if (runDirWatchers.has(stateDir) || !existsSync(stateDir))
+        if (runDirWatchers.has(stateDir) || !pathExists(stateDir))
             return;
         try {
-            const watcher = watch(stateDir, input.onChange);
-            watcher.on("error", () => {
-                watcher.close();
-                runDirWatchers.delete(stateDir);
-            });
+            const watcher = watchPath(stateDir, input.onChange);
+            watcher.on("error", (error) => removeRunWatcher(stateDir, watcher, { error }));
             runDirWatchers.set(stateDir, watcher);
+            if (degradedRunDirs.delete(stateDir))
+                record("rearmed", "run", stateDir);
         }
-        catch {
-            // Watching is best-effort; explicit inspect remains available.
+        catch (error) {
+            degradedRunDirs.add(stateDir);
+            record("attach_failed", "run", stateDir, error);
         }
     };
     function refresh() {
-        if (!existsSync(stateRoot))
+        if (!pathExists(stateRoot))
             return;
         if (!stateRootWatcher) {
             try {
-                stateRootWatcher = watch(stateRoot, input.onChange);
-                stateRootWatcher.on("error", () => {
-                    stateRootWatcher?.close();
+                const watcher = watchPath(stateRoot, input.onChange);
+                stateRootWatcher = watcher;
+                watcher.on("error", (error) => {
+                    if (stateRootWatcher !== watcher)
+                        return;
+                    watcher.close();
                     stateRootWatcher = undefined;
+                    rootDegraded = true;
+                    record("error", "root", stateRoot, error);
+                    record("removed", "root", stateRoot);
                 });
+                if (rootDegraded) {
+                    rootDegraded = false;
+                    record("rearmed", "root", stateRoot);
+                }
             }
-            catch {
-                // Watching is best-effort; explicit inspect remains available.
+            catch (error) {
+                rootDegraded = true;
+                record("attach_failed", "root", stateRoot, error);
             }
         }
-        for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+        let stateDirs;
+        try {
+            stateDirs = listDirectories(stateRoot);
+        }
+        catch (error) {
+            record("attach_failed", "root", stateRoot, error);
+            return;
+        }
+        const present = new Set(stateDirs);
+        for (const [stateDir, watcher] of runDirWatchers) {
+            if (present.has(stateDir) && pathExists(stateDir))
                 continue;
-            watchRunDir(`${stateRoot}/${entry.name}`);
+            removeRunWatcher(stateDir, watcher, { degraded: false });
         }
+        for (const stateDir of stateDirs)
+            watchRunDir(stateDir);
     }
-    return { close, refresh };
+    return {
+        close,
+        getDiagnostics: () => [...diagnostics],
+        refresh,
+    };
+}
+export function createRunTerminalReconciliationLoop(input) {
+    const intervalMs = input.intervalMs ?? 10_000;
+    let interval;
+    const reconcileNow = () => {
+        try {
+            input.refreshWatcher();
+            input.reconcile();
+        }
+        catch (error) {
+            input.onError?.(error);
+        }
+    };
+    const close = () => {
+        if (interval)
+            clearInterval(interval);
+        interval = undefined;
+    };
+    const start = () => {
+        close();
+        interval = setInterval(reconcileNow, intervalMs);
+        interval.unref?.();
+    };
+    return { close, reconcileNow, start };
 }
 const TERMINAL = new Set([
     "done",
@@ -193,6 +311,9 @@ function observeRun(stateDir) {
                 !Array.isArray(status.model_policy)
                 ? { modelPolicy: status.model_policy }
                 : {}),
+            ...(status.notification_policy === "silent"
+                ? { notificationPolicy: "silent" }
+                : {}),
             ...(typeof status.recipe_file === "string"
                 ? { recipeFile: status.recipe_file }
                 : {}),
@@ -497,7 +618,9 @@ export function detectRunTransitions(previous, summary) {
     for (const run of summary.runs) {
         const key = runObservationKey(run);
         const old = previous.get(key);
-        if (!run.terminalHandled && TERMINAL.has(run.status)) {
+        if (run.notificationPolicy !== "silent" &&
+            !run.terminalHandled &&
+            TERMINAL.has(run.status)) {
             transitions.push({
                 from: old ?? "running",
                 run: run.run,
@@ -589,6 +712,11 @@ export function detectRunOutboxEvents(previousLineCounts, summary, seenEventIds
         const key = run.stateDir ?? run.run;
         const records = readOutboxRecords(run);
         const previousCount = previousLineCounts.get(key) ?? 0;
+        if (run.notificationPolicy === "silent") {
+            previousLineCounts.set(key, records.length);
+            seenEventIds.set(key, seenEventIds.get(key) ?? new Set());
+            continue;
+        }
         const start = Math.min(previousCount, records.length);
         const seen = seenEventIds.get(key) ?? new Set();
         for (let index = start; index < records.length; index += 1) {

package/dist/lib/paths.d.ts

@@ -4,6 +4,7 @@
  * Owns agent directory, tools config, recipe root, and actor run state root resolution
  */
 export declare function getAgentDir(env?: Record<string, string | undefined>): string;
+export declare function isAutomaticRecipeReviewEnabled(env?: Record<string, string | undefined>): boolean;
 export interface ExtensionRuntimePaths {
     configPath: string;
     runStateRoot: string;
@@ -12,6 +13,12 @@ export interface ExtensionRuntimePaths {
 export declare function getConfigPath(agentDir?: string): string;
 export declare function getExtensionTmpDir(agentDir?: string, extensionName?: string): string;
 export declare function getRunStateRoot(agentDir?: string): string;
+export declare function getDraftSleepRoot(agentDir?: string): string;
+export declare function getDraftSleepStatePath(agentDir?: string): string;
+export declare function getDraftSleepBatchDir(batchId: string, agentDir?: string): string;
+export declare function getToolReviewRoot(agentDir?: string): string;
+export declare function getToolReviewStatePath(agentDir?: string): string;
+export declare function getToolReviewBatchDir(reviewId: string, agentDir?: string): string;
 export declare function getExtensionRuntimePaths(agentDir?: string): ExtensionRuntimePaths;
 export declare const EXTENSION_RUNTIME_PATHS: ExtensionRuntimePaths;
 export declare function getExtensionSkillsDir(extensionUrl: string): string;

package/dist/lib/paths.js

@@ -12,6 +12,10 @@ export function getAgentDir(env = process.env) {
         ? resolve(env.PI_CODING_AGENT_DIR)
         : join(homedir(), ".pi", "agent");
 }
+export function isAutomaticRecipeReviewEnabled(env = process.env) {
+    const value = env.PI_ACTORS_AUTOMATIC_REVIEW?.trim().toLowerCase();
+    return value === undefined || !["0", "false", "off"].includes(value);
+}
 export function getConfigPath(agentDir = getAgentDir()) {
     return join(agentDir, "tool-registry.json");
 }
@@ -21,6 +25,30 @@ export function getExtensionTmpDir(agentDir = getAgentDir(), extensionName = "pi
 export function getRunStateRoot(agentDir = getAgentDir()) {
     return join(getExtensionTmpDir(agentDir), "runs");
 }
+export function getDraftSleepRoot(agentDir = getAgentDir()) {
+    return join(getExtensionTmpDir(agentDir), "draft-sleep");
+}
+export function getDraftSleepStatePath(agentDir = getAgentDir()) {
+    return join(getDraftSleepRoot(agentDir), "state.json");
+}
+export function getDraftSleepBatchDir(batchId, agentDir = getAgentDir()) {
+    if (!/^[a-f0-9-]{36}$/u.test(batchId)) {
+        throw new Error("Invalid draft sleep batch id.");
+    }
+    return join(getDraftSleepRoot(agentDir), "batches", batchId);
+}
+export function getToolReviewRoot(agentDir = getAgentDir()) {
+    return join(getExtensionTmpDir(agentDir), "tool-review");
+}
+export function getToolReviewStatePath(agentDir = getAgentDir()) {
+    return join(getToolReviewRoot(agentDir), "state.json");
+}
+export function getToolReviewBatchDir(reviewId, agentDir = getAgentDir()) {
+    if (!/^[a-f0-9-]{36}$/u.test(reviewId)) {
+        throw new Error("Invalid tool review id.");
+    }
+    return join(getToolReviewRoot(agentDir), "batches", reviewId);
+}
 export function getExtensionRuntimePaths(agentDir = getAgentDir()) {
     return {
         configPath: getConfigPath(agentDir),

package/dist/lib/recipes-discovery.js

@@ -528,30 +528,38 @@ function templatePreview(value) {
 }
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
-        const id = RecipesReferences.getRecipeIdFromPath(path);
-        const bytes = readFileSync(path);
-        const stat = statSync(path);
-        const config = RecipesReferences.readRawRecipeConfig(path);
-        const resolved = RecipesReferences.readResolvedRecipeConfig(path);
-        const diagnostics = getRecipeConfigDiagnostics(path, resolved);
-        const sourceRun = String(config?.description ?? "").match(/spawn run ([^\s]+)/)?.[1];
-        const preview = templatePreview(config?.template);
-        const riskLabels = getRecipeRiskLabels(resolved);
-        return {
-            id,
-            path,
-            sha256: createHash("sha256").update(bytes).digest("hex"),
-            size: bytes.byteLength,
-            created_at: stat.birthtime.toISOString(),
-            modified_at: stat.mtime.toISOString(),
-            valid: Boolean(resolved),
-            diagnostics,
-            ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
-            ...(config?.description ? { description: config.description } : {}),
-            ...(sourceRun ? { source_run: sourceRun } : {}),
-            ...(config?.async !== undefined ? { async: config.async } : {}),
-            ...(preview ? { template_preview: preview } : {}),
-        };
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const id = RecipesReferences.getRecipeIdFromPath(path);
+            const bytes = readFileSync(path);
+            const fingerprint = createHash("sha256").update(bytes).digest("hex");
+            const stat = statSync(path);
+            const config = RecipesReferences.readRawRecipeConfig(path);
+            const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+            const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+            const after = readFileSync(path);
+            if (createHash("sha256").update(after).digest("hex") !== fingerprint) {
+                continue;
+            }
+            const sourceRun = String(config?.description ?? "").match(/spawn run ([^\s]+)/)?.[1];
+            const preview = templatePreview(config?.template);
+            const riskLabels = getRecipeRiskLabels(resolved);
+            return {
+                id,
+                path,
+                sha256: fingerprint,
+                size: bytes.byteLength,
+                created_at: stat.birthtime.toISOString(),
+                modified_at: stat.mtime.toISOString(),
+                valid: Boolean(resolved),
+                diagnostics,
+                ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
+                ...(config?.description ? { description: config.description } : {}),
+                ...(sourceRun ? { source_run: sourceRun } : {}),
+                ...(config?.async !== undefined ? { async: config.async } : {}),
+                ...(preview ? { template_preview: preview } : {}),
+            };
+        }
+        throw new Error(`Draft changed repeatedly during inventory: ${path}`);
     });
 }
 export function summarizeDiscovery(result) {

package/dist/lib/recipes-usage.d.ts

@@ -1,9 +1,21 @@
 /**
- * Recipe usage metadata helpers
- * Zones: recipe telemetry, muscle-memory cleanup evidence
- * Owns lightweight launch counters for user-owned recipe files
+ * Recipe usage and name-based lineage metadata.
+ * Zones: recipe lineage, launch telemetry, revision history, migration
+ * Owns priority-compatible recipe names and lifetime/revision counters for user recipes.
  */
 export type RecipeLaunchKind = "direct" | "spawn" | "tool";
-export declare function getRecipeUsagePath(path: string): string;
-export declare function readRecipeUsage(path: string): Record<string, unknown> | undefined;
-export declare function recordRecipeLaunch(path: string, now?: Date, kind?: RecipeLaunchKind): boolean;
+export declare function getRecipeUsageIndexPath(recipeRoot: string): string;
+export declare function getRecipeUsageLedgerPath(lineageName: string, recipeRoot: string): string;
+export declare const RECIPE_REVISION_SNAPSHOT_LIMIT = 32;
+export declare function getRecipeRevisionSnapshotPath(lineageName: string, revision: number, recipeRoot: string): string;
+export declare function readRecipeUsage(path: string, recipeRoot?: string): Record<string, unknown> | undefined;
+export declare function ensureRecipeLineage(path: string, now?: Date, recipeRoot?: string): boolean;
+export declare function isCurrentRecipeRevisionReviewed(path: string, recipeRoot?: string): boolean;
+export interface RecipeLaunchRecordOptions {
+    onMutationLockContention?(): void;
+}
+export declare function recordRecipeLaunch(path: string, now?: Date, kind?: RecipeLaunchKind, recipeRoot?: string, options?: RecipeLaunchRecordOptions): boolean;
+export declare function recordRecipeReview(path: string, reviewEpoch: string, now?: Date, recipeRoot?: string): boolean;
+export declare function recordRecipeRollback(path: string, rollbackRevision: number, now?: Date, recipeRoot?: string): boolean;
+export declare function retireRecipeUsage(path: string, recipeRoot?: string): boolean;
+export declare function moveRecipeUsage(fromPath: string, toPath: string, recipeRoot?: string): boolean;