@llblab/pi-actors 0.41.1 → 0.42.0

package/dist/lib/tool-review-lineage.js

@@ -0,0 +1,98 @@
+/**
+ * Tool-review lineage projection.
+ * Zones: approved source coverage, target ownership, lineage transition semantics
+ * Owns deterministic keep/evolve/replace/demote/merge/split grouping; filesystem mutation and recovery remain separate.
+ */
+function sameNames(actual, expected) {
+    return (actual.length === expected.length &&
+        [...actual].sort().every((name, index) => name === [...expected].sort()[index]));
+}
+export function projectToolReviewLineage(plan) {
+    const sources = new Map();
+    for (const source of plan.sources) {
+        if (sources.has(source.name)) {
+            throw new Error(`Duplicate tool review lineage source: ${source.name}`);
+        }
+        sources.set(source.name, source);
+    }
+    const targetsBySource = new Map();
+    for (const target of plan.targets) {
+        if (target.sources.length === 0 || new Set(target.sources).size !== target.sources.length) {
+            throw new Error(`Invalid tool review lineage target sources: ${target.name}`);
+        }
+        for (const sourceName of target.sources) {
+            if (!sources.has(sourceName)) {
+                throw new Error(`Unknown tool review lineage target source: ${sourceName}`);
+            }
+            const entries = targetsBySource.get(sourceName) ?? [];
+            entries.push(target);
+            targetsBySource.set(sourceName, entries);
+        }
+    }
+    const operations = [];
+    const handled = new Set();
+    for (const source of plan.sources) {
+        if (handled.has(source.name))
+            continue;
+        const targets = targetsBySource.get(source.name) ?? [];
+        if (source.action === "keep") {
+            if (targets.length > 0) {
+                throw new Error(`Kept tool owns lineage targets: ${source.name}`);
+            }
+            operations.push({ action: "keep", sources: [source], targets: [] });
+            handled.add(source.name);
+            continue;
+        }
+        if (source.action === "demote" ||
+            source.action === "evolve" ||
+            source.action === "replace") {
+            if (targets.length !== 1 ||
+                targets[0].lineage !== source.action ||
+                !sameNames(targets[0].sources, [source.name])) {
+                throw new Error(`Invalid ${source.action} lineage target: ${source.name}`);
+            }
+            operations.push({
+                action: source.action,
+                sources: [source],
+                targets: [targets[0]],
+            });
+            handled.add(source.name);
+            continue;
+        }
+        if (source.action === "merge") {
+            if (targets.length !== 1 || targets[0].lineage !== "merge") {
+                throw new Error(`Invalid merge lineage target: ${source.name}`);
+            }
+            const target = targets[0];
+            const groupSources = target.sources.map((name) => sources.get(name));
+            if (groupSources.length < 2 ||
+                groupSources.some((candidate) => candidate.action !== "merge") ||
+                !sameNames(target.sources, groupSources.map((candidate) => candidate.name))) {
+                throw new Error(`Invalid merge lineage group: ${target.name}`);
+            }
+            operations.push({ action: "merge", sources: groupSources, targets: [target] });
+            for (const candidate of groupSources)
+                handled.add(candidate.name);
+            continue;
+        }
+        if (source.action === "split") {
+            if (targets.length < 2 ||
+                targets.some((target) => target.lineage !== "split" ||
+                    !sameNames(target.sources, [source.name]))) {
+                throw new Error(`Invalid split lineage targets: ${source.name}`);
+            }
+            operations.push({
+                action: "split",
+                sources: [source],
+                targets: [...targets].sort((left, right) => left.name.localeCompare(right.name)),
+            });
+            handled.add(source.name);
+            continue;
+        }
+        throw new Error(`Unsupported tool review lineage action: ${source.action}`);
+    }
+    if (handled.size !== plan.sources.length) {
+        throw new Error("Tool review lineage projection does not cover every source.");
+    }
+    return operations;
+}

package/dist/lib/tool-review-scheduler.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Automatic active-tool portfolio review admission.
+ * Zones: revision eligibility, immutable thirty-six-tool capture, persisted review state
+ * Owns exact portfolio admission; reviewer execution and recipe mutation remain separate domains.
+ */
+import { type ToolReviewTool } from "./tool-review.ts";
+export declare const TOOL_REVIEW_RESULT_MAX_BYTES: number;
+export interface ToolReviewBatch {
+    inputPath: string;
+    reviewerInputPath: string;
+    reviewId: string;
+    toolNames: string[];
+}
+export interface ToolReviewAdmissionState {
+    approvedPath?: string;
+    attempts: number;
+    failedStage?: string;
+    lastError?: string;
+    lineageJournalPath?: string;
+    inputPath: string;
+    nextAction?: string;
+    phase: "approved" | "captured" | "completed" | "failed" | "launched" | "lineage_pending" | "processing_failed";
+    processingAttempts?: number;
+    reviewerInputPath: string;
+    reviewId: string;
+    runId?: string;
+    toolNames: string[];
+    transactionEvidencePath?: string;
+    updatedAt: string;
+}
+export interface ToolReviewSchedulerDeps extends CaptureToolReviewOptions {
+    delayMs?: number;
+    hasActiveActors(): boolean;
+    launch(batch: ToolReviewBatch): {
+        run: string;
+    };
+    process?(state: ToolReviewAdmissionState): ToolReviewProcessResult;
+}
+export interface ToolReviewProcessResult {
+    approvedPath?: string;
+    error?: string;
+    outcome: "approved" | "pending" | "processing_failed" | "review_failed";
+    stage?: string;
+}
+export interface ToolReviewScheduler {
+    close(): void;
+    schedule(): void;
+}
+export interface CaptureToolReviewOptions {
+    batchRoot?(reviewId: string): string;
+    createReviewId?(): string;
+    now?(): Date;
+    recipeRoot?: string;
+    statePath?: string;
+}
+export declare function listEligibleToolReviewRecipes(recipeRoot?: string, now?: Date): ToolReviewTool[];
+export declare function captureToolReviewBatch(options?: CaptureToolReviewOptions): ToolReviewBatch | undefined;
+export interface ProcessToolReviewDeps {
+    draftRoot?: string;
+    getRunStatus(runId: string): Record<string, unknown>;
+    now?(): Date;
+    recipeRoot?: string;
+}
+export declare function processToolReviewResult(state: ToolReviewAdmissionState, deps: ProcessToolReviewDeps): ToolReviewProcessResult;
+export interface ToolReviewBoundaryResult {
+    outcome: "completed" | "lineage_pending" | "none" | "processing_failed";
+    state?: ToolReviewAdmissionState;
+}
+export declare function applyApprovedToolReviewAtSessionBoundary(options?: {
+    lifecycleHooks?: {
+        onCompleted?(): void;
+        onLineagePending?(): void;
+        onStateLocked?(): void;
+    };
+    now?(): Date;
+    recipeRoot?: string;
+    statePath?: string;
+}): ToolReviewBoundaryResult;
+export declare function createToolReviewScheduler(deps: ToolReviewSchedulerDeps): ToolReviewScheduler;
+export declare function toolReviewRunId(reviewId: string): string;

package/dist/lib/tool-review-scheduler.js

@@ -0,0 +1,494 @@
+/**
+ * Automatic active-tool portfolio review admission.
+ * Zones: revision eligibility, immutable thirty-six-tool capture, persisted review state
+ * Owns exact portfolio admission; reviewer execution and recipe mutation remain separate domains.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import * as Paths from "./paths.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesReferences from "./recipes-references.js";
+import * as RecipesUsage from "./recipes-usage.js";
+import * as ReviewProjection from "./review-projection.js";
+import * as ToolReviewLineage from "./tool-review-lineage.js";
+import * as ToolReviewLineageTransaction from "./tool-review-lineage-transaction.js";
+import * as ToolReviewTransaction from "./tool-review-transaction.js";
+import { findUnsafeRecipeReason } from "./draft-review.js";
+import { parseToolReviewResult, TOOL_REVIEW_THRESHOLD, validateToolReviewInput, validateToolReviewResult, } from "./tool-review.js";
+export const TOOL_REVIEW_RESULT_MAX_BYTES = 16 * 1024 * 1024;
+function sha256(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function readAdmissionState(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function usageOrder(tool) {
+    const firstSeen = tool.usage?.first_seen;
+    return typeof firstSeen === "string" ? firstSeen : "";
+}
+export function listEligibleToolReviewRecipes(recipeRoot = Paths.getRecipeRoot(), now = new Date()) {
+    const discovered = RecipesDiscovery.discoverRecipeSources([
+        { root: recipeRoot, defaultTool: true, mutableUsage: true },
+    ]);
+    return [...discovered.active.values()]
+        .filter((entry) => entry.active && entry.tool && !entry.invalid && !entry.disabled)
+        .flatMap((entry) => {
+        if (!RecipesUsage.ensureRecipeLineage(entry.path, now, recipeRoot))
+            return [];
+        if (RecipesUsage.isCurrentRecipeRevisionReviewed(entry.path, recipeRoot))
+            return [];
+        const recipe = RecipesReferences.readRawRecipeConfig(entry.path);
+        if (!recipe ||
+            entry.riskLabels.includes("risk.secret_touching") ||
+            findUnsafeRecipeReason(recipe))
+            return [];
+        return [{
+                name: entry.id,
+                path: entry.path,
+                recipe,
+                riskLabels: [...entry.riskLabels],
+                sha256: sha256(entry.path),
+                usage: RecipesUsage.readRecipeUsage(entry.path, recipeRoot),
+                valid: true,
+            }];
+    })
+        .sort((left, right) => usageOrder(left).localeCompare(usageOrder(right)) ||
+        left.name.localeCompare(right.name));
+}
+function captureToolReviewBatchLocked(options, recipeRoot, statePath, now) {
+    const state = readAdmissionState(statePath);
+    if (state?.phase === "captured" ||
+        state?.phase === "launched" ||
+        state?.phase === "processing_failed")
+        return undefined;
+    const eligible = listEligibleToolReviewRecipes(recipeRoot, now());
+    if (eligible.length < TOOL_REVIEW_THRESHOLD)
+        return undefined;
+    const reviewId = (options.createReviewId ?? randomUUID)();
+    const inputPath = join((options.batchRoot ?? Paths.getToolReviewBatchDir)(reviewId), "input.json");
+    const tools = eligible.slice(0, TOOL_REVIEW_THRESHOLD);
+    const input = {
+        createdAt: now().toISOString(),
+        reviewId,
+        tools,
+    };
+    const validation = validateToolReviewInput(input);
+    if (!validation.ok) {
+        throw new Error(`Tool review input rejected: ${validation.errors.join("; ")}`);
+    }
+    writeJsonAtomic(inputPath, input);
+    const reviewerInputPath = join(dirname(inputPath), "review-input.json");
+    writeJsonAtomic(reviewerInputPath, ReviewProjection.projectToolReviewInput(input));
+    const toolNames = tools.map((tool) => tool.name);
+    writeJsonAtomic(statePath, {
+        attempts: 0,
+        inputPath,
+        phase: "captured",
+        reviewerInputPath,
+        reviewId,
+        toolNames,
+        updatedAt: input.createdAt,
+    });
+    return { inputPath, reviewerInputPath, reviewId, toolNames };
+}
+export function captureToolReviewBatch(options = {}) {
+    const recipeRoot = options.recipeRoot ?? Paths.getRecipeRoot();
+    const statePath = options.statePath ?? Paths.getToolReviewStatePath();
+    const now = options.now ?? (() => new Date());
+    return withFileMutationLock(statePath, () => captureToolReviewBatchLocked(options, recipeRoot, statePath, now));
+}
+function approvedTargets(input, decisions, recipeRoot) {
+    const targets = new Map();
+    const tools = new Map(input.tools.map((tool) => [tool.name, tool]));
+    const add = (name, path, recipe, lineage, source) => {
+        const existing = targets.get(path);
+        if (existing) {
+            if (lineage !== "merge" || existing.lineage !== "merge") {
+                throw new Error(`Duplicate tool review target: ${path}`);
+            }
+            existing.sources.push(source);
+            return;
+        }
+        const sourceAtPath = input.tools.find((tool) => tool.path === path);
+        if (existsSync(path) && !sourceAtPath) {
+            throw new Error(`Tool review target appeared after capture: ${path}`);
+        }
+        targets.set(path, {
+            expectedSha256: sourceAtPath?.sha256 ?? null,
+            lineage,
+            name,
+            path,
+            recipe,
+            sources: [source],
+        });
+    };
+    for (const decision of decisions) {
+        const source = tools.get(decision.source);
+        if (decision.action === "keep")
+            continue;
+        if (decision.action === "demote") {
+            add(decision.source, join(recipeRoot, "drafts", `${decision.source}.json`), source.recipe, "demote", decision.source);
+            continue;
+        }
+        if (decision.action === "evolve") {
+            const source = tools.get(decision.source);
+            add(decision.target, join(recipeRoot, `${decision.target}.json`), source.recipe, "evolve", decision.source);
+            continue;
+        }
+        if (decision.action === "merge") {
+            const source = tools.get(decision.source);
+            add(decision.target, join(recipeRoot, `${decision.target}.json`), source.recipe, "merge", decision.source);
+            continue;
+        }
+        throw new Error(`${decision.action} requires explicit operator-authored recipe mutation.`);
+    }
+    return [...targets.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+export function processToolReviewResult(state, deps) {
+    if (!state.runId) {
+        return { error: "review run id is unavailable", outcome: "review_failed", stage: "review_state" };
+    }
+    let status;
+    try {
+        status = deps.getRunStatus(state.runId);
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            outcome: "review_failed",
+            stage: "review_state",
+        };
+    }
+    if (status.status === "running")
+        return { outcome: "pending" };
+    if (status.status !== "done" || typeof status.state_dir !== "string") {
+        return {
+            error: `review run ended with status ${String(status.status ?? "unknown")}`,
+            outcome: "review_failed",
+            stage: "review_run",
+        };
+    }
+    let input;
+    let result;
+    try {
+        input = JSON.parse(readFileSync(state.inputPath, "utf8"));
+        const stdoutPath = join(status.state_dir, "stdout.log");
+        if (statSync(stdoutPath).size > TOOL_REVIEW_RESULT_MAX_BYTES) {
+            throw new Error("Tool reviewer output exceeds the approval limit.");
+        }
+        result = ReviewProjection.restoreToolReviewResult(input, parseToolReviewResult(readFileSync(stdoutPath, "utf8")));
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            outcome: "review_failed",
+            stage: "result_parse",
+        };
+    }
+    const validation = validateToolReviewResult(input, result);
+    if (!validation.ok) {
+        return {
+            error: validation.errors.join("; "),
+            outcome: "review_failed",
+            stage: "result_validation",
+        };
+    }
+    try {
+        for (const tool of input.tools) {
+            if (!existsSync(tool.path) || sha256(tool.path) !== tool.sha256) {
+                throw new Error(`Reviewed tool changed after capture: ${tool.name}`);
+            }
+        }
+        const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+        const plan = {
+            createdAt: (deps.now ?? (() => new Date()))().toISOString(),
+            decisions: result.decisions,
+            reviewId: state.reviewId,
+            sources: result.decisions.map((decision) => {
+                const tool = input.tools.find((candidate) => candidate.name === decision.source);
+                return {
+                    action: decision.action,
+                    name: tool.name,
+                    path: tool.path,
+                    sha256: tool.sha256,
+                };
+            }),
+            targets: approvedTargets(input, result.decisions, recipeRoot),
+        };
+        ToolReviewLineage.projectToolReviewLineage(plan);
+        if (Buffer.byteLength(JSON.stringify(plan)) > TOOL_REVIEW_RESULT_MAX_BYTES) {
+            throw new Error("Tool review approved plan exceeds the persistence limit.");
+        }
+        const approvedPath = join(dirname(state.inputPath), "approved.json");
+        writeJsonAtomic(approvedPath, plan);
+        return { approvedPath, outcome: "approved" };
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            outcome: "processing_failed",
+            stage: "approval",
+        };
+    }
+}
+export function applyApprovedToolReviewAtSessionBoundary(options = {}) {
+    const statePath = options.statePath ?? Paths.getToolReviewStatePath();
+    const recipeRoot = options.recipeRoot ?? Paths.getRecipeRoot();
+    return withFileMutationLock(statePath, () => {
+        options.lifecycleHooks?.onStateLocked?.();
+        const state = readAdmissionState(statePath);
+        if (!state)
+            return { outcome: "none" };
+        if (state.phase === "completed") {
+            if (state.approvedPath) {
+                rmSync(join(dirname(state.approvedPath), "quarantine"), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+            return { outcome: "completed", state };
+        }
+        if (state.phase !== "approved" && state.phase !== "lineage_pending") {
+            return { outcome: "none" };
+        }
+        if (!state.approvedPath) {
+            const failed = {
+                ...state,
+                failedStage: "approval_state",
+                lastError: "approved review path is unavailable",
+                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                phase: "processing_failed",
+                updatedAt: (options.now ?? (() => new Date()))().toISOString(),
+            };
+            writeJsonAtomic(statePath, failed);
+            return { outcome: "processing_failed", state: failed };
+        }
+        try {
+            const journalPath = join(dirname(state.approvedPath), "journal.json");
+            const transaction = existsSync(journalPath)
+                ? ToolReviewTransaction.recoverToolReviewTransaction(state.approvedPath, {
+                    now: options.now,
+                    recipeRoot,
+                })
+                : ToolReviewTransaction.applyToolReviewPlan(state.approvedPath, {
+                    now: options.now,
+                    recipeRoot,
+                });
+            if (transaction.phase !== "committed") {
+                const failed = {
+                    ...state,
+                    failedStage: "transaction",
+                    lastError: `tool review transaction remained ${transaction.phase}`,
+                    nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                    phase: "processing_failed",
+                    updatedAt: (options.now ?? (() => new Date()))().toISOString(),
+                };
+                writeJsonAtomic(statePath, failed);
+                return { outcome: "processing_failed", state: failed };
+            }
+            const pending = {
+                ...state,
+                ...(transaction.evidencePath
+                    ? { transactionEvidencePath: transaction.evidencePath }
+                    : {}),
+                phase: "lineage_pending",
+                updatedAt: (options.now ?? (() => new Date()))().toISOString(),
+            };
+            writeJsonAtomic(statePath, pending);
+            options.lifecycleHooks?.onLineagePending?.();
+            let lineage;
+            try {
+                lineage = ToolReviewLineageTransaction.finalizeToolReviewLineage(state.approvedPath, {
+                    now: options.now,
+                    recipeRoot,
+                });
+            }
+            catch (error) {
+                const failedPending = {
+                    ...pending,
+                    failedStage: "lineage",
+                    lastError: error instanceof Error ? error.message : String(error),
+                    nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                };
+                writeJsonAtomic(statePath, failedPending);
+                return { outcome: "lineage_pending", state: failedPending };
+            }
+            const completed = {
+                ...pending,
+                lineageJournalPath: lineage.journalPath,
+                phase: "completed",
+                updatedAt: (options.now ?? (() => new Date()))().toISOString(),
+            };
+            writeJsonAtomic(statePath, completed);
+            options.lifecycleHooks?.onCompleted?.();
+            rmSync(transaction.quarantineDir, { recursive: true, force: true });
+            return { outcome: "completed", state: completed };
+        }
+        catch (error) {
+            const failed = {
+                ...state,
+                failedStage: "transaction",
+                lastError: error instanceof Error ? error.message : String(error),
+                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                phase: "processing_failed",
+                updatedAt: (options.now ?? (() => new Date()))().toISOString(),
+            };
+            writeJsonAtomic(statePath, failed);
+            return { outcome: "processing_failed", state: failed };
+        }
+    });
+}
+export function createToolReviewScheduler(deps) {
+    const statePath = deps.statePath ?? Paths.getToolReviewStatePath();
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    const now = deps.now ?? (() => new Date());
+    let timer;
+    let closed = false;
+    const close = () => {
+        closed = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = undefined;
+    };
+    const schedule = () => {
+        if (closed || timer)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (closed || deps.hasActiveActors())
+                return;
+            try {
+                withFileMutationLock(statePath, () => {
+                    const existing = readAdmissionState(statePath);
+                    if (existing?.phase === "launched" ||
+                        existing?.phase === "processing_failed") {
+                        if (!deps.process || (existing.processingAttempts ?? 0) >= 3)
+                            return;
+                        let processed;
+                        try {
+                            processed = deps.process(existing);
+                        }
+                        catch (error) {
+                            processed = {
+                                error: error instanceof Error ? error.message : String(error),
+                                outcome: "processing_failed",
+                                stage: "result_processing",
+                            };
+                        }
+                        if (processed.outcome === "pending")
+                            return;
+                        if (processed.outcome === "approved") {
+                            writeJsonAtomic(statePath, {
+                                ...existing,
+                                ...(processed.approvedPath ? { approvedPath: processed.approvedPath } : {}),
+                                failedStage: undefined,
+                                lastError: undefined,
+                                nextAction: undefined,
+                                phase: "approved",
+                                updatedAt: now().toISOString(),
+                            });
+                            return;
+                        }
+                        writeJsonAtomic(statePath, {
+                            ...existing,
+                            failedStage: processed.stage ?? "review_result",
+                            lastError: processed.error ?? "automatic tool reviewer failed",
+                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                            phase: processed.outcome === "processing_failed"
+                                ? "processing_failed"
+                                : "failed",
+                            ...(processed.outcome === "processing_failed"
+                                ? { processingAttempts: (existing.processingAttempts ?? 0) + 1 }
+                                : { runId: undefined }),
+                            updatedAt: now().toISOString(),
+                        });
+                        return;
+                    }
+                    if (existing?.phase === "captured" ||
+                        existing?.phase === "failed") {
+                        if (existing.attempts >= 3)
+                            return;
+                        try {
+                            const launched = deps.launch({
+                                inputPath: existing.inputPath,
+                                reviewerInputPath: existing.reviewerInputPath,
+                                reviewId: existing.reviewId,
+                                toolNames: existing.toolNames,
+                            });
+                            writeJsonAtomic(statePath, {
+                                ...existing,
+                                attempts: existing.attempts + 1,
+                                phase: "launched",
+                                runId: launched.run,
+                                updatedAt: now().toISOString(),
+                            });
+                        }
+                        catch (error) {
+                            writeJsonAtomic(statePath, {
+                                ...existing,
+                                attempts: existing.attempts + 1,
+                                failedStage: "review_launch",
+                                lastError: error instanceof Error ? error.message : String(error),
+                                nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                                phase: "failed",
+                                updatedAt: now().toISOString(),
+                            });
+                        }
+                        return;
+                    }
+                    if (existing && existing.phase !== "completed")
+                        return;
+                    let batch;
+                    try {
+                        batch = captureToolReviewBatchLocked(deps, recipeRoot, statePath, now);
+                        if (!batch)
+                            return;
+                        const launched = deps.launch(batch);
+                        writeJsonAtomic(statePath, {
+                            attempts: 1,
+                            inputPath: batch.inputPath,
+                            phase: "launched",
+                            reviewerInputPath: batch.reviewerInputPath,
+                            reviewId: batch.reviewId,
+                            runId: launched.run,
+                            toolNames: batch.toolNames,
+                            updatedAt: now().toISOString(),
+                        });
+                    }
+                    catch (error) {
+                        if (!batch)
+                            return;
+                        writeJsonAtomic(statePath, {
+                            attempts: 1,
+                            failedStage: "review_launch",
+                            inputPath: batch.inputPath,
+                            lastError: error instanceof Error ? error.message : String(error),
+                            nextAction: "message to=tool:pi-actors type=review.retry body={\"scope\":\"tool\"}",
+                            phase: "failed",
+                            reviewerInputPath: batch.reviewerInputPath,
+                            reviewId: batch.reviewId,
+                            toolNames: batch.toolNames,
+                            updatedAt: now().toISOString(),
+                        });
+                    }
+                });
+            }
+            catch {
+                /* another session owns the durable admission transition */
+            }
+        }, deps.delayMs ?? 50);
+        timer.unref?.();
+    };
+    return { close, schedule };
+}
+export function toolReviewRunId(reviewId) {
+    return `tool-review-${reviewId}`;
+}